sglavoie.com – Tag: Git

Git worktrees for a better parallel workflow

Sébastien Lavoie — Mon, 02 Jan 2023 09:52:00 -0600

Introduction

Why are Git worktrees needed in the first place? Well, there are certainly a couple of different use cases where they come in handy, but the reason they exist is to allow a developer to check out multiple branches at once without having to do any kind of cleanup when switching branches. Introduced back in 2015 in Git 2.5, it’s certainly not a new feature anymore, yet it seems like its adoption really took off more recently. I was an avid user of git stash but I often got myself cornered in some specific situations where it was not as convenient as I thought it was… and git worktree was for me a pretty good solution without much overhead.

Why is `git stash` not enough?

It can be enough, but there are edge cases where it falls short of its promise of keeping stuff neatly around without too much fuss.

Switching context

One particular use case in favor of git worktree is when you have to quickly switch context and you have a dirty branch checked out – which is basically the same use case advertised in the Git documentation. Committing changes away might be a bit risky if those aren’t ready to be pushed to the remote server and stashing files might be annoying because there could be newer files to include with git stash --include-untracked or some files already staged in the middle of the work where a git stash --keep-index is also appropriate, or maybe even a case where you have created temporary files that match ignored files where git stash --all might do. It gets even messier if you want to leave things in a clean state with only the changes you need with git stash --patch where it would be needed to select interactively all your hunks. And then, you might already have multiple stashes or you might have forgotten to give one or more stash(es) a name, which makes it harder to git stash pop or git stash apply your changes later without having to inspect the content of your stashes with something like git stash show -p.

With git worktree, this is no longer an issue! If you don’t already have a new worktree you can switch to, creating one with git worktree add is quick and easy, as shown in the docs:

bash

git worktree add -b emergency-fix ../temp master

This will create a branch named emergency-fix, creating a new worktree at ../temp checking the branch emergency-fix that will be based off the master branch. Then, you would switch to that branch which is managed with a new worktree by changing directory into it (or pushd ../temp to put the directory into a stack so you can come back later to your current branch with popd). You would add changes and commit them, likely pushing them to a remote, then you could resume your work by going back to the original directory for your master branch. Now, you could leave behind the emergency-fix branch but if that was meant as a temporary one, you could just delete the worktree with git worktree remove ../temp. Besides being removed by path, worktrees can also be removed by the name they are associated with, which is the branch name shown in square brackets when issuing the command git worktree list.

Arguably, it’s not too hard to see that dealing with temporary changes in this way is a lot more straightforward since the current changes can be left intact without having to commit or stash them.

Running tasks in the background

Whether that be running a test suite that takes a while to execute or leaving the build of a system untouched while it is happening (like building a Docker image), it can be really useful to go work on something else while leaving the original task in the background. More than this, it allows one to go on another branch and make changes to the repository while files from the other branch are being accessed. In the case of building a Docker image for instance, it could cause hard-to-find bugs if the build is stopped or failed and meanwhile files were modified in the repo on the same branch to then be copied back in the next build of the Docker image only to realize that the files being copied have changed prior to being copied.

More generally though, I find I just like to leave my terminal windows open into a specific path (branch) while having the freedom to go work elsewhere. This way, a virtual environment (for instance, in Python) can be left “activated” and ready to use when context is switched again. Often, different branches in a project might have slightly different requirements and so a distinct virtual environment must be activated. Having them entirely separated by path in separate worktrees makes this kind of workflow a lot simpler to manage.

How I operate worktrees

First, other approaches in the wild

I have seen some great programmers use them within a “bare repository”, notably ThePrimeagen in his YouTube video titled Git’s Best And Most Unknown Feature. This works by creating different directories inside the bare repository, effectively having all worktrees at the same level. There is a slight chance of colliding with a reserved directory name by Git, though, since all the metadata is stored there too.

Another interesting approach I’ve witnessed is the use of a .worktrees directory inside the directory containing the main branch of the project, which works by adding a match for .worktrees/ in a global .gitignore file (kudos to Redhwan Nacef in his Git Worktree Tutorial!). I like this approach because it can list all working trees anyways with git worktree list and there’s nothing really cluttering the directory structure. However, there might be some huge build files or environments and nesting everything that way might require creating a script to find all worktrees as it is not immediately obvious where they would be stored, if at all.

What I actually do these days

The approach I have adopted is very simple and requires almost no setup at all.

Starting with a project with existing branches

Assuming a project is already cloned and worked on with no additional worktrees, then it leads to a minor hiccup because the project will need to be renamed. So what I currently do is create a top-level directory for the project, say sglavoie.github.io for this website. Then, I will literally reuse the branch name to create some hierarchy inside that project. Let’s say that right now, I’m writing multiple articles in different branches and I keep my main branch as always, then I would first mkdir sglavoie.github.io/main and put the project’s content in there with its .git folder. Mind you, this is a one-time thing when not already using worktrees!

At this stage, the project structure is laid out nicely and ready to accommodate new worktrees. So for instance, if I want to work on a new branch to create a new article without touching the main branch, I would git worktree add ../articles/article-name-here article-name-here from the main branch and voilà, a new worktree will be ready to use. Once a couple of worktrees are created in this way, the directory structure might look as follows:

 
 
 
~/dev/sglavoie/sglavoie.github.io
├── articles
│ ├── adv-web-dev-social-network-app
│ ├── git-worktree
│ ├── react-native-app
│ └── text-based-diagrams
└── main

In this way, it’s just a matter of changing directory and opening the worktree in your editor of choice (e.g., nvim for neovim or code . with VS Code). From now on, it’s easy to switch between branches of a project right from the editor by searching for the “topic” (e.g., main or articles in this case, but that could be hotfix or feat depending on how your name your branches) or for a project name directory, which would show all the branches that have been opened previously to allow further filtering. This is what git worktree list would display in this example:

 
 
 
/some/path/sglavoie.github.io/main d67dd8d2 [main]
/some/path/sglavoie.github.io/articles/adv-web-dev-social-network-app 666a0b43 [articles/adv-web-dev-social-network-app]
/some/path/sglavoie.github.io/articles/git-worktree d67dd8d2 [git-worktree]
/some/path/sglavoie.github.io/articles/react-native-app bcfac34e [articles/react-native-app]
/some/path/sglavoie.github.io/articles/text-based-diagrams 4b25371d [articles/text-based-diagrams]

New worktrees from a project already using worktrees

If you’ve already embraced this approach, then the next time you want to create a worktree, it will just be a matter of switching to the “base” branch you want to create a worktree from and creating one at whatever location you fancy outside the current directory. For instance, for this article:

bash

git worktree add ../articles/git-worktree articles/git-worktree

This would take care of using the branch name “nesting” convention (e.g., feat/feature-name, hotfix/bug-name, etc.) and create sub-directories as needed too. Assuming a worktree has been merged in another branch and/or is no longer necessary, it can be removed with git worktree remove git-worktree in this example (where git-worktree is the name given to the worktree… a bit confusing here, you’re right).

Keeping worktrees around

Although the official Git documentation presents a useful case for a temporary fix where the worktree is almost immediately deleted upon the completion of a task, I have found myself in a situation where I’d rather have multiple longstanding worktrees. For example, I regularly need to boot a web application from a different branch, either because the currently checked out branch does not have the necessary requirements installed or because I want to leave a web application running in the background without affecting my current work. In my case, I use it to process some data when it arrives and come back to the work I was doing earlier, doing practically the same thing shown in the Git docs but keeping the worktree around for future use.

On a large project, I might have a couple of worktrees, but still I would keep branches around without them being part of worktrees when these are meant to be short-lived feature branches that share the same dependencies as other branches as long as they won’t need to be checked out at the same time. Another time I might have separate branches like this could be to avoid having to duplicate gigantic node_modules or .venv directories when not needed, because working with different worktrees is pretty much like cloning an entire repository in a separate folder and having to reinstall requirements. There is also a nice Git feature where worktrees are prefixed with a plus sign when issuing git branch, so that makes them distinctly different from regular branches:

 bash
 
 
 
$ git branch
+ articles/react-native-app # worktree
 gh-pages # other regular branch
+ git-worktree # worktree
* main # currently checked out

Conclusion

I have briefly touched upon a downside of worktrees, which is that it’s almost like cloning over and over a repository, which can take up a lot of disk space with large projects. Nevertheless, this is a tradeoff I am entirely willing to make given the advantages Git worktrees bring with them! If you’re not already using them, maybe this little post might have inspired you to give them a go!

Resources and references

External links

From this website

Git the gist of it: common commands for a working workflow

Sébastien Lavoie — Sun, 03 Apr 2022 11:21:00 -0500

Introduction

Git, the friend you wish you had met earlier, when organizing files like report 1.pdf, report 2.pdf and report final 1.pdf still made sense somehow. It’s undoubtedly complicated to wrap one’s head around it at first, although there exist some GUIs to make the journey smoother – the best examples that come to mind would include GitKraken and Tower at the top of the list. I have been advised to learn to use Git from the terminal and I would, without flinching, recommend anyone to do the same to really grok this tool and get an intuitive feel for what it does.

Beyond the extraordinary technical prowess that it is, Git can be useful to a broad audience. It’s not good at dealing with large binary files (and Git LFS is not exactly easy to use just yet to cover that case), but for anything involving text that a human can read, it shines – may it be a programming language, some reports written with LaTeX, some diagrams produced with Mermaid or PlantUML, personal notes taken in plain text or in Markdown or the fact that synchronizing changes made to a project is a breeze and allows ones to work from multiple locations and machines.

With platforms like GitHub and GitLab, it is easy to keep a “backup” of projects, which can be either public or private. And despite Git not being awesome with very large files, any smaller binary files like images and PDF files can easily be added to a Git repository, allowing users to keep different versions of these files very easily without using a cloud service such as Dropbox or Google Drive. So even if the original input is not written in a text-friendly manner, the output can still be saved under multiple versions with great details, backed up to different websites and fetched just as conveniently from anywhere else (assuming access has been set up to continue working on a project, or at least one can log in to the website and download files without issue).

Sure, it is not for everyone, but the use cases just described can go a long way. I have used it to practice solving programming challenges, to document all my project at the university, to keep track of preferences and configuration files for my different systems (Linux and macOS) which I’ve described in Managing dotfiles with a Git bare repository, to work on pet programming projects and coding experiments that I keep private, to store code snippets into a growing library for reference purposes, to take notes in the form of “tutorials” or “wiki” (platforms like GitHub and GitLab have a nice wiki feature that renders prose nicely!) for different tasks I need to do infrequently and of course to build this very website in the open (the source code is available on GitHub)! And that is just describing some of my personal use cases without touching on the fact that collaboration within a team is a huge reason to use it!

So with that said, let’s explore some of its functionality, starting with a few tips and tricks, then delving deeper into a real-world workflow and topping it off with more useful commands and configuration settings.

Global and local `.gitignore`

There are files we never care about adding to Git repositories, such as a thumbnail cache file Thumbs.db on Windows or a .DS_Store file storing custom attributes for folders on macOS. Instead of ignoring these kinds of entries in a per-repository .gitignore file which might not contain everything we would like to exclude, it can be simpler and more efficient to use a global .gitignore, which serves the same purpose but for any Git repository regardless of the presence of a .gitignore in that specific repository! In other words, this serves as a permanent list of things to ignore so that there is no need to remember about them later.

The setup is straightforward: create a file ~/.gitignore, fill it as usual with patterns you are sure to want to exclude globally and set a configuration option to use that file – for instance by adding the following to .gitconfig:

git

[core]
 excludesfile = ~/.gitignore

Toptal provides a nice tool on the command-line that can be used to easily exclude patterns. With it, typing gi python >> .gitignore would append a bunch of common patterns to a .gitignore file – in this case, for Python.

Meaningful commit messages with `.gitmessage`

Besides using the excellent Conventional Commits specification to write messages in a format that makes sense to other fellow human beings, using a template for Git commits can help with remembering why commits are made and how they should be structured. There is a configuration setting, commit.template, that can be used to set the default text being displayed when a text editor opens after typing git commit.

The following is the current template I use, which can be saved in a file like ~/.gitmessage:

 
 
 
# [Add/Fix/Remove/Update/Refactor/Document] [summary]


# Why is it necessary? (Bug fix, feature, improvements?)
#-
# How does the change address the issue?
#-
# What side effects does this change have?
#-
# Include a link to the ticket, if any.

Then, this can be added to the config file under the [commit] section like so:

git

[commit]
 template = ~/.gitmessage

All lines starting with a hash symbol (#) will be ignored, so there is no need to manually delete all of this verbose content when saving the commit message. Sweet!

My usual Git workflow

This section depends very much on team standards, if applicable. But in general terms and considering mostly a solo interaction with Git, I like to adhere to the following processes, without taking into account how one would plan, produce diagrams, brainstorm, etc. That shall be the topic of an upcoming post!

Starting a new project

There are different ways to proceed, although I like the simplicity of just creating a new empty repository on GitHub and cloning it on my machine using the SSH protocol, e.g. git clone git@github.com:some/project.git. This has the benefit of automatically setting the main branch and the remote URL, using origin as the default remote. Cloning an empty repository has the same effect as starting with git init, so this also becomes unnecessary.

If I have been experimenting locally first, I would do a git init, commit any changes and then push the new repository on GitHub, either using the great Git integration provided by VS Code or again creating a new repository on GitHub to set the remote URL in order to be able to push local changes, i.e. by doing git remote add origin git@github.com:some/project.git and then pushing to that new URL. To make sure that my default branch is always main (to match the new default on GitHub) and not something like dev or master, I have a Git template lying around that ensures that the first branch created when doing git init will be main. It is as simple as creating the file ~/.git-templates/HEAD with this content:

ref: refs/heads/main

Then, in ~/.gitconfig, the following section is used to read the templates:

git

[init]
 defaultBranch = main
 templateDir = ~/.git-templates

I have this template since before init.defaultBranch was introduced in Git 2.28.0 back in July 2020: now just having the option defaultBranch will do the trick. Still, it’s good to have a templateDir configured for other purposes! Although admittedly, I don’t use them at all and would rather create a custom command to more easily script what I need for each repository: more on this in the section Custom Git sub-commands.

Committing to an existing project

Now that there is some folder set up for Git to track files, it’s time to make changes! I’m a big fan of committing “small and often” because Git is super flexible and updating the history is usually a simple process – unless you have pushed to a remote repository used by other people, in which case being a “force push” type of person won’t make you many friends. May the --force be with you when you push to a private repository where you’re the only contributor, otherwise, it’s good practice to think twice before sending your final changes away as you should not mess up with public history (and depending on how your access is set up within a team, you might not even be able to use the --force flag when pushing on certain branches!).

So what’s the alternative to constantly rewriting history in a harmful way? Well, assuming you have a choice when working alone for instance, there are two main contenders: merge vs rebase. I think neither option is better than the other when used right, but it’s good to know that rebase might create possible headaches because it modifies the Git history while merge might create undesirable noise when used profusely by adding “merge commits”. I use both techniques, but for different purposes.

Being committed

The basic workflow might look like this, with a couple of different options thrown in to cover more scenarios:

 bash
 
 
 
# Check the current state of the repo
git status

# Inspect the changes to commit (before staging)
git diff

# Stage a file to be committed
git add SOME_FILE

# Stage all new/modified files, (i.e., --all)
git add -A

# Stage all modified files (not any new ones, i.e., --update)
git add -u

# Get fancy with adding patches only (part of files)
git add -p

# Undo changes done to a tracked file
git restore -- FILE_NAME

# Inspect staged changes to commit
git diff --staged

# Unstage files
git reset HEAD --

# or just 'git commit' to open a text editor
git commit -m "SOME_MESSAGE"

# See the changes done in the latest commit
git show

# or a specific commit hash from earlier
git show COMMIT_HASH # or ref like HEAD^

# Forgot to add something?
git add SOME_OTHER_FILE
git commit --amend --no-edit

# Want to rephrase the last commit?
git commit --amend

# Tag the latest commit
git tag TAG_NAME

# Tag earlier commit with annotation
git tag -a TAG_NAME COMMIT_HASH -m "MESSAGE"

# Undo a commit, keeping changes in the work tree
git reset HEAD^

# Undo a commit and DO NOT keep changes
git reset --hard HEAD^

# Oops, get back a commit that was "lost"
git reflog # find the relevant commit hash
git cherry-pick COMMIT_HASH # or git checkout COMMIT_HASH

# Explore the repo at an earlier commit
git checkout COMMIT_HASH

# Committed some changes while checking out an old commit?
# Save the changes to a new branch, then potentially merge them back
git switch -c NEW_BRANCH_NAME
git switch OTHER_BRANCH
git merge NEW_BRANCH_NAME

# Undo a merge
git reflog # find the commit hash before the merge
git reset --hard COMMIT_HASH

# Or undo to a known point from a remote branch
git reset --hard origin/main

# Stop tracking a file/directory (remove) but keep it on disk
git rm --cached FILE_OR_DIRECTORY

# Remove stuff that hasn't been committed yet (interactive mode is nice)
# Don't forget about -n for a dry run first!
git clean -i

# Want to undo a change that's already pushed?
# Add a new commit without rewriting history
git revert COMMIT_HASH

# See who did what to which file and when
git blame FILE_NAME

Arguably, basic editing doesn’t require stashing, but that can be helpful for a quick modification, like temporarily saving changes to quickly switch to another branch or pull some remote changes without having to commit first.

 bash
 
 
 
# git stash --help - "Stash the changes in a dirty working directory away"

# Maybe you want to keep changes around without committing
# --include-untracked and --keep-index might be needed!
git stash

# Stash changes with a clearer name/purpose
git stash save "SOME MESSAGE"

# Selectively stash changes (keep specific lines)
git stash save -p

# List existing stashes
git stash list

# See the summary of a stash
git stash show

# See all changes made in a stash (patch)
git stash show -p

# Apply changes from a stash (TAB completion after `apply` is useful)
git stash apply stash@\{SOME_ID\}

# Apply and remove the last stash at the same time
git stash pop

# Remove a single stash
git stash drop stash@\{SOME_ID\}

# Remove all stashes
git stash clear

`rebase`

When working locally with changes that are not yet part of the “permanent” Git history, I like to git rebase very much to clean things up before making a git push, which I like to view as an irrevocable decision. Because I commit small and often, it’s often the case that I end up with a couple of very simple commits which really belong together and should form a bigger commit. While committing a big chunk of code at once avoids having to do any rebase in the first place, it’s also inconvenient to undo a substantial amount of work when you’re experimenting and/or working on an unfamiliar codebase. So in the end, my preference goes towards smaller commits because rebasing is actually fun to do and lets you believe that you came up with brilliant solutions on your first attempt :). That makes for a cleaner Git history for sure, although you will lose some context if you never merge. Meaning, rebasing creates a “linear” history while merging from different branches shows a more complete picture of how a repository really took shape over time. My simple rule of thumb on the matter is this: use rebase to consistently ship meaningful commits (good descriptions, fewer typos, changes chunked logically and precisely, etc.) and use merge to incorporate somewhat larger pieces of history, like a new feature coming from a “feature branch”.

Some common commands I use:

 bash
 
 
 
# git rebase --help - "Reapply commits on top of another base tip"

# Include all commits up to COMMIT_HASH, included
git rebase -i COMMIT_HASH^

# Include most recent commit only
git rebase -i HEAD^

# Include 2 most recent commits
git rebase -i HEAD^^

# Include 3 most recent commits
git rebase -i HEAD~3

# make BRANCH have the history up to COMMIT_OR_BRANCH, included
git rebase COMMIT_OR_BRANCH BRANCH

# Used after resolving a conflict
git rebase --continue

# Reset to where you were before rebasing (move HEAD)
git rebase --abort

# To update the next actions to be taken on the remaining commits
git rebase --edit-todo

There are a bunch of obscure options just like almost any other Git command in existence, but for that there is help available for each command (such as git rebase --help) from the terminal and the trusty Stack Overflow ;).

Sample workflow

In the case of rebase, I enjoy working in this way:

Make small commits, maybe 5 to 10 depending on the complexity of the project – usually as long as a series of commits relates to a single topic whenever possible.
Have a peak at the recent history with git log to have a good idea of what just happened.
Realize that the history can be improved. Find the oldest commit hash (not pushed yet!), take note of it and run git rebase -i COMMIT_HASH^ (with the “hat” ^ at the end to reference the parent of that commit).
This opens up a text editor with some explanations on how to proceed (for more on this, have a look at this great article on Rewriting history). From there, I usually use r to reword, s to squash, e to edit and sometimes f to fixup, besides also re-ordering commits and from time to time deleting one by removing the line entirely.
- r is pretty harmless as it will just show up a new window where the commit message and description can be modified.
- s is more destructive because commits will be “merged” together! No actual change is lost, but if you squash a ton of commits by accident, it will create huge commits and you might want to undo that with reflog before it’s too late (Atlassian has more to say about this in git reflog). The s option is also nice because it keeps all commit messages, so you can edit the final log message as needed without discarding messages.
- e is used to modify the actual source code being committed, maybe to fix a typo or a minor bug after realizing that the test suite no longer passes (assuming you are not programming blindly without tests :)). This can cause some “conflicts” if you change some lines which are also part of other commits in the selection you made originally, so one has to be careful with that. This can also be used in conjunction with git reset HEAD^ to “cancel” the current commit when doing the rebase in order to split it into multiple smaller commits, which can then be “git added” back, followed by a git rebase --continue to keep going.
- f is a quick way of squashing commits together while discarding messages you don’t need. So maybe the last commit has a proper description (“Implemented something…”) and a few commits before that one were just temporary “savepoints” with non-sensical commit messages (things like “testing…” or “new commit”) that were done until you reached a final solution that’s worth committing. So of course in that case the history would be pretty ugly and hard to understand if all commits were kept intact, so these can be added to the latest change which encompasses a working solution as a whole. Just as well, maybe that last commit didn’t have a complete message just yet, so it could also be rewritten with the r prefix.
When individual commits make the rebase stop temporarily (such as when a commit is to be edited with e and waits for changes to be made), then it’s time to do git rebase --continue once the necessary changes are made.
If something goes wrong along the way, there’s always a way back to the place you were right before rebasing with git rebase --abort. It’s worth noting that Git itself will output some useful messages all along so it’s not necessary to remember all of this: it quickly becomes intuitive.

Now, rebase covers the cases where local changes are done in isolation, but for something more imposing or simply to keep track of what happened in which branch, merge remains a powerful ally.

`merge`

So I don’t use merge as much, especially when working solo, but it is undeniably useful and could replace the rebase workflow completely (it might also be demanded by your colleagues anyways!). There’s nothing like a good rebase session to keep things tidy, but a flat history line won’t look attractive on a huge project with many contributors, so merge is there to deal with cleanly integrating changes from different places into some main branch (it could be named differently based on the team workflow of course and there might be more than one “main” branch too). What makes merge incredibly cool is the fact that branches in Git are “cheap”, meaning they can be created very quickly and efficiently, they don’t take space at all, you could have dozens of branches or more and you can incorporate changes from one branch to another with a simple git merge, which is nicer than using git cherry-pick to get multiple commits from one branch into another (for one or two commits though, cherry-pick is handy).

I see rebase more like a cleaning step while merge really shines when dealing with multiple commits between different branches. Even on a simple project when working alone, it has its uses! For example, let’s say we have a repository full of small programming challenges (maybe from HackerRank or LeetCode). We might get stuck on a tricky problem and wouldn’t want to commit an unfinished solution. Also, maybe we would get fed up eventually working on a given challenge and would rather try our luck with a different one. Well, we can always leave changes uncommitted (not very safe as these might be lost!), but that can cause confusion and you might inadvertently end up committing files that have nothing to do with the latest challenge – effectively committing at the same time your unfinished challenge with the one you just completed. There’s always the possibility to git stash individual files to keep them somewhere, but I find working with stashes to be a bit more cumbersome than branches and you might literally forget that you have changes stashed. If you do that a few times, you might not even know which stash is what if you didn’t give them a good name…

Some common commands I use:

 bash
 
 
 
# git merge --help - "Join two or more development histories together"

# Get commits from BRANCH_NAME into the currently checked one
git merge BRANCH_NAME

# Merge one branch into another
git merge SOURCE_BRANCH_NAME DESTINATION_BRANCH_NAME

# Get out of conflicts...
git merge --abort

# Continue after resolving conflicts
git merge --continue

# Keep the "merge commit" in the history
git merge --no-ff BRANCH_NAME

# Set a custom commit message for a "merge commit"
git merge -m "MESSAGE" BRANCH

_{Tip: The command git merge --help describes some nice examples about the whole process of conflict resolution.}

Sample workflow (kinda)

So, instead of risking losing changes like this, creating a new branch with git switch -c BRANCH_NAME and working from there is much easier to confine changes to a specific matter, which we can see like a “feature” that can later be added to the main “trunk”. We can commit unfinished business, switch to a different branch, come back to it later, git reset any old commit to “revert” the history and keep working from a clean state. In any case, there’s always rebase to avoid committing useless stuff, so there’s really no reason to avoid branches.

The merge command will be involved when changes from a “feature branch” (or whatever other purpose you give a branch) are merged into the main branch with git merge BRANCH_NAME. When there are no “merge conflicts” (such as when you work on a totally new file that won’t clash with prior work), this is a seamless workflow where you can just merge as if changes were made in the branch you are on in the first place. There are other instances where bigger changes can be merged successfully in the same way, but it’s interesting to keep track of how you worked on a project, so in this scenario you can always use git merge --no-ff BRANCH_NAME (--no-ff meaning “no fast-forward”) to keep a “merge commit”, which is strictly speaking not needed (because there’s no conflict resolution in the case of a “successful” merge) but can be a helpful reference point when you look back at your Git history two years from now to understand how you worked on something, piecing things together bit by bit.

There’s also an indisputable advantage conferred by the use of branches, which is: you can have plenty of them! So while rebase is nice to use on a given branch, in no way can working on multiple things at once in a single branch and then rebasing all that effort be as straightforward as creating new branches for every new topic that’s being started and then merging it back into a single place of truth. Juggling different concerns in a single branch where you have a few things going on (maybe 2-3 partially implemented features) is far from being a cozy environment and rebasing that kind of work where commits are not even related to each other can become a nightmare in a short amount of time.

Managing branches

So with all that was written earlier, I believe a point was made in favour of using branches. Because branches are such a wonderful feature of Git, here are some more commands I rely on (surprisingly, there aren’t that many for git branch!):

 bash
 
 
 
# git branch --help - "List, create, or delete branches"

# List local branches
git branch

# List only remote branches
git branch -r

# List all branches
git branch -a

# Delete a branch
git branch -d BRANCH_NAME

# Delete a branch forcefully
git branch -D BRANCH_NAME

# Delete a remote branch (doesn't matter if the local branch was deleted)
git push origin --delete REMOTE_NAME/BRANCH_NAME

# Rename a branch
git branch -m BRANCH_NAME NEW_BRANCH_NAME

# Track a specific remote branch
git branch BRANCH_NAME -u UPSTREAM_NAME

# See which branches have been merged or not
git branch --merged
git branch --no-merged

# Switch to the branch last checked out
git checkout -

# Compare changes between branches
git diff BRANCH_ONE..BRANCH_TWO

# Compare a file across branches
git diff BRANCH_ONE:FILE_NAME BRANCH_TWO:FILE_NAME

# See a file from another branch
git show BRANCH_NAME:FILE_NAME

# Get a file from a different branch
git restore --source OTHER_BRANCH_NAME path/to/file.txt

Aliases

While I believe it’s good practice to type complete commands to remember them better, I also tend to use Git aliases for two reasons: because some deeply ingrained concepts don’t need as much reinforcement and because some obscure operations can be made so much more accessible with a pertinent mnemonic device.

Some commands like add just become unforgettable over time, while others – e.g., unstage – just don’t exist yet. Without further ado, here is a list of the aliases I currently rely on when using Git, which comes straight from ~/.gitconfig.

For instance, instead of typing git add, by setting the alias a = add (see below), it is now possible to type git a to get the same result.

git

[alias]
 a = add
 br = branch
 c = commit
 ca = commit --amend
 can = commit --amend --no-edit
 ch = checkout
 d = diff
 ds = diff --staged
 po = push origin
 pos = push --set-upstream origin main
 rc = rebase --continue
 ri = rebase -i
 rl = reflog
 sh = show
 s = status --short
 st = status
 sw = switch
 t = tag
 unstage = reset HEAD --

 ; show changes since last commit
 difflast = diff --cached HEAD^

 ; show last commit
 last = l -1 HEAD

 ; undo last commit
 undo = "!f() { git reset --hard $(git rev-parse \
--abbrev-ref HEAD)@{${1-1}}; }; f"

 l = log

 ; short log
 sl = shortlog

 ; log graph
 lg = l --color --graph --pretty=format:'%Cred%h%Creset \
-%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

 ; log name
 ln = l --name-only

 ; log decorate all
 logda = l --oneline --decorate --graph --all

 ; log stat
 ls = l --stat

 ; log pretty
 lp = log --pretty='%C(yellow)%h %C(cyan)%ad %Cblue%aN%C(auto)%d \
%Creset%s' --date=relative --date-order --graph

At some point, using Git aliases will become second nature, but until then, it can be useful to have a separate terminal alias to list them all (or maybe you forgot the command an alias is using under the hood!). For this, you can set the following alias in a file like ~/.bash_aliases:

 bash
 
alias gitaliases='git config -l | grep alias | sed "s/^alias\.//g"'

# For a fancier version displaying aliases in two columns neatly aligned:
alias gitaliases='git config -l | grep alias | sed "s/^alias\.//g" \
 | sed "s/=/Ω/" | column -t -s "Ω"'

That command will look in the Git configuration, extract all the lines containing “alias” and remove the “alias.” prefix so that you can see all aliases in the form a=add in the case of git add being aliased to git a. If you have a ton of aliases (which is probably a red flag…), finding a specific one is just a matter of doing gitaliases | grep keyword, of course replacing keyword with something else ;).

_{Tip: One can go further to shorten Git commands by shortening git itself! You can put a line such as alias g='git' in ~/.bash_aliases for instance. Now, git add can become g a. Pretty efficient! For more on Bash aliases, you might like to read Aliases: Also Known as Terminal User’s Best Friends.}

This section is really just meant to give a taste of the possibilities that aliases offer. To learn about actual commands and their usage, there is nothing like the official Git docs (there is a short section on Git aliases too).

Custom Git sub-commands

There might be less of a need for custom-made commands to be created when so much can be done with Git alone, but there are cases where these custom additions can shine! As a concrete example, I have been updating this website with what I call my “learning progress” but committing always the same kind of stuff gets boring, so I have created a simple Bash script to automate the process of publishing and committing (the content of the script is of no importance, it is only there to demonstrate that commands other than Git can be called too):

 bash
 
 
 
#!/bin/bash
# Act as custom command `git addlearning` and perform all that follows
# Assumes that `pelican` command is available
cd ~/dev/sglavoie/sglavoie.github.io-source
git add .
git commit -m "Add learning progress"
git push origin main
pelican

cp -r \
 ~/dev/sglavoie/sglavoie.github.io-source/output/* \
 ~/dev/sglavoie/sglavoie.github.io/ && \
 cd ~/dev/sglavoie/sglavoie.github.io && git add .
git commit -m "Add learning progress"
git push origin main
cd ~/dev/sglavoie/sglavoie.github.io-source

It is noteworthy to know that any kind of executable programs can be used, such as Ruby, Python and so on, as long as they are made available in the $PATH. This will be somewhat similar on most UNIX-based system where the PATH variable needs to be exported (usually in a file like .bashrc or .zshrc), for instance:

 bash
 
# $HOME refers to a place like /home/user on Linux or /Users/user on macOS
export PATH="$HOME/dev/git-scripts:$PATH"

On Windows, there are separate instructions to be followed. With that done, there’s also a need to make sure the file is executable, which can be done on the command-line with chmod +x FILENAME_HERE.

Some lesser-known yet incredibly useful commands

`git bisect`

I try to commit working code as often as possible, but sometimes there are just bugs that have flown by and took residence in the codebase a long time ago. In this scenario, there is one tool in the Git tool belt for that very specific use case: git bisect. Working with the binary search algorithm, git bisect searches in a range of commits and by identifying “good” and “bad” commits, will pinpoint exactly where the issue came from in the minimum number of iterations possible. You’ll need sub-commands like start, bad, good and reset at the very least and for more advanced use cases where automatically running a script for each commit is needed, run will do the job. See the docs on git bisect for more.

`git rerere`

I almost never use this in practice, but it can be very useful when working in a large project where similar merge conflicts are likely to occur over time. Git can be “taught” to automatically solve merge conflicts! There are some official docs on this, but I’ve found this Stack Overflow answer to be a more approachable read.

A word on the configuration file

At the very minimum, setting a name and email will be necessary to use Git:

 bash
 
git config --global user.name "Your Name"
git config --global user.email "email@example.com"

Seeing the current configuration can come in handy, too:

bash

git config --global --list

And in the case of this particular command, git config, it can’t be emphasized enough how useful searching through the help page in the terminal will be: git config --help.

I’d be remiss if I didn’t include an example of my own configuration at this point, so here it goes! To make it so that it is convenient to commit this configuration file publicly, some private settings can be “included” from other paths inside the [include] block. For clarity, I’ll show what that file looks like below the main configuration file.

 bash
 
 
 
# This is the content of ~/.gitconfig

[include]
 ; This file can add more information to extend the main configuration.
 ; For example, when inside a directory that match a certain pattern,
 ; we can tell Git to change our name or email (e.g., when committing
 ; with different credentials from a work email)
 path = ~/Dropbox/.custom/.gitconfig
[color]
 branch = auto
 diff = auto
 grep = auto
 interactive = auto
 status = auto
 ui = true
[alias]
 # cut out for brevity, see the section on Aliases
[core]
 editor = nvim
 excludesfile = ~/.gitignore
 pager = diff-so-fancy | less --tabs=4 -RFX
[commit]
 gpgsign = true
 template = ~/.gitmessage
[mergetool "nvim"]
 cmd = nvim $MERGED
[difftool "vscode"]
 cmd = code --wait --diff $LOCAL $REMOTE
[mergetool]
 prompt = false
[color "diff-highlight"]
 oldNormal = red bold
 oldHighlight = red bold 52
 newNormal = green bold
 newHighlight = green bold 22
[color "diff"]
 commit = yellow bold
 frag = magenta bold
 meta = 11
 new = green bold
 old = red bold
 whitespace = red reverse
[push]
 recurseSubmodules = on-demand
[gpg]
 program = gpg2
[filter "lfs"]
 clean = git-lfs clean -- %f
 smudge = git-lfs smudge --skip -- %f
 process = git-lfs filter-process --skip
 required = true
[pull]
 rebase = false
[credential]
 helper = store
[init]
 defaultBranch = main
 templateDir = ~/.git-templates
[diff]
 tool = vscode

The file being referenced/included here, ~/Dropbox/.custom/.gitconfig, looks like this:

 bash
 
 
 
[user]
 email = email@example.com
 name = Your Name
 signingkey = 798034F11B2ADED2
[commit]
 gpgsign = true

# The following block could be used to update credentials when committing
# depending on what directory is opened. So, if you work for COMPANY_NAME
# and the pattern 'COMPANY_NAME' appears in the current working directory,
# then Git can be smart and update your configuration by including
# something like the previous block so that the original email, name,
# signingkey and possibly other config options are overwritten.

; when working at COMPANY_NAME
[includeIf "gitdir:**/COMPANY_NAME/**/.git"]
 path = ~/Dropbox/.custom/.gitconfig-COMPANY_NAME

So this section briefly points out how custom tools like diff-so-fancy can be used, how diff output colors can be customized, how specific code editors like Neovim and VS Code can be opened when committing or dealing with merge conflicts and generally just how the file is meant to be structured.

A lot more on configuring Git can be found in the official documentation on git config.

Conclusion

Being exhaustive when it comes to using Git is definitely not something this article strived to achieve: Git is such a complex piece of software that has been evolving since 2005, when it became a necessity to deal with incoming patches sent to Linus Torvalds to make Linux the fantastic project it has become! There is much, much more to learn, but hopefully this post gives you a slightly different perspective and points the way to a well-rounded journey with the list of references below. Git good!

More resources and references

Websites

Conventional Commits - “A specification for adding human and machine readable meaning to commit messages.”
Git Cheatsheet - “Interactive Git Cheatsheet, categorizing commands based on what they affect.”
Git Immersion - “A guided tour that walks through the fundamentals of Git, inspired by the premise that to know a thing is to do it.”
GitHowTo - “Git How To is a guided tour that walks through the fundamentals of Git, inspired by the premise that to know a thing is to do it.”
GitHub Learning Lab - “With GitHub Learning Lab, grow your skills by completing fun, realistic projects. Get advice and helpful feedback from our friendly Learning Lab bot.”
Learn Git Branching - “An interactive Git visualization tool to educate and challenge!”
Microsoft Learn GitHub modules - “Learn new skills and discover the power of Microsoft products with step-by-step guidance.”
Pro Git Book - “The entire Pro Git book, written by Scott Chacon and Ben Straub and published by Apress, is available here. All content is licensed under the Creative Commons Attribution Non Commercial Share Alike 3.0 license. Print versions of the book are available on Amazon.com.”
Productive Git for Developers - “You will walk through a series of scenarios which you’ll most commonly encounter in your daily work life as a developer.”.
Step-by-step guide to contributing on GitHub - “Have you thought about contributing to an open source project, but you’re too confused (or intimidated) by the process to even try? I’ve been there too!”
Try GitHub - Resources to learn Git: Handbook, cheat sheets, git commands in the browser, etc.

YouTube

CS50 Beyond 2019 - CS50
Git & GitHub Crash Course For Beginners - Traversy Media
Git and GitHub for Beginners - Crash Course - freeCodeCamp.org
Git Tutorial for Beginners: Command-Line Fundamentals (playlist) - Corey Schafer
GitHub Basics Tutorial - How to Use GitHub - freeCodeCamp.org
MIT Missing semester (Version Control) - Git data model - MIT
The Ultimate Git & GitHub Crash Course - Learn to Version Control for Beginners - Laith Harb

Online courses

Git Essential Training (free with free trial) - LinkedIn Learning. “Using a step-by-step approach, author Kevin Skoglund presents the commands that enable efficient code management and reveals the fundamental concepts behind version control systems and the Git architecture. Discover how to track changes to files in a repository, review previous edits, and compare versions of a file; create branches to test new ideas without altering the main project; and merge those changes into the project if they work out.”
Git Started with GitHub - Udacity. “This course is designed to jump right into showing how Git and GitHub work together, focusing on the Git basic workflow. Students can expect to learn the minimum needed to start using Git in about 30 minutes.”
How to Use Git and GitHub - Udacity. “This course, built with input from GitHub, will introduce the basics of using version control by focusing on a particular version control system called Git and a collaboration platform called GitHub.”
Short and Sweet: Get Started with Git and GitHub Right Now - Udemy. “In just 30 minutes, this “Short and Sweet” course covers the essential ideas you need to move forward, without a lot of filler. At the end of the course, you’ll be able to set up a GitHub account, install Git, create and configure new Git and GitHub repositories, create a change history for your software projects, and publish your software projects to GitHub.”
The Ultimate GIT 5-day Challenge - Udacity. “A quick way to determine if working with GIT is something you want to learn more about. This course takes us step-by-step through some basic GIT operations. The course will not dive too deep, and takes small steps on each of five days. As we continue through the course, we learn a basic, single-person workflow that could allow anyone to store files at GitHub or BitBucket.”
Version Control with Git - Coursera. “In this course, you will not learn everything there is to know about Git, but you will build a strong conceptual understanding of the technology, and afterward will be able to confidently dig deeper on any topic that interests you.”
Introduction to Git and Github - Coursera. Offered by Google. “In this course, you’ll learn how to keep track of the different versions of your code and configuration files using a popular version control system (VCS) called Git. We’ll also go through how to setup an account with a service called GitHub so that you can create your very own remote repositories to store your code and configuration.”

References for this article

git rerere - git-scm.
35+ Git Commands List Every Programmer Should Know - loginradius.
Binary search algorithm - Wikipedia.
Gitignore - Toptal.
HackerRank.
LeetCode.
Rewriting history - Atlassian.
The new Git default branch name - GitLab.
What is git-rerere and how does it work? - Stack Overflow.

Managing dotfiles with a Git bare repository

Sébastien Lavoie — Sun, 30 May 2021 13:13:00 -0500

Introduction

I have been managing my configuration files for the past year using a technique I originally came across in this YouTube video from DistroTube. This uses a Git bare repository instead of the “usual” way, which consists of using a normal Git repository where one would store the actual configuration files and create symbolic links to all those files to the expected path on the system.

Needless to say, symlinks are a pain to manage when potentially hundreds of files need to be tracked in this way. Fortunately, working with a bare repository is much simpler: there’s neither a need to move files around nor store any of them in the dotfiles bare repository either. Let’s dive in to see how this works! I’ll keep the instructions to the point: for more details, please refer to the article The best way to store your dotfiles: A bare Git repository from Atlassian, the source of knowledge behind this post.

1. Set up the system

Open a terminal and brace yourself to type a few commands. This will need to be done only once on any machine you use.

Set the following variable to the name of the directory where you want to store your dotfiles (e.g. .dotfiles, dotfiles, cfg, etc.):

 bash
 
DOTFILES=dotfiles

Then type the following commands:

 bash
 
git init --bare $HOME/$DOTFILES
alias config='/usr/bin/git --git-dir=$HOME/$DOTFILES/ --work-tree=$HOME'
config config --local status.showUntrackedFiles no

Depending on where you store your terminal aliases (e.g. .bashrc, .zshrc, .bash_aliases, etc.), set the following variable according to your needs:

 bash
 
ALIASES=.bash_aliases

Once that is done, type the following command (or open the file containing your aliases with a text editor to manually put the alias wherever you want):

 bash
 
echo "alias config='/usr/bin/git --git-dir=$HOME/$DOTFILES/ --work-tree=$HOME'" >> $HOME/$ALIASES

You can of course change the config alias to something else. I like to simply use c instead.

1.1 Create a repository to host your dotfiles

At this point, you will want to make sure you have created an empty Git repository on a website such as GitHub, GitLab or BitBucket. In the interface of that website, you should find a place that allows you to copy the link to that Git repository, which might look like something like this: git@github.com:username/dotfiles.git.

1.2 Set the remote to track your dotfiles

With your new Git repository created in the previous step, you will now want to add tracking information to be able to connect to the remote Git repository. You can do so as follows:

bash

config remote set-url origin git@github.com:username/dotfiles.git

For more information about this, you can read the article Setting up SSH and Git for Multiple Accounts if you’ll be using an SSH key to connect and more specifically the official documentation on the git remote command.

2. Use the new system

2.1 On your current machine

Tracking changes will now be a breeze! All we have to do is to add files with our new alias (assuming config was chosen) to Git, commit and push to a remote repository to keep everything neatly backed up.

A typical workflow will look like this:

 bash
 
 
 
config status
config add .gitconfig
config commit -m "Add .gitconfig"
config add .zshrc
config commit -m "Add .zshrc"
config push

2.2 On a different machine

Once yet have set up the system once with a remote repository, then the process becomes simpler as you can clone that repository and save a few steps. Here’s what you’d be expected to do to set up the same dotfiles management system on another machine:

 bash
 
 
 
# set to different values as desired
DOTFILES=dotfiles
REMOTE=git@github.com:username/dotfiles.git

alias config='/usr/bin/git --git-dir=$HOME/$DOTFILES/ --work-tree=$HOME'
echo "$DOTFILES" >> $HOME/.gitignore
git clone --bare $REMOTE $HOME/$DOTFILES
config checkout

At this point, you might see an error message if you have existing configuration files on your machine in locations that are already tracked by Git in your dotfiles on the remote repository. If that’s the case, you can move them to a secure place like so:

 bash
 
mkdir -p .config-backup && \
config checkout 2>&1 | egrep "\s+\." | awk {'print $1'} | \
xargs -I{} mv {} .config-backup/{}

Let’s make sure we don’t show all untracked files again:

bash

config config --local status.showUntrackedFiles no

From here, this will be the same workflow as described in the section 2.1 On your current machine.

Conclusion

No more symlinks: this is definitely a nicer approach! You will need to be a bit more familiar with Git if you need to edit your Git history such as with the rebase sub-command or when adding changes selectively such as with the sub-command add -p to add files interactively — which might be the case if you want to commit only part of the changes made to one file — but that’s a great tool to master anyways, and there’s an article to get the ball rolling: Git the gist of it: common commands for a working workflow ;).

More resources and references

Git Bare Repository - A Better Way To Manage Dotfiles — DistroTube, YouTube
The best way to store your dotfiles: A bare Git repository, the source of the idea for this post. — Atlassian

Setting up SSH and Git for Multiple Accounts

Sébastien Lavoie — Sat, 03 Oct 2020 15:25:00 -0500

Introduction

To work effectively with services such as GitHub and GitLab, it is useful to set up a workflow that doesn’t get in the way, especially when multiple accounts are involved. SSH will be set up to avoid entering the username/password combination every time we interact with remote repositories and Git will be set up to work differently for each account while signing the commits potentially with different GPG keys.

In short, we need to do the following:

Set up SSH locally (in ~/.ssh/);
Set up SSH keys remotely (GitLab, GitHub, Bitbucket, etc.);
Set up Git locally (in ~/.gitconfig);
Set up GPG keys remotely (add our keys(s) to GitLab, GitHub, etc.);
Start interacting with remote repositories.

Setting SSH locally

First, let’s make sure we have some SSH keys to work with. The default location is ~/.ssh/id_rsa (you can just press Enter when asked to save to a path):

bash

$ ssh-keygen -t rsa -C "email@personal.com"

The next key should have a different path:

 bash
 
$ ssh-keygen -t rsa -C "email@work.com"
$ Enter file in which to save the key
 (/home/sglavoie/.ssh/id_rsa): /home/sglavoie/.ssh/id_rsa_work

Add the keys to the authentication agent like so:

bash

$ ssh-add /.ssh/id_rsa
$ ssh-add /.ssh/id_rsa_work

See which keys were added:

bash

$ ssh-add -l # list the keys

If you need to delete any keys that were cached prior to that:

bash

$ ssh-add -D

Now, we need a configuration file:

 bash
 
$ touch ~/.ssh/config
$ chmod 600 ~/.ssh/config

Let’s add some content in there, assuming we deal with GitHub and GitLab, both with a personal account and a work account:

 bash
 
 
 
AddKeysToAgent yes
Host github
 HostName github.com
 User git
 IdentityFile ~/.ssh/id_rsa
Host github-work
 HostName github.com
 User git
 IdentityFile ~/.ssh/id_rsa_work
Host gitlab
 HostName gitlab.com
 User git
 IdentityFile ~/.ssh/id_rsa
Host gitlab-work
 HostName gitlab.com
 User git
 IdentityFile ~/.ssh/id_rsa_work

The directive AddKeysToAgent yes is useful to avoid typing ssh-add path_to_key every time SSH is needed.
The Host can have any name we want, it doesn’t need to match the HostName.
The HostName is the address we need to access. This should be the same thing for all accounts using a particular service (here, GitHub or GitLab).
We can set the user to be git by default.
For each Host, we indicate which IdentityFile to use when trying to work with a remote repository.

Automatically load the keys from the Shell

For Zsh, the following can be added near the top of ~/.zshrc when using the ssh-agent plugin:

 bash
 
# Load multiple SSH keys
zstyle :omz:plugins:ssh-agent identities id_rsa id_rsa_work

With Oh-My-Zsh, the ssh-agent plugin should be contained in plugins like so:

 bash
 
plugins=(git ssh-agent fzf gitignore zsh-autosuggestions history-substring-search)

# Somewhere below
source $ZSH/oh-my-zsh.sh

With this setup, the SSH keys will be loaded when opening a terminal after booting up and those will be available for any subsequent terminal sessions until the user session is exited.

Setting SSH keys remotely

The process will be slightly different on each platform on which we want to authenticate, but the gist of it is to paste the content of the public SSH key in the field when asked to do so.

Setting Git locally

The idea is to have a ~/.gitconfig file from which we load the main Git configuration by default (let’s say, our personal account) and then we load another account – overwriting the Git settings of the personal account with the settings defined for that other account – whenever we navigate to a directory that relates to that other account. Let’s see this in action.

Minimal `~/.gitconfig`

 bash
 
 
 
# default configuration settings to load
[include]
 path = ~/.gitconfig-personal

# when working with company-x
# those settings are loaded only when the
# directory matches the pattern defined
[includeIf "gitdir:**/company-x/**/.git"]
 path = ~/.gitconfig-company-x
[gpg]
	program = gpg
[credential]
	helper = store

The [credential] section with the setting helper = store will store your username/password combination when using HTTPS so you don’t have to type it over and over again. You could also set this to helper = cache if you don’t want to permanently store credentials.
The includeIf directive will be triggered whenever you are in a directory containing company-x in this case so that your correct GPG key and Git settings will be used instead of the default settings for your personal account.
In the block [gpg], your system may be using the program gpg2 instead of gpg.

Minimal `~/.gitconfig-personal` and `~/.gitconfig-company-x`

Example for one of those:

 bash
 
 
 
[user]
 email = email@work.com
 name = Sébastien Lavoie
 signingkey = A343702EBE11E0C2
[commit]
 gpgsign = true

If you don’t have a GPG key already, you can generate one with this command:

bash

gpg --gen-key

To list existing GPG keys to determine the signinkey value to use in those files, you can type:

bash

gpg --list-secret-keys --keyid-format LONG

You might get an output similar to the following (this one is showing only one key):

 bash
 
 
 
sec rsa3072/A343702EBE11E0C2 2020-10-03 [SC] [expires: 2022-10-03]
 EF731EFC008D47D176C05910A343702EBE11E0C2
uid [ultimate] Sébastien Lavoie <email@work.com>
ssb rsa3072/718726CCFED43B47 2020-10-03 [E] [expires: 2022-10-03]

The bit you need to retrieve for the signingkey value comes after the type of encryption, here it’s rsa3072 and the bit we want is A343702EBE11E0C2.

If you need to edit a key, there are plenty of options described with man gpg or man gpg2. For instance, to remove the expiration date for the above key:

bash

gpg2 --edit-key EF731EFC008D47D176C05910A343702EBE11E0C2

At the gpg> prompt, type expire and follow the instructions.

To delete a key, you can do so by referring to the email address like this:

bash

gpg --delete-secret-and-public-key email@work.com

Just follow the instructions from there. You may need to repeat the process multiple times if your email address is associated with more than one key.

Setting GPG keys remotely

Just like with the SSH keys, the process differs from one platform to the other.

Interacting with remote repositories

Now that the Git configuration is set up and we have SSH and GPG keys to authenticate ourselves and verify our identity when committing, respectively, we can start interacting with remote repositories. From the example we have been following, the file ~/.gitconfig-personal will be used by default (and by consequence, our personal account).

The SSH part

When first cloning, change the host so that it reflects what you have in ~/.ssh/id_rsa_correct_key_file. For your personal account, no change would be required:

bash

git clone git@github.com:organization/repo.git

For a repository at work requiring the SSH key set up for the work account, you would need to change to the appropriate host like so (we still use the git user for convenience):

bash

git clone git@github-work:organization/repo.git

For a refresher, the following are the hosts we have set in ~/.ssh/config: github, github-work, gitlab, gitlab-work.

The difference will be noticed when pushing/pulling as seen with git remote -v:

 bash
 
$ git remote -v
origin	git@github-work:organization/repo.git (fetch)
origin	git@github-work:organization/repo.git (push)

Whereas the personal account will have the same host as usual, for instance git@github.com:organization/repo.git.

The GPG part

If we want to keep our personal and work Git configurations separate (and we probably want that! ;)), it’s only a matter of ensuring that the includeIf pattern contains, in this example, company-x somewhere in the path. When this is the case, we will see with git config --list in the cloned repository that our personal account details are loaded first, but if the includeIf directive matches, the settings for that other account will be applied on top and used when committing.

If you type git config --list and search for the word “email” in the output, it will appear only once when the default ~/.ssh/id_rsa key is used (or whatever is read for the IdentityFile from the SSH configuration file) while you will see that same personal email showing up first in a work repository, but then later in the output you will find the work email, work GPG key and so on.

Conclusion

This is one possible kind of setup we can use to work with SSH and GPG comfortably. This is pretty much a “set it and forget it” approach as long as you remember the following:

SSH: Change the SSH host when cloning. If the repository is not publicly available, it would fail anyways (or you may realize you can clone it if it’s a public repo but have no push access).
Git: Make sure you are in a directory where the includeIf directive will kick in to set up the email, GPG key and so on.

One nice tip to help with the latter bullet point could be to define an alias, say in ~/.bash_aliases, something like what follows:

 bash
 
cdwork='cd /path/to/work/dir/with/appropriate/pattern'

Then, you simply cdwork and store all your Git repositories for work under that root repository, which would always match the desired pattern by default. That’s it. Anything else related to the personal account can be cloned anywhere on the file system since this is the default configuration file used. For more Git-related content, you might enjoy reading Git the gist of it: common commands for a working workflow.

sglavoie.com – Tag: Git

Git worktrees for a better parallel workflow

Introduction

Why is git stash not enough?

Switching context

Running tasks in the background

How I operate worktrees

First, other approaches in the wild

What I actually do these days

Starting with a project with existing branches

New worktrees from a project already using worktrees

Keeping worktrees around

Conclusion

Resources and references

External links

From this website

Git the gist of it: common commands for a working workflow

Introduction

Global and local .gitignore

Meaningful commit messages with .gitmessage

My usual Git workflow

Starting a new project

Committing to an existing project

Being committed

rebase

Sample workflow

merge

Sample workflow (kinda)

Managing branches

Aliases

Custom Git sub-commands

Some lesser-known yet incredibly useful commands

git bisect

git rerere

A word on the configuration file

Conclusion

More resources and references

Websites

YouTube

Online courses

References for this article

Managing dotfiles with a Git bare repository

Introduction

1. Set up the system

1.1 Create a repository to host your dotfiles

1.2 Set the remote to track your dotfiles

2. Use the new system

2.1 On your current machine

2.2 On a different machine

Conclusion

More resources and references

Setting up SSH and Git for Multiple Accounts

Introduction

Setting SSH locally

Automatically load the keys from the Shell

Setting SSH keys remotely

Setting Git locally

Minimal ~/.gitconfig

Minimal ~/.gitconfig-personal and ~/.gitconfig-company-x

Setting GPG keys remotely

Interacting with remote repositories

The SSH part

The GPG part

Conclusion

Why is `git stash` not enough?

Global and local `.gitignore`

Meaningful commit messages with `.gitmessage`

`rebase`

`merge`

`git bisect`

`git rerere`

Minimal `~/.gitconfig`

Minimal `~/.gitconfig-personal` and `~/.gitconfig-company-x`