Git & collaboration

Git is the tool you touch on every working day, and most of the trouble people have with it comes from not knowing where a change currently lives. This section gives you that model first, then the handful of commands that follow from it: branching, merging, undoing safely, and finding the commit that broke something. Without it you lose work that was never recoverable, or produce a pull request nobody can review.

A repository is a graph of commits#

Almost every confusing thing git does stops being confusing once you hold one picture: a repository is a graph of commits, each one pointing back at the commit or commits it came from, and a branch is nothing but a name stuck to one node in that graph. Every command in this section either adds a node, moves a name, or both. Build a small repository and look at it rather than taking that on trust.

mkdir demo && cd demo && git init -b main
git config user.name Ada && git config user.email ada@example.com

for n in 1 2 3; do echo "line $n" >> app.py; git add app.py; git commit -m "commit $n"; done
git switch -c feature
echo "feature work" >> feature.py && git add -A && git commit -m "add feature.py"
echo "more feature" >> feature.py && git add -A && git commit -m "extend feature.py"
git switch main
echo "line 4" >> app.py && git add -A && git commit -m "commit 4 on main"

git log --graph --oneline --all

* 435ccff extend feature.py
* b2245a1 add feature.py
| * fdd7b5c commit 4 on main
|/
* 5c7464c commit 3
* 480943e commit 2
* 10a008f commit 1

Now look at what the pieces actually are, because both are smaller than people expect. A branch is a forty-character file. A commit is a snapshot plus a pointer to its parent.

cat .git/refs/heads/main
# fdd7b5c434ebec6f9e0859fabb8b54eb66d18ef7

cat .git/HEAD
# ref: refs/heads/main

git cat-file -p HEAD
# tree f74d34831129b127c5c4d7a4376604a2e499fea2
# parent 5c7464c29e79ff0dc498534a9a52465a45d3d87e
# author Ada <ada@example.com> 1789324096 +0530
# committer Ada <ada@example.com> 1789324096 +0530
#
# commit 4 on main

Three consequences follow directly, and between them they answer most beginner questions. Creating and deleting branches is free and reversible, because the commits are not stored in the branch — the branch only names one of them. A commit is identified by a hash of its content, its parents and its metadata, so any command that changes a commit's contents or its parent produces a different commit with a different hash rather than editing the old one. And nothing in the graph is ever removed by an ordinary command: commits that no branch points at are still on disk, which is what makes the recovery moves in the next section work.

Three places#

Alongside the graph there is the staging area, and most day-to-day confusion comes from not knowing which of three places a change is in. The working directory is your files. The staging area is what you have marked for the next commit. The repository is committed history.

git status                # what is where, read this constantly
git add file.py           # working directory -> staging
git commit -m "message"   # staging -> repository
git push                  # repository -> remote

Branching#

git switch -c feature/retrieval-eval    # create and move to it
git switch main                        # move back
git branch -d feature/retrieval-eval   # delete when merged

Branch names are read by other people. A name describing the change beats a ticket number alone, and a ticket number plus a description beats both.

Merge or rebase#

Merge keeps both histories and adds a merge commit. Rebase replays your commits on top of the target, producing a straight line. Rebase makes history readable, and it rewrites commits, which is why it has a rule attached.

In the graph both are one sentence. Merge adds a node with two parents and moves the branch name onto it. Rebase makes new copies of your commits with a different parent, then moves the branch name onto the last copy. Run each on a copy of the demo repository and compare.

git switch main && git merge feature          git switch feature && git rebase main

*   d983e7b Merge branch 'feature'               * 24e98d7 extend feature.py
|\                                               * e5ebea2 add feature.py
| * 435ccff extend feature.py                    * fdd7b5c commit 4 on main
| * b2245a1 add feature.py                       * 5c7464c commit 3
* | fdd7b5c commit 4 on main                     * 480943e commit 2
|/                                               * 10a008f commit 1
* 5c7464c commit 3
* 480943e commit 2
* 10a008f commit 1

That right-hand column is the whole reason for the rule below. The old commits b2245a1 and 435ccff still exist on your disk, but nothing points at them any more, and anyone else who had fetched them now holds commits that your branch has never heard of. Their git will offer to merge the two versions of the same work back together, which produces every commit twice.

The merge commit on the left is also worth one more look, because it is the only kind of commit with two parents and that shape matters later. It is what lets git work out, for any commit, whether it is an ancestor of main, which is how a pull request knows it has been merged. It is also why reverting a merge needs telling which of the two parents to keep, covered in the recovery section. And if main had not moved since the branch left, git would not have created a node at all: it would simply have slid the name main forward onto the branch tip, which is what the phrase fast-forward means.

What reset actually resets#

Reset is the command people are most afraid of, and the fear is aimed at the wrong part of it. Reset always moves the current branch name to the commit you give it. The flag decides which of the other two places follow it there. Here is the same repository, reset back one commit three times, with the resulting status and the contents of the file.

