path: root/2023/captions/emacsconf-2023-unentangling--unentangling-projects-and-repos--alexey-bochkarev--main.vtt

WEBVTT

00:00.000 --> 00:04.000
Hello, I'm Alexey Bychkadov, and I'm talking about

00:04.000 --> 00:07.000
unentangling projects and repositories,

00:07.000 --> 00:10.000
or maybe entangling them, depending on how you look at that.

00:12.000 --> 00:15.000
So that's going to be a short workflow note.

00:15.000 --> 00:19.000
I work as a researcher,

00:19.000 --> 00:23.000
so there are three main components to my work, I guess.

00:23.000 --> 00:27.000
First, I think, so I try to come up with new ideas,

00:27.000 --> 00:31.000
and that usually results in some collection of notes I have.

00:31.000 --> 00:35.000
Second, I try things out, so it usually means that I write code.

00:35.000 --> 00:39.000
And third, I communicate, so I prepare papers,

00:39.000 --> 00:43.000
presentations, memos, and so on and so forth.

00:43.000 --> 00:47.000
And so the workflow problem I had is

00:47.000 --> 00:51.000
sometimes all this does not really fit

00:51.000 --> 00:55.000
into a concept of a single repository per project,

00:55.000 --> 00:59.000
so I might want to have, for example,

00:59.000 --> 01:03.000
a source code in one repository, and then I would like to have a paper

01:03.000 --> 01:07.000
in another one, and then I want to have a collection of notes somewhere

01:07.000 --> 01:11.000
unrelated to those two. And yeah,

01:11.000 --> 01:15.000
Emacs is pretty good at supporting your workflows, and I figured I should

01:15.000 --> 01:19.000
share what I use and what works for me.

01:19.000 --> 01:23.000
So,

01:23.000 --> 01:27.000
from the technical perspective, things are

01:27.000 --> 01:31.000
pretty easy, so I use a collection of pretty standard components

01:31.000 --> 01:35.000
of Emacs, so it's a projectile org-mode with its capture templates and other

01:35.000 --> 01:39.000
things. Then I sustain a collection of notes in something

01:39.000 --> 01:43.000
that is called org-roam, which is, well, essentially, it's a glorified

01:43.000 --> 01:47.000
collection of org-mode files. Then I use directory

01:47.000 --> 01:51.000
local variables, maybe a ctext to jump through the source code,

01:51.000 --> 01:55.000
and very, very little Elisp glue to make this

01:55.000 --> 01:59.000
all work, but that's not really rocket science.

01:59.000 --> 02:03.000
So that's the workflow I would like to talk about today.

02:03.000 --> 02:07.000
So, what I mean by all that,

02:07.000 --> 02:11.000
it's pretty straightforward to make

02:11.000 --> 02:15.000
it easy to jump around a single repository in Emacs.

02:15.000 --> 02:19.000
Now, I have Doom Emacs, but that's not really specific to Doom.

02:19.000 --> 02:23.000
That'll work in any Emacs configuration.

02:23.000 --> 02:27.000
Well, kbindings might be

02:27.000 --> 02:31.000
different, but that's not the point, I guess, for the workflow. So, if I hit space

02:31.000 --> 02:35.000
two times, I have all the list of files within my project.

02:35.000 --> 02:39.000
So, if I create a couple of custom shortcuts,

02:39.000 --> 02:43.000
so if I press a magic button,

02:43.000 --> 02:47.000
hyperlp, don't worry about hyperkey, so I want it to have a

02:47.000 --> 02:51.000
modifier key all to myself, so that would, no program

02:51.000 --> 02:55.000
on my computer would use that except Emacs, and Emacs would

02:55.000 --> 02:59.000
use that only when I tell it to, so I have a hyperkey instead of caps lock, that's pretty easy

02:59.000 --> 03:03.000
to do in GNU Linux system. So,

03:03.000 --> 03:07.000
when I press this magic keys, I have a menu that's a normal

03:07.000 --> 03:11.000
kbinding, yeah, essentially in Emacs, and

03:11.000 --> 03:15.000
if I hit, for example, R, I end up in a readme file within

03:15.000 --> 03:19.000
this specific repository I was sitting in, right, so if I want to document something

03:19.000 --> 03:23.000
real quick, I go to the readme file. Then I could have, I could

03:23.000 --> 03:27.000
go to a changelog file, right, so I have a list of changes

03:27.000 --> 03:31.000
and the way it works, usually, for example, if I'm working on some code,

03:31.000 --> 03:35.000
I created a couple of dummy files in there, so

03:35.000 --> 03:39.000
I'm working on some code, and then I implemented something, and I can

03:39.000 --> 03:43.000
just use the org mode capture

03:43.000 --> 03:47.000
mechanisms to keep track of what

03:47.000 --> 03:51.000
I want to discuss with colleagues next time, for example, I could just hit

03:51.000 --> 03:55.000
capture repo specific changelog entry

03:55.000 --> 03:59.000
and I implemented a feature

03:59.000 --> 04:03.000
and I can continue working

