git-annex/ tips/ Using git-worktree with annex

Git worktrees are supported since version 6.20180719.

Git normally makes a `.git` file in a worktree, that points to the real git repository under `.git/worktrees/`. This presents problems for git-annex. So, when used in a worktree, git-annex will automatically replace the `.git` file with a symlink pointing at the git repository. It also places an appropriate `annex` link to `.git/worktrees/<name>/annex` to point to the object store. I don't know how crippled filesystems are handled.

Getting, dropping and syncing content works fine in a worktree, however if there is change in the tree then syncing doesn't update git worktrees and their indices, but updates the checked out branches. This is different to the handling of the main working directory as it's either got updated or left behind with its branch if there is a conflict.

In its current state I use git-worktree to copy symlinks across branches and run `git annex fix` on them. I only use temporary worktrees due to the syncing behavior.

worktrees vs. bare repositories

Note that while bare repos can have worktrees in git, the combination is not really supported in git-annex; as a result,

- `git annex add` doesn't work ("You cannot run this command in a bare repository.") and
- `git annex fix` would change all object links from two-character (`../.git/annex/objects/KP/4p/SHA256...`) to three-character (`../.git/annex/objects/7e3/613/SHA256...`) names.

Comment by https://christian.amsuess.com/chrysn — Wed Oct 29 14:05:27 2025
Comments on this page are closed.