Worktrees and bigger projects

The interactive lesson needs JavaScript. The text below is the complete lesson.

After this lesson you can

• work on two branches at once with git worktree add, and clean up afterwards with git worktree remove or git worktree prune apply
• write patterns in .gitignore and delete untracked files safely with git clean -n before git clean -f apply
• explain what Git LFS and hooks solve, and what they do not guarantee understand

Understand: More folders, and things that do not belong in Git

A working tree shows one branch at a time. git worktree add creates an extra working tree for the same repository, here with a new branch, hotfix. It has its own HEAD, its own staging area and its own files, but commits and branches are shared.

A commit made in one folder is visible in the other at once, because it is the same repository. Here hotfix gets the commit H.

In bigger projects, files show up that should never go into Git, like logs and build output. Patterns in .gitignore make Git stop showing them as untracked. That applies only to files that are not already tracked, so .gitignore removes nothing from the history.

git clean deletes untracked files, and Git has no copy to restore them from. That is why you always run git clean -n first, which only shows what would be deleted. Untracked folders need -d, and ignored files stay unless you add -x.

Large binary files, like video or data sets, fit Git poorly. Every version stays in the history, and an ordinary clone downloads all of them. Git LFS is a separate add-on that stores a small pointer in Git and the file itself on a separate server.

Hooks are scripts Git runs at events, for example before a commit or a push. They live in your local .git folder, are not cloned and can be skipped. Rules the team must rely on belong in CI or on the server.

Watch: An urgent fix in a folder of its own

We are on feature in the middle of a search feature. search.txt is modified and not committed. Then an urgent fix comes in that must start from main.

$ git status --short

Instead of stashing, we create a new working tree next to this one, ../hotfix. With -b it gets a new branch, hotfix, starting at main. What happens to the unfinished change?

$ git worktree add -b hotfix ../hotfix main

git worktree list shows both folders, which commit each is on and which branch each has checked out. It is still just one repository.

$ git worktree list

We step into the new folder. The graph and the file panel still show the first folder, but it is the same repository.

$ cd /course/hotfix

Here we make the fix and commit it. Watch the graph: hotfix gets a new commit, even though we committed in another folder.

$ echo "Contact: support@example.com" >> README.md && git commit -am "Add support contact"

Then we go back to the first folder.

$ cd /course/you

The unfinished work is right where it was. We have not stashed, committed or switched branches here.

$ git status --short

The fix is committed on hotfix, so the folder is no longer needed. git worktree remove deletes the folder, but the branch and the commit stay. Afterwards you merge hotfix into main as usual.

$ git worktree remove ../hotfix

Tasks

1. See which files have unfinished changes.
2. Create an extra worktree ../hotfix with a new branch hotfix starting at main.
3. List the repository's worktrees.
4. Make the fix in the hotfix folder: add a line to README.md and commit it on hotfix.
5. Remove the extra working folder, but keep the branch.

Watch: Ignore and clean up safely

A project quickly gathers clutter: a build folder, a log file and a scratch note. None of them should go into Git.

$ mkdir -p build && echo "binary" > build/app.bin && echo "debug output" > debug.log && echo "draft idea" > scratch.txt

Git shows all three as untracked. With many such files, the important changes drown in noise.

$ git status --short

We write two patterns in .gitignore. The first matches every file ending in dot log. The second matches the whole build folder.

$ printf '*.log\nbuild/\n' > .gitignore

.gitignore is an ordinary file. We commit it, so the whole team gets the same rules. Now only the scratch note is left as untracked.

$ git add .gitignore && git commit -m "Ignore logs and build output"

Before deleting anything, we ask what would disappear. -n means dry run. What do you think is on the list?

$ git clean -n

The list looked right, so we delete with -f. The scratch note is gone for good, while the log and the build folder remain.

$ git clean -f

Tasks

1. Make Git ignore all log files and the whole build folder.
2. Commit the ignore rules.
3. See what Git would delete, without deleting anything.
4. Delete the untracked scratch note, but leave the ignored files alone.

Practise: Transfer: a review and a clean-up

You are on main with an unfinished change in README.md. The branch docs already exists. The folder also has two untracked files, and last week you deleted an old worktree folder, ../old-review, by hand. No demo this time.

Tasks

1. Git still remembers the old folder ../old-review, even though it is gone. Clean up Git's records of worktrees.
2. A colleague asks you to fix the guide on the branch docs now. Check out the existing branch docs in a folder of its own, ../docs, without touching your README change.
3. In the docs folder: add a line to guide.txt and commit it. Then remove the extra folder. The commit must stay on docs.
4. Tidy the main folder. Make Git ignore every file ending in .tmp, and commit the rule. Then delete the other untracked files. Your README change must still be there.

Check yourself: Recall it

The branch hotfix is checked out in ../hotfix. In the main folder you type git switch hotfix. What happens?

• Git switches, and both folders now show hotfix
• Git refuses, because the branch is already checked out in another worktree
• Git moves the folder ../hotfix here

secret.env was committed last week. Today you add secret.env to .gitignore and commit. Is the secret safe now?

• Yes, ignored files are no longer pushed
• No. The file is still tracked, and the old commits contain the secret
• Yes, once git clean -fX has removed it

The project needs large video files that change often. What fits?

• Commit them as ordinary files, Git compresses them anyway
• Git LFS, which stores a pointer in Git and the content on a separate server
• Put them in .gitignore, so they take up no space

The team wants to make sure code that does not compile never lands on main. Is a pre-push hook enough?

• Yes, hooks come along to everyone who clones
• No, hooks are local and can be skipped. The rule must be enforced on the server, with required CI checks and a protected main
• Yes, if the hook is committed in a hooks/ folder in the repository

Review from “Fetch, pull and push”: Ada makes a commit in her own clone and pushes it to main. When do you see it in your repository?

• At once, just like in a worktree
• As soon as she pushes, without you doing anything
• When you run git fetch, and then as origin/main

Common misconceptions

• “A worktree is a new clone.” All worktrees share the same repository, with the same commits and branches.
• “git clean can be undone.” Git keeps no saved copy of what untracked files contain now. What it deletes is gone.
• “.gitignore hides secrets.” It applies only to untracked files. Anything already committed is still in the history.

$ git worktree list
/course/you    78e95ce [main]
/course/hotfix 78e95ce [hotfix]
/course/review 78e95ce [docs] prunable
$ git worktree prune --dry-run --verbose
Removing worktrees/review: gitdir file points to non-existent location
$ git worktree prune

$ git check-ignore -v build/output.log
.gitignore:2:build/ build/output.log

$ printf '* text=auto\n*.sh text eol=lf\n*.png binary\n' > .gitattributes
$ git check-attr -a -- src/app.sh
src/app.sh: text: set
src/app.sh: eol: lf

$ git submodule add https://example.com/lib.git vendor/lib
$ git ls-files --stage vendor/lib
160000 2ac14ea53dae7e4f874f013b705d31dc30124a99 0   vendor/lib

$ git bundle create ../backup.bundle --all
$ git bundle verify ../backup.bundle
...
../backup.bundle is okay