04:03.000 --> 04:07.000
without this context switching, and then if I want to go to the changelog,

04:07.000 --> 04:11.000
well, it is there, and next time I talk

04:11.000 --> 04:15.000
to the colleagues about the source code, I can open the changelog and go through entries one by one

04:15.000 --> 04:19.000
and discuss what I have implemented last time.

04:19.000 --> 04:23.000
I could go to project specific

04:23.000 --> 04:27.000
to, sorry, to repo specific to-do list, and I have

04:27.000 --> 04:31.000
a list of to-dos that would live within a repository, and

04:31.000 --> 04:35.000
for example, I could have a high-level structure here,

04:35.000 --> 04:39.000
work distribution between team members and other things that sort of face

04:39.000 --> 04:43.000
the world, so to speak, and of course,

04:43.000 --> 04:47.000
there are very many ways to jump through the source code conveniently,

04:47.000 --> 04:51.000
I ended up not using language servers, I used a special program called

04:51.000 --> 04:55.000
ctags, and so the way it works is just I call

04:55.000 --> 04:59.000
projectile regenerate tags, and it creates the special

04:59.000 --> 05:03.000
tags file within the repository,

05:03.000 --> 05:07.000
and then I can, again, run

05:07.000 --> 05:11.000
I usually just hit a single keystroke,

05:11.000 --> 05:15.000
and here is all the symbols that are there in my

05:15.000 --> 05:19.000
source code, regardless of the language, right, so I can jump to the main function

05:19.000 --> 05:23.000
and that'll be a C++ file, or I could go to the super function, which I

05:23.000 --> 05:27.000
had in my Python file, and this comes in pretty convenient if I have

05:27.000 --> 05:31.000
a mixture of languages, so sometimes I can have some algorithm-specific code

05:31.000 --> 05:35.000
in Julia, and then I can have some Python glue within the same

05:35.000 --> 05:39.000
source code repository, and it makes it really convenient to jump

05:39.000 --> 05:43.000
between all of those, right,

05:43.000 --> 05:47.000
but I have a few problems here,

05:47.000 --> 05:51.000
just to give you a little bit of context, for example, here is the

05:51.000 --> 05:55.000
a real project that corresponds to a real paper,

05:55.000 --> 05:59.000
I have a single note about that project,

05:59.000 --> 06:03.000
where I keep all the things related to that project here, but that's a private

06:03.000 --> 06:07.000
note, so for example, again, I hit a special key that

06:07.000 --> 06:11.000
invokes my org-roam function that gives me a menu of my

06:11.000 --> 06:15.000
notes, and so here is the paper,

06:15.000 --> 06:19.000
essentially, and I can have a paper timeline, and I can

06:19.000 --> 06:23.000
have a list of all the dates, what happened to the paper, with links

06:23.000 --> 06:27.000
to my email, right, so for example, if I hit this link,

06:27.000 --> 06:31.000
that'll open a specific email, and that doesn't work outside of my

06:31.000 --> 06:35.000
computer, it doesn't make any sense to keep it in the outer world-facing

06:35.000 --> 06:39.000
repository, for example, so that's something to myself, right, sometimes I want

06:39.000 --> 06:43.000
to have, like, this list of

06:43.000 --> 06:47.000
working notes, right, that contain, like, for example,

06:47.000 --> 06:51.000
I might produce this kind of things for internal discussion, right,

06:51.000 --> 06:55.000
it has some marks, it has some margin notes, and things like that,

06:55.000 --> 06:59.000
maybe, again, health-based ideas that may or may not end up

06:59.000 --> 07:03.000
in a repository, in a final paper, or in a source code,

07:03.000 --> 07:07.000
but still I want to have it somewhere, and

07:07.000 --> 07:11.000
well, long story short, I need a project folder

07:11.000 --> 07:15.000
that would be unrelated to the source code, or

07:15.000 --> 07:19.000
to the source code repository, or to the paper itself,

07:19.000 --> 07:23.000
or a final report, right, and one way,

07:23.000 --> 07:27.000
as usual, there are multiple ways to achieve that, I suppose, and one way to do that

07:27.000 --> 07:31.000
is, so, I create

07:31.000 --> 07:35.000
a special folder within my org-roam

07:35.000 --> 07:39.000
storage, so it's a special folder outside of any

07:39.000 --> 07:43.000
repositories that got backed up to my hard drive, with

07:43.000 --> 07:47.000
certain redundancy, but I don't really need, like, version control, full-blown

07:47.000 --> 07:51.000
version control for that, I'm okay with just having a couple of backups, right, so

07:51.000 --> 07:55.000
this is the folder you see here, so pkb stands for personal knowledge

07:55.000 --> 07:59.000
base, and I have a folder, project notes in there, right, so

07:59.000 --> 08:03.000
and, how does it work, so I have a

08:03.000 --> 08:07.000
folder per project in there, essentially, and here I can

08:07.000 --> 08:11.000
have all the stuff that is, that kind of belongs to me, and I

08:11.000 --> 08:15.000
do not publish it anywhere, and then