git reset --soft  HEAD~1   HEAD=5c7464c   status: M_ app.py   app.py has 4 lines
git reset --mixed HEAD~1   HEAD=5c7464c   status: _M app.py   app.py has 4 lines
git reset --hard  HEAD~1   HEAD=5c7464c   status: (clean)     app.py has 3 lines

M_  staged: the change is in the index, ready to commit again
_M  not staged: the change is in your files only
--hard  the fourth line is gone from the file, and was never committed elsewhere

Read from that what each is for. Soft reset is how you squash the last few commits into one: move back three, everything is staged, commit once. Mixed reset is how you unstage and rethink what belongs in the commit. Hard reset is how you throw the work away, and it is the only one of the three that can lose anything, because the commits it leaves behind are still recoverable through the reflog while uncommitted file changes are not.

Undoing#

git restore file.py              # discard uncommitted changes to a file
git restore --staged file.py     # unstage, keep the changes
git commit --amend               # fix the last commit (before pushing)
git revert <sha>                 # undo a commit with a new commit, safe
git reset --hard <sha>           # move the branch, DESTROYS uncommitted work

git reflog                       # the safety net: every state you have been in

Prefer revert to reset on anything shared. Revert adds a commit that undoes the change, which is honest history. Reset pretends the change never happened, which breaks everyone who already has it.

Finding when something broke#

git bisect start
git bisect bad                   # current state is broken
git bisect good v1.4             # this version was fine
# git checks out midpoints; mark each good or bad
git bisect reset

Pull requests#

• Keep them small. A 2000-line pull request gets approved without being read, which is worse than not being reviewed.
• One concern per pull request. Refactoring and behaviour change together makes both unreviewable.
• Write the description for someone who was not in the conversation: what, why, and what you considered.
• Review your own diff before requesting review. You will find something, every time.

Data and model weights do not belong in git. Git stores a full copy of every version of a binary file, so a repository with model checkpoints in it becomes unusable quickly, and because history is immutable the size never comes back down once it has gone in — removing the file in a later commit leaves every earlier copy in the history that everyone clones. Use object storage with a versioned path, or a dedicated data versioning tool, and commit the reference.

What to skip#

Git has a very large surface and most of it is never used by working engineers. The commands above, plus the recovery moves in the next section, cover essentially everything that comes up on a normal team. A few things are worth deliberately not learning until something forces you to.

• Submodules. They solve a real problem badly and every team that adopts them spends time on them forever. If you are given a repository that uses them, learn git submodule update --init --recursive and no more.
• Branching models with names. Gitflow and the rest are process documents rather than git features, and the branch commands underneath are the ones above. Learn the model your team uses when you join it.
• Interactive rebase beyond squashing. Reordering, splitting and editing old commits is worth knowing exists and is not worth practising. Squashing before review covers almost every real need.
• Custom merge drivers, git hooks written by hand, and anything involving git filter-branch. Modern equivalents exist, and the cases that need them are rare enough that you should read the documentation at the time rather than carrying it around.
• Memorising flags. The four worth having in your fingers are git status, git log --oneline --graph, git diff and git reflog. Everything else can be looked up without the lookup costing you anything.

This section is the set of moves for the moment something in git has gone wrong: commits that seem to have vanished after a reset or a rebase, a change you need to undo, a merge conflict, or a secret that is now in the history. The fact that makes most of it recoverable is that git almost never throws anything away, and the reflog lists every position HEAD has held. The exception is the leaked secret, which is why that part starts with revoking the key rather than rewriting history.

You almost never lose a commit#

git reflog                     # every place HEAD has been, with ids
git branch rescue 3f9c2a1      # put a branch on the commit you thought was gone

After a bad reset or rebase, the old commits still exist for weeks. The reflog lists them. Find the one you want and point a branch at it.

Worth doing once for real, in a repository you do not care about, so that the muscle exists before the panic does. Here is a hard reset two commits too far and the recovery, in a scratch repository. Your hashes will differ.

git log --oneline -1
# fdd7b5c commit 4 on main

git reset --hard HEAD~2
git log --oneline -1
# 480943e commit 2                 <- two commits of work apparently gone

git reflog -4
# 480943e HEAD@{0}: reset: moving to HEAD~2
# fdd7b5c HEAD@{1}: commit: commit 4 on main
# 5c7464c HEAD@{2}: checkout: moving from feature to main
# 435ccff HEAD@{3}: commit: extend feature.py

git reset --hard 'HEAD@{1}'      # or the hash; quote it, the braces are shell syntax
git log --oneline -1
# fdd7b5c commit 4 on main

A deleted branch is the same problem with one extra step, because the branch name is gone and so its own reflog went with it. Two things still know where it was. The delete command printed the hash, and the HEAD reflog recorded every commit you made while you were on it.

git branch -D feature
# Deleted branch feature (was 435ccff).        <- keep this line

