Hello, I'm Alexey Bychkadov, and I'm talking about
unentangling projects and repositories,
or maybe entangling them, depending on how you look at that.
So that's going to be a short workflow note.
I work as a researcher,
so there are three main components to my work, I guess.
First, I think, so I try to come up with new ideas,
and that usually results in some collection of notes I have.
Second, I try things out, so it usually means that I write code.
And third, I communicate, so I prepare papers,
presentations, memos, and so on and so forth.
And so the workflow problem I had is
sometimes all this does not really fit
into a concept of a single repository per project,
so I might want to have, for example,
a source code in one repository, and then I would like to have a paper
in another one, and then I want to have a collection of notes somewhere
unrelated to those two. And yeah,
Emacs is pretty good at supporting your workflows, and I figured I should
share what I use and what works for me.
So,
from the technical perspective, things are
pretty easy, so I use a collection of pretty standard components
of Emacs, so it's a projectile org-mode with its capture templates and other
things. Then I sustain a collection of notes in something
that is called org-roam, which is, well, essentially, it's a glorified
collection of org-mode files. Then I use directory
local variables, maybe a ctext to jump through the source code,
and very, very little Elisp glue to make this
all work, but that's not really rocket science.
So that's the workflow I would like to talk about today.
So, what I mean by all that,
it's pretty straightforward to make
it easy to jump around a single repository in Emacs.
Now, I have Doom Emacs, but that's not really specific to Doom.
That'll work in any Emacs configuration.
Well, kbindings might be
different, but that's not the point, I guess, for the workflow. So, if I hit space
two times, I have all the list of files within my project.
So, if I create a couple of custom shortcuts,
so if I press a magic button,
hyperlp, don't worry about hyperkey, so I want it to have a
modifier key all to myself, so that would, no program
on my computer would use that except Emacs, and Emacs would
use that only when I tell it to, so I have a hyperkey instead of caps lock, that's pretty easy
to do in GNU Linux system. So,
when I press this magic keys, I have a menu that's a normal
kbinding, yeah, essentially in Emacs, and
if I hit, for example, R, I end up in a readme file within
this specific repository I was sitting in, right, so if I want to document something
real quick, I go to the readme file. Then I could have, I could
go to a changelog file, right, so I have a list of changes
and the way it works, usually, for example, if I'm working on some code,
I created a couple of dummy files in there, so
I'm working on some code, and then I implemented something, and I can
just use the org mode capture
mechanisms to keep track of what
I want to discuss with colleagues next time, for example, I could just hit
capture repo specific changelog entry
and I implemented a feature
and I can continue working
without this context switching, and then if I want to go to the changelog,
well, it is there, and next time I talk
to the colleagues about the source code, I can open the changelog and go through entries one by one
and discuss what I have implemented last time.
I could go to project specific
to, sorry, to repo specific to-do list, and I have
a list of to-dos that would live within a repository, and
for example, I could have a high-level structure here,
work distribution between team members and other things that sort of face
the world, so to speak, and of course,
there are very many ways to jump through the source code conveniently,
I ended up not using language servers, I used a special program called
ctags, and so the way it works is just I call
projectile regenerate tags, and it creates the special
tags file within the repository,
and then I can, again, run
I usually just hit a single keystroke,
and here is all the symbols that are there in my
source code, regardless of the language, right, so I can jump to the main function
and that'll be a C++ file, or I could go to the super function, which I
had in my Python file, and this comes in pretty convenient if I have
a mixture of languages, so sometimes I can have some algorithm-specific code
in Julia, and then I can have some Python glue within the same
source code repository, and it makes it really convenient to jump
between all of those, right,
but I have a few problems here,
just to give you a little bit of context, for example, here is the
a real project that corresponds to a real paper,
I have a single note about that project,
where I keep all the things related to that project here, but that's a private
note, so for example, again, I hit a special key that
invokes my org-roam function that gives me a menu of my
notes, and so here is the paper,
essentially, and I can have a paper timeline, and I can
have a list of all the dates, what happened to the paper, with links
to my email, right, so for example, if I hit this link,
that'll open a specific email, and that doesn't work outside of my
computer, it doesn't make any sense to keep it in the outer world-facing
repository, for example, so that's something to myself, right, sometimes I want
to have, like, this list of
working notes, right, that contain, like, for example,
I might produce this kind of things for internal discussion, right,
it has some marks, it has some margin notes, and things like that,
maybe, again, health-based ideas that may or may not end up
in a repository, in a final paper, or in a source code,
but still I want to have it somewhere, and
well, long story short, I need a project folder
that would be unrelated to the source code, or
to the source code repository, or to the paper itself,
or a final report, right, and one way,
as usual, there are multiple ways to achieve that, I suppose, and one way to do that
is, so, I create
a special folder within my org-roam
storage, so it's a special folder outside of any
repositories that got backed up to my hard drive, with
certain redundancy, but I don't really need, like, version control, full-blown
version control for that, I'm okay with just having a couple of backups, right, so
this is the folder you see here, so pkb stands for personal knowledge
base, and I have a folder, project notes in there, right, so
and, how does it work, so I have a
folder per project in there, essentially, and here I can
have all the stuff that is, that kind of belongs to me, and I
do not publish it anywhere, and then
for example, a source code
repository knows about that folder, and a paper repository
knows about that folder, and anything else that might live in separate
places all over my system can know about that folder, and how do I achieve that,
well, essentially, this is one of the use cases for the directory
local variables, right, so, for example,
how does it work from the user perspective, so if I hit a special
key, oh, sorry, if I hit a special key
that would be open project
and then, for example,
org mode file, right, so this is my personal notes about the emacs conf, not
specifically about this very talk, but I can have, you know,
half-baked ideas here, again, presentation tools, and things like that,
and how does that happen if we try to
look at the code, the elisp magic here, what
is happening is, it's just a couple lines of code, in fact, so
let me just press control, help
key, and so the key I was
pressing is open project org mode file, and so
what we see here, there is a single, so it's just a call to a find
file function, so I open that file, and there is a special function that
figures out what is the, like, umbrella
project notes file, and that's, again, that's very easy, so
essentially, if a variable describing this
the name for that project is defined, then
I use that as my project folder name, if not, I take the project name from the
project towel, and well, that's pretty much it,
and how do I define this
variable is, essentially, there is this
magical file in a folder called dear locals elisp,
and I just put it there, and then, whenever I
go into that folder, or any of its children folders, I get this
variable defined, and that's pretty much it, that's how
it works for me.
I guess one thing that I wanted to emphasize
specifically about that is, of course, it's
time tracking, right, so what I find especially important when I work in
something, and I want to clock time, I usually do not want
this information to be in a source code repository or in a paper repository
because other people I work with will not be particularly happy about that
especially if most of them do not use Emacs, and they will see
this long list of org clocked data, and that doesn't look
nice in a plain text format, so what I usually
do if I want to clock in some time, and then later analyze what I've
been spending time on, so I go to my org mode file
and I go to my current project
to-dos, and I clock in there, and that's
how it works, so again
what comes in handy if I hit ctrl-o, I just go
back to the file I jumped from, so that's also
pretty handy, so again, no rocket science in there
so I create a directory local variable that helps me
to figure out what umbrella project does
this particular folder belongs to, and this way
I make Emacs aware of, for example, facts like so this
source code belongs to that project, and this repository with the paper
also belongs to that project, and I can have capture templates
that would save my notes into my private notes
file, and my to-dos go to my private note files
and so on and so forth, so I find it pretty simple, but
that really helps to reduce this context
switching, and I don't believe it allows me to save time
but that probably helps me to stay focused, and this
is what is really important, I believe, so thank you
very much, and if you have any comments or suggestions to that, please do jump
into the discussion, yeah, after the talk, thank you.