08:15.000 --> 08:19.000
for example, a source code

08:19.000 --> 08:23.000
repository knows about that folder, and a paper repository

08:23.000 --> 08:27.000
knows about that folder, and anything else that might live in separate

08:27.000 --> 08:31.000
places all over my system can know about that folder, and how do I achieve that,

08:31.000 --> 08:35.000
well, essentially, this is one of the use cases for the directory

08:35.000 --> 08:39.000
local variables, right, so, for example,

08:39.000 --> 08:43.000
how does it work from the user perspective, so if I hit a special

08:43.000 --> 08:47.000
key, oh, sorry, if I hit a special key

08:47.000 --> 08:51.000
that would be open project

08:51.000 --> 08:55.000
and then, for example,

08:55.000 --> 08:59.000
org mode file, right, so this is my personal notes about the emacs conf, not

08:59.000 --> 09:03.000
specifically about this very talk, but I can have, you know,

09:03.000 --> 09:07.000
half-baked ideas here, again, presentation tools, and things like that,

09:07.000 --> 09:11.000
and how does that happen if we try to

09:11.000 --> 09:15.000
look at the code, the elisp magic here, what

09:15.000 --> 09:19.000
is happening is, it's just a couple lines of code, in fact, so

09:19.000 --> 09:23.000
let me just press control, help

09:23.000 --> 09:27.000
key, and so the key I was

09:27.000 --> 09:31.000
pressing is open project org mode file, and so

09:31.000 --> 09:35.000
what we see here, there is a single, so it's just a call to a find

09:35.000 --> 09:39.000
file function, so I open that file, and there is a special function that

09:39.000 --> 09:43.000
figures out what is the, like, umbrella

09:43.000 --> 09:47.000
project notes file, and that's, again, that's very easy, so

09:47.000 --> 09:51.000
essentially, if a variable describing this

09:51.000 --> 09:55.000
the name for that project is defined, then

09:55.000 --> 09:59.000
I use that as my project folder name, if not, I take the project name from the

09:59.000 --> 10:03.000
project towel, and well, that's pretty much it,

10:03.000 --> 10:07.000
and how do I define this

10:07.000 --> 10:11.000
variable is, essentially, there is this

10:11.000 --> 10:15.000
magical file in a folder called dear locals elisp,

10:15.000 --> 10:19.000
and I just put it there, and then, whenever I

10:19.000 --> 10:23.000
go into that folder, or any of its children folders, I get this

10:23.000 --> 10:27.000
variable defined, and that's pretty much it, that's how

10:27.000 --> 10:31.000
it works for me.

10:31.000 --> 10:35.000
I guess one thing that I wanted to emphasize

10:35.000 --> 10:39.000
specifically about that is, of course, it's

10:39.000 --> 10:43.000
time tracking, right, so what I find especially important when I work in

10:43.000 --> 10:47.000
something, and I want to clock time, I usually do not want

10:47.000 --> 10:51.000
this information to be in a source code repository or in a paper repository

10:51.000 --> 10:55.000
because other people I work with will not be particularly happy about that

10:55.000 --> 10:59.000
especially if most of them do not use Emacs, and they will see

10:59.000 --> 11:03.000
this long list of org clocked data, and that doesn't look

11:03.000 --> 11:07.000
nice in a plain text format, so what I usually

11:07.000 --> 11:11.000
do if I want to clock in some time, and then later analyze what I've

11:11.000 --> 11:15.000
been spending time on, so I go to my org mode file

11:15.000 --> 11:19.000
and I go to my current project

11:19.000 --> 11:23.000
to-dos, and I clock in there, and that's

11:23.000 --> 11:27.000
how it works, so again

11:27.000 --> 11:31.000
what comes in handy if I hit ctrl-o, I just go

11:31.000 --> 11:35.000
back to the file I jumped from, so that's also

11:35.000 --> 11:39.000
pretty handy, so again, no rocket science in there

11:39.000 --> 11:43.000
so I create a directory local variable that helps me

11:43.000 --> 11:47.000
to figure out what umbrella project does

11:47.000 --> 11:51.000
this particular folder belongs to, and this way

11:51.000 --> 11:55.000
I make Emacs aware of, for example, facts like so this

11:55.000 --> 11:59.000
source code belongs to that project, and this repository with the paper

11:59.000 --> 12:03.000
also belongs to that project, and I can have capture templates

12:03.000 --> 12:07.000
that would save my notes into my private notes

12:07.000 --> 12:11.000
file, and my to-dos go to my private note files

12:11.000 --> 12:15.000
and so on and so forth, so I find it pretty simple, but

12:15.000 --> 12:19.000
that really helps to reduce this context

12:19.000 --> 12:23.000
switching, and I don't believe it allows me to save time

12:23.000 --> 12:27.000
but that probably helps me to stay focused, and this

12:27.000 --> 12:31.000
is what is really important, I believe, so thank you

12:31.000 --> 12:35.000
very much, and if you have any comments or suggestions to that, please do jump

12:35.000 --> 12:39.000
into the discussion, yeah, after the talk, thank you.