git reflog | grep feature
# 5c7464c HEAD@{3}: checkout: moving from feature to main
# 435ccff HEAD@{4}: commit: extend feature.py
# b2245a1 HEAD@{5}: commit: add feature.py
# 5c7464c HEAD@{6}: checkout: moving from main to feature

git branch feature 435ccff
git log --oneline -1 feature
# 435ccff extend feature.py

The one thing that is genuinely lost is work that was never committed. A hard reset overwrites your files from the commit, and there is no record of what was in them, so a morning of uncommitted editing is simply gone. There is an exception worth knowing, and it is the strongest argument for staging work you are not ready to commit: git add writes the file into the object database immediately, and objects are not deleted by reset.

echo "half an hour of work" >> app.py
git add app.py                   # this line is the difference
git reset --hard
git status --short               # nothing: the file is back to the committed version

git fsck --lost-found
# dangling blob 8233b38978eca16f6ab63b4fc1475cb5fc945dd2

cat .git/lost-found/other/8233b38978eca16f6ab63b4fc1475cb5fc945dd2
# line 1
# line 2
# line 3
# line 4
# half an hour of work

Which undo?#

Discard changes to a file you have not committed   git restore <file>
Unstage a file                                      git restore --staged <file>
Undo local commits not yet pushed                   git reset <commit>   (keeps changes)
Undo a commit that others already have              git revert <commit>  (new commit)

The rule: never rewrite history other people have pulled. Revert adds a new commit that undoes the old one, which is safe on shared branches.

Merge conflicts#

A conflict means both sides changed the same lines. Git marks them in the file. Read both versions, decide what the result should be, which is sometimes a mix, remove the markers, run the tests, then add and continue. If it goes badly, git merge --abort or git rebase --abort returns you to where you started.

The default markers give you less than you need, and it is worth seeing why on a small one. Two branches both edited a two-line config file: main changed the timeout from 30 to 45 and the retries from 3 to 5, the other branch changed only the timeout, to 120.

git merge raise-timeout
# Auto-merging config.py
# CONFLICT (content): Merge conflict in config.py
# Automatic merge failed; fix conflicts and then commit the result.

cat config.py
# <<<<<<< HEAD
# TIMEOUT = 45
# RETRIES = 5
# =======
# TIMEOUT = 120
# RETRIES = 3
# >>>>>>> raise-timeout

Read that as it stands and you have a genuine choice to make about TIMEOUT and an invented one about RETRIES. Only one side touched RETRIES, so 5 is simply the newer value and 3 is what it always was, but the markers do not tell you that and picking a side at random here quietly reverts someone's work. Turning on a conflict style that also shows the common ancestor fixes it permanently.

git config --global merge.conflictStyle zdiff3     # needs git 2.35 or newer

git merge --abort && git merge raise-timeout
cat config.py
# <<<<<<< HEAD
# TIMEOUT = 45
# RETRIES = 5
# ||||||| bcf6972
# TIMEOUT = 30
# RETRIES = 3
# =======
# TIMEOUT = 120
# RETRIES = 3
# >>>>>>> raise-timeout

With the base visible the resolution is mechanical: for each hunk, work out what each side did to the base, and write the file that does both. Here that is TIMEOUT = 120 and RETRIES = 5, which is a line neither branch contains. That is normal and is the reason the advice is to resolve rather than to choose a side; the tooling offers you --ours and --theirs and they are almost always both wrong.

# edit config.py to the version that is actually correct, markers removed
git add config.py
git status --short
# M  config.py
git commit --no-edit          # keeps the generated merge message

git log --graph --oneline --all
# *   6979262 Merge branch 'raise-timeout'
# |\
# | * e2cea00 raise timeout for slow model calls
# * | 9d9cc89 tune timeout and retries
# |/
# * bcf6972 base config

One consequence of that two-parent shape, which catches people out perhaps once in a career and is unpleasant when it does: reverting a merge needs telling which side to keep. A merge undid nothing on its own, so undoing it is ambiguous, and git refuses to guess.

git revert HEAD
# error: commit 6979262629e9e33b0ccc42687601201053afe878 is a merge but no -m option was given.
# fatal: revert failed

git revert -m 1 HEAD          # -m 1 means "keep the first parent", which is the branch
                              # you merged into, almost always main
cat config.py
# TIMEOUT = 45
# RETRIES = 5                 <- main as it was before the merge

Small tools#

• git stash puts uncommitted changes aside so you can switch branches; git stash pop brings them back.
• git cherry-pick <commit> copies one commit onto the current branch, useful for moving a fix to a release branch.

A secret was committed#

1. 1.Revoke and replace the secret immediately. Assume it is already compromised; deleting it from git does not un-leak it.
2. 2.Then remove it from the code and history if your team's policy requires, which rewrites history and needs coordination.
3. 3.Add a secret scanner to pre-commit or CI so it does not happen again.