Thomas Letan's Blog - git

Using git maintenance with Encrypted SSH Keys

February 18, 2024

Using `git maintenance` with Encrypted SSH Keys

This year, I went to FOSDEM 2024 . It was nice and ~~cosy~~ crowded, and I really enjoyed my time there. The very last talk I could attend to before having to leave for the train station was “So You Think You Know Git ” by Scott Chacon . If you haven’t already, go and watch it. It is a very good and educational presentation. You will learn what git blame -C -C -C does and never be the same.

Another takeaway for me was git maintenance. git maintenance allows running in the background a set of tasks which optimize commands like git add and git fetch for a responsive user experience. I mean, count me in! Our git repository at $WORK has become fairly big over the yearsNot mono-repo big yet, but still big enough to make git fetch --all --prune feels… well, unresponsive. .

So, when I came back to work the next day, I run the magic command the speaker had mentionedFollowing a petition from the Internet , my terminal prompt is ;. .

; git maintenance start

This created a bunch of user systemd services and timers which I decided to run immediately to test that everything was working correctly, starting with the hourly service responsible for prefetching remote branches.

; systemctl --user start git-maintenance@hourly.service

Unfortunately, this did not work out, and for predictable reasons.

; systemctl --user status git-maintenance@hourly.service
(...)
systemd[1706]: Starting Optimize Git repositories data...
git[76228]: git@gitlab.com: Permission denied (publickey).
git[76226]: error: failed to prefetch remotes
git[76226]: error: task 'prefetch' failed
systemd[1706]: git-maintenance@hourly.service: Main process exited, code=exited, status=>
systemd[1706]: git-maintenance@hourly.service: Failed with result 'exit-code'.
systemd[1706]: Failed to start Optimize Git repositories data.

The culprit here is the fact I am using an encrypted SSH key to connect to Gitlab where our repository is hosted and out of the box the scripts run by git-maintenance have now way to use them. This is because git-maintenance is not aware of the existence of the SSH agent running on my laptop.

The solution can be read in the Man page of git-maintenance:

(…) any customization should be done by creating a drop-in file, i.e. a .conf suffixed file in the ~/.config/systemd/user/git-maintenance@.service.d directory.

I didn’t know this general purpose trick which should work for any systemd service running on a Linux machine! Thanks, anonymous technical writer who took the time to contribute to this Man page.

And indeed, creating a file named 10-ssh.confThe prefix number is as important as the .conf suffix mentioned in the git-maintenance Man page for systemd to load the drop-in file. in ${HOME}/.config/systemd/user/git-maintenance@.service.d/ to set the SSH_AUTH_SOCK environment variable solved my issue. Its value depends on your personal setup. In my case, I am using the systemd ssh-agent.service user unit.

; systemctl --user show ssh-agent.service | grep Environment=SSH_AUTH_SOCK
Environment=SSH_AUTH_SOCK=/run/user/1000/ssh-agent.socket

We replicate this in our 10-ssh.conf.

[Service]
Environment=SSH_AUTH_SOCK=/run/user/1000/ssh-agent.socket

And we are done! This time, executing the service manually will work (assuming the necessary encrypted key has been ssh-add to the agent).

; systemctl --user daemon-reload
; systemctl --user start git-maintenance@hourly.service
; systemctl --user status git-maintenance@hourly.service
(...)
systemd[1706]: Starting Optimize Git repositories data...
systemd[1706]: Finished Optimize Git repositories data.

Patch Dependencies for Stacked Git

January 26, 2023

Patch Dependencies for Stacked Git

git opinions

Every time I catch myself thinking about dependencies between changeset of a software project, the fascinating field of patch theories comes to my mind.

A “patch theory” usually refers to the mathematical foundation behind the data model of so-called Patch-based DVCS like Darcs and Pijul. More precisely, a patch theory is an encoding of the state of a repository, equipped with operations (gathered in so-called patches, not to be confused with GNU diff patches) one can do to this state. For instance, my rough understanding of Pijul’s patch theory is that a repository is an oriented graph of lines, and a patch is a set of operations onto this graph.

An interesting aspect of patch theory is that it requires a partial order for its patches, from which a Patch-based DVCS derives a dependency graph. In a nutshell, a patch $P$ depends on the patches which are responsible for the presence of the lines that $P$ modifies.

I have always found this idea of a dependency graph for the patches of a repository fascinating, because I though it would be a very valuable tool in the context of software development.

I wanted to slightly change the definition of what a patch dependency is, though. See, the partial order of Darcs and Pijul focus on syntactic dependencies: the relation between lines in text files. They need that to reconstruct these text files in the file system of their users. As a software developers writing these text files, I quickly realized these dependencies were of little interest to me, though. What I wanted to be able to express was that a feature introduced by a patch $P$ relied on a fix introduced by a patch $P'$ .

I have experimented with Darcs and Pijul quite a bit, with this idea stuck in the back of my mind. At the end of this journey, I convinced myselfI am not trying to convince you, per say. This is a very personal and subjective feedback, it does not mean someone else couldn't reach a different conclusion. (1) this beautiful idea I had simply could not scale, and (2) neither I nor our industry is ready to give up on the extensive ecosystem that has been built on top of git just yet. As a consequence, my interest in Patch-based DVCS decreased sensibly.

Until very recently, that is. I got reminded of the appeal of a dependency graph for changesets when I started adopted a Gitlab workflow centered around Stacked Git and smaller, sometimes interdependent MRs.

A manually curated graph dependency for a whole repository is not practical, but what about my local queue of patches, patiently waiting to be integrated into the upstream repository I am contributing too? Not only does it look like a more approachable task, it could make synchronizing my stacked MRs a lot easier.

The workflow I have in mind would proceed as follows.

Stacked Git’s new and edit commands could be extended to let developers declare dependencies between their patches. It would be the commands’ responsibility to enforce the wellfoundness of the dependency graph (e.g., prevent the introduction of cycles in the graph, and maybe diamonds tooAt least in a first version. There is definitely value in being able to work with two independent patches in conjunction with a third one that needs them both. That being said, our goal here is to organize our work locally, and if it is made easier by declaring artificial dependency, this is a pragmatic sacrifice I am personally willing to make. ).
The series command could be improved to display the resulting dependency graph.
push and pop would automatically take care (pushing or popping) of the selected patch(es) dependencies.
Ideally, Stacked Git would get a new command prepare <PATCH NAME> which would pop every patches applied, then only only push <PATCH NAME> and its dependencies (in the reverse order). Developers could fix conflicts if need be. That is, Stacked Git would not be responsible for the consistency or correctness of the dependency graph.
Stacked Git could get commands to detect potential issues with the dependency graph specified by the developer (mostly consisting in dry-run of prepare to check if it would lead to conflicts).

Because what we want is semantic dependencies, not syntactic dependencies between patches, I really think it makes a lot of sense to completely delegate the dependencies declaration to the developerFurther versions of Stacked Git could explore computing the dependency graph automatically, similarly to what Git does. But I think that if Darcs and Pijul told us anything, it's that this computation is far from being trivial. . The very mundane example that convinced me is the CHANGELOG file any mature software project ends up maintaining. If the contribution guidelines require to modify the CHANGELOG file in the same commit as a feature is introduced, then the patches to two independent features will systematically conflict. This does not mean, from my patch queue perspective, I should be forced to pop the first commit before starting to work on the second one. It just means that when I call stg prepare, I can have to fix a conflict, but fixing Git conflicts is part of the job after allAnd we have tools to help us. I wonder to which extends git rerere could save the day in some cases, for instance. . If for some reasons solving a conflict proves to be too cumbersome, I can always acknowledge that, and declare a new dependency to the appropriate patch. It only means I and my reviewers will be constrained a bit more than expected when dealing with my stack of MRs.

I am under the impression that this model extends quite nicely the current way Stacked Git is working. To its core, it extends its data model to constraint a bit push and pop, and empowers developers to organize a bit its local mess.

How I Keep Using Stacked Git at $WORK

January 16, 2023

How I Keep Using Stacked Git at `$WORK`

git workflow

One year ago, I have published an article summarizing my experience using Stacked Git at $WORK. Twelve months later, enough has changed to motivate a spin-off piece.

Stacked Git is Fast

Firstly, it is important to state that my main complaint about Stacked Git is now a thing of the pastFor fairness, I have removed the related section in my previous write-up. ! Stacked Git does not feel slow anymore, and far from it. This is because Stacked Git 2.0 has been rewritten in Rust . While RiiR (Rewrite it in Rust) is a running meme on the Internet, in this particular case, the result is very exciting.

Thanks to the performance boost, my Zsh prompt does not take 0.1s to appear!

Speaking of Zsh prompt, basically what I ended up displaying is (<TOP PATCH NAME> <APPLIED PATCHES COUNT>/<PATCHSET SIZE> <HIDDEN PATCHES COUNT). For instance, (fix-1337 1/2 3).

In case you want to take inspiration in my somewhat working configuration, here is the snippet of interest.

local series_top="$(stg top 2> /dev/null)"
local total="$(stg series 2> /dev/null | wc -l)"
local hidden="$(stg series --hidden 2> /dev/null | wc -l)"

if [[ "${total}" -gt 0 ]]; then
    local not_applied="$(stg series | grep -E '^-' | wc -l)"
    local applied="$(($total - $not_applied))"

    if [[ -z "${series_top}" ]]; then
        series_top="·"
    fi

    echo -n "(${status_color}${series_top} ${applied}/${total} ${hidden})"
    echo -n "  ($(current_branch))"
fi

Branchless Workflow

Last year, I was using Stacked Git on top of git branches. More precisely, I had one branch for each (stack of) Merge Request. It worked well, because my typical MR counted 3 to 4 commits in average.

Fast forward today, and things have changed on this front too. In a nutshell, I have become a “one commit per MR” maximalist of sortIt goes without saying that this approach comes with its set of drawbacks too. During the past year, I’ve pushed fairly large commits which could have been split into several smaller ones, for the sake of keeping my “one commit per MR” policy. I have also had to manage large stacks of MRs. . I find this approach very effective to get more focused reviews, and to reduce the time it takes for a given MR to be integrated into the main branch.

My previous approach based on git branches did not scale well with this new mindset, and during the course of the year, I stopped using branches altogetherI have not invented the branchless workflow, of course. After it was first published, someone posted a link to my Stacked Git article on Hacker News, and @arxanas posted a comment about git-branchless . I tried the tool, and even if it never clicked for me, I was really compelled by its core ideas. Similarly, Drew DeVault has published a complete article on its own branchless workflow in 2020 . .

These days, I proceed as follows.

I name each patch after the branch to which I will push it on our upstream Git remote.
99% of the time, I push my work using git push -f upstream @:$(stg top)
I created a small git plugin I called git-prepare which allows me to select one of the patch of my current patchset using fzf, and which pops all other patches that are currently applied.

git-prepare is really straightforward:

#!/bin/sh
patch=$(stg series -P | fzf)

if [[ ! $? -eq 0 ]] ; then
    exit $?
fi

if [ -n "$(stg series -A)" ]; then
    stg pop -a
fi

stg push ${patch}

The main hurdle which I still need to figure out is how to deal with stacked MRs. Currently, this is very manual. I need to remember which commit belongs to the stack, the order and dependencies of these commits, and I need to publish each commit individually using stg push; git push @:$(stg top).

The pragmatic answer is definitely to come back to git branches for this particular use case, but it's not the fun answer. So from time to time, I try to experiment with alternative approaches. My current intuition is that, by adopting a naming convention for my patches, I could probably implement a thin tooling on top of Stacked Git to deal with dependents commits.

Conclusion

Putting aside stacked MRs for now, I am really satisfied with my workflow. It’s very lightweight and intuitive, and working without Stacked Git now feels backward and clunky.

So I will take this opportunity to thank one more time Stacked Git’s authors and contributors. You all are making my professional like easier with your project.

How I Use Stacked Git at $WORK

January 16, 2022

How I Use Stacked Git at `$WORK`

git workflow

According to my Lobste.rs history , I have run into Stacked Git in early April 2021, and I remember that its promises hit a soft spot. A few weeks later, I was submitting a pull request to teach Stacked Git to sign commits . It was all I needed to start using it at $WORK, and now it has become a cornerstone of my development workflow.

What is Stacked Git?

Before going any further, it is probably a good idea to take a moment and present Stacked Git. The website introduces the tool as follows:

Stacked Git, StGit for short, is an application for managing Git commits as a stack of patches.

There are a few things to unpack here. First and as its name suggests, Stacked Git is a tool built on top of GitMy main takeaway from my Pijul adventure is connected to this. Git is not limited to the git binary. Git comes with a collection of powerful forges, nice editor plugins, and years of good practices. To this day, it’s neither the bugs nor the breaking changes that made me quite Pijul. Those were expected. What I naively did not anticipate is the dry feeling that Pijul was just the pijul binary, which left me with a lot of tasks to do manually. . It is not a brand new VCS, and as a consequence you keep using all your existing tools and pluginsI am looking at you, Magit. . Secondly, Stacked Git helps you curate your Git history, by turning your commits into patches, and your branches into stacks of patches. This speaks to me, maybe because I have been fascinated by email-based workflows for quite some time.

To me, the two core features of Stacked Git are (1) allowing you to name your commits, and (2) to navigate among them. Together, they create a wonderful companion to help you keep your history clean.

My Subset of Stacked Git

I do not want this article to be a Stacked Git tutorial. Fortunately, I don’t really use the tool at its full potential. I only care about a relatively small subset of commands I feel comfortable with and use daily.

First, to decide which commits are part of my “stack of patches,” I can count of these commands:

stg new NAME creates an empty commit, and gives it the name NAME. Having a way to identify a patch with a meaningful name that is resistant to rebase and amend is very nice. These are two properties commit hashes do not have.
stg uncommit NAME names the most recent commit under my stack with NAME and integrates it into it. I do this when I am tasked to work on a merge request made by a colleague, for instance.
stg commit removes from my stack its last patch. I do this when said commit has been merged into master.

Once my stack of patches is ready, the fun begins.

At a given time, a patch can either be (1) applied, (2) unapplied, or (3) hidden. On the one hand, if a patch is applied it is part of the Git history. On the other hand, unapplying a patch means removing it from the working branch (but not from the stack of patches of Stacked Git). If a patch becomes irrelevant, but you don’t want to remove it entirely because it can become handy later, you can hide it. A hidden patch sits beside the stack of patches, and can be reintegrated if need be.

Analogous to git log ---which allows you to visualize your Git history---, stg series gives you a view of the state of your stack of patches. Patches prefixed with + (or >) are applied, while - means the patch is unapplied.

Then,

stg pop unapplies the patch on top of the list of applied patches.
stg push applies the patch on the bottom of the list of unapplied patches.
stg goto NAME unapplies or applies the necessary patches so that NAME becomes the top patch of the list of applied patches.

Both HEAD and the work tree are updated accordingly.

In addition, stg sink and stg float allow reorganizing your stack of patches, moving patches around. Basically, they are like git rebase -i, but without having to use $EDITOR.

Modifying patches is done with stg refresh. It’s akin to git commit --amend, except it is more powerful because you can modify any applied patches with the -p option. I’d always encourage you to stg goto first, because stg refresh -p remains unfortunately error-prone (nothing prevents you from targeting the wrong patch). But when used carefully, it can be very handy.

Finally, stg rebase REF moves your stack of patches on top of REFStacked Git is supposedly able to detect, during a rebase, which of your patches have been applied to your target branch. I’d rather use stg uncommit before doing the rebase, though. . It is akin to git rebase --onto, but more straightforward. What happens is Stacked Git pop all the patches of my stack, reset the HEAD of the current branch to REF, and tries applying the patches one by one In case of conflicts, the process stop, and I am left with an empty patch, and a dirty work tree with conflicts to solve. The hidden gem is that, contrary to git rebase, the repository is not “in the middle of a rebase.”

Suppose there are many conflicting patches still waiting in my stack of patches, and an urgent task I need to take care of first. I can just leave them here. I can switch to another branch, and when I come back, I get my patches back. I call this feature “incremental rebases.”

And that is basically it. In a nutshell, Stacked Git equips commits with the same features as branches.

My Stacked Git Workflow

As mentioned in the introduction of this article, Stacked Git has become a cornerstone of my workflow. I’ve been asked a few times what this workflow is, and why Magit is not enoughIt’s always about Magit. ;) . So let’s try to do that. But first, a warning. Yes, because Stacked Git is only a wrapper above Git, everything I will explain can be achieved using Git alone, especially if you are a Magit wizard.

Stacked Git makes just everything so more convenient to me.

Planning My Commits Ahead Of Time

I’ve been introduced to Git with a pretty simple workflow: I am supposed to start working on a feature, and once it’s ready, I can commit, and move on to the next task on my to-do list.

To me, this approach is backward. It makes you set your intent after the fact. With Stacked Git, I often try to plan my final history /before writing the very first line of code/. Using stack new, I create my patches, and take the time to write their description. It helps me visualize where I want to go. Then, I use stack goto to go back to the beginning of my stack, and start working.

It is not, and cannot be, an exact science. I often have to refine them as my work progresses. Yet, I think my Git history is cleaner, more focused, since I have started this exercise.

Getting My Fixup Commits Right

Reviews are a fundamental aspect of a software developer job. At $WORK, we use Gitlab and their merge requests workflow, which I find very annoying, because it does not provide meaningful ways to compare two versions of your submissionThere is a notion of “versions” in Gitlab, but its ergonomics fall short of my expectations for such a tool. .

What we end up doing is creating “fixup commits,” and we push them to Gitlab so that reviewers can easily verify that their feedback has correctly been taken into account.

A fixup commit is a commit that will eventually be squashed into another. You can understand it as a delayed git commit --amend. Git has some built-in features to manipulate them. You create them with git commit --fixup=<HASH>, and they are interpreted in a specific manner by git rebase -i. But they have always felt to me like a sordid hack. It is way too easy to create a fixup commit that targets the wrong commit, and you can end up with strange conflicts when you finally squash them. That being said, if used carefully, they are a powerful tool to keep a Git history clean.

I am not sure we are using them carefully, though.

Some reviews can be excruciating, with dozens of comments to address, and theoretically as many fixup commits to create. Then you push all of them on Gitlab, and days later, after the green light from the reviewer, you get to call git rebase and discover your history is broken, you have tones of conflicts to fix, and you’re good for a long afternoon of untangling.

The main reason behind this mess is that you end up fixing a commit from the HEAD of your working branch, not the commit itself. But with Stacked Git, things are different. With stg goto, I put my working tree in the best state possible to fix a commit: the commit itself. I can use stg new to create a fixup commit, with a meaningful name. Then, I am forced to deal with the potential conflicts it brings when I call stg push.

Once my reviewer is happy with my work, I can call stg squash. It is less automated than git rebase -i, but the comfort I gained during the development is worth this little annoyance.

Managing Stacked Merge Requests

At $WORK, we are trying to change how we deliver new features to our master branch. More precisely, we want to merge smaller contributions more frequently. We have had our fair share of large and complex merge requests that were a nightmare to review in the past, and it’s really not a fun position to be put in.

For a few months, I have been involved in a project wherein we decided /not/ to fall in the same trap again. We agreed on a “planning of merge requests” and started working. The first merge request was soon opened. We’ve nominated an “owner” to take care of the review, and the rest of the team carried on. Before the first merge request was merged, the second one was declared ready, and another owner was appointed. Then, the owner of the first merge request had a baby, and yours truly ended up having to manage two interdependent merge requests.

It turns out Stacked Git is a wonderful tool to help me keep this under control.

I only have one branch, and I use the same workflow to deal with feedback, even if they are coming from more than one merge request. To remember the structure of everything, I just prefix the name of my patches with a merge request nickname. So my stack will look something like this:

+ mr1-base
+ mr1-tests
+ mr1-doc
> mr2-command
- mr2-tests

A reviewer leaves a hard-truth comment that requires a significant rework of the oldest merge request? stg goto reverts my work tree in the appropriate state, and stg push allows me to deal with conflicts one patch at a time. If I need to spend more time on the oldest merge request at some point, I can continue my work, knowing the patches related to the newest one are awaiting in my stack.

The most annoying part is when the time comes to push everything. I need to stg goto at the last patch of each merge request, and git push HEAD:the-branch. It’s not horrible. But I will probably try to automate it at some point.

Conclusion

Overall, I am really thankful to Stacked Git’s authors! Thank you! You are making my interactions with Git fun and carefree. You provide me some of the convenience of patch-based VCS like Darcs and Pijul , but without sacrificing the power of Git.

I encourage anyone to at least give it a try, and I really hope I will be able to contribute back to Stacked Git in the near future.