Git Reference ยท Files and Formats
The .git file and commondir
Reference for the .git file (gitdir: pointer) used by linked worktrees and submodules, plus the gitdir, commondir and locked files in .git/worktrees.
Normally .git is a directory. In a linked worktree or a submodule it is a small text file instead, containing a single line gitdir: <path>. Git follows that line to find the real repository data, so the working directory can be anywhere while the object database lives elsewhere.
For linked worktrees there is a second level: each worktree has its own private directory under the main repository's .git/worktrees/<name>/, holding its HEAD, its index and two small pointers, gitdir and commondir. Shared data (objects, branches, tags, config) stays in the main repository, the "common directory".
# contents of a linked worktree's .git file
gitdir: /path/to/main/.git/worktrees/feature
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
gitdir: <path>
| File | Where | Contents |
|---|---|---|
.git (file) |
Root of a linked worktree or a submodule | One line, gitdir: <path>. The path may be absolute or relative to the file. |
.git/worktrees/<id>/gitdir |
Main repository | Absolute path to the linked worktree's .git file; lets git worktree prune see if the worktree has vanished. |
.git/worktrees/<id>/commondir |
Main repository | Path to the common directory, normally ../... |
.git/worktrees/<id>/locked |
Main repository | Present when the worktree is locked; the file holds the reason (may be empty). |
.git/worktrees/<id>/HEAD, index |
Main repository | The worktree's own HEAD and index. |
Per-worktree vs shared: HEAD, the index, refs/bisect, refs/worktree and refs/rewritten are per worktree. Branches, tags, remotes, config and objects are shared.
Edge cases: if the main repository moves, the linked worktrees' pointers break; git worktree repair rewrites them. A branch can be checked out in only one worktree at a time.
Usage notes
git rev-parse --git-dirvs--git-common-dir. In a linked worktree they differ; in an ordinary repository they are the same.- Never copy the working tree folder alone. The
.gitfile points at the original repository, so the copy is not independent. - Moving. Use
git worktree moveandgit submodulecommands; they update pointers on both sides. If you moved things by hand, rungit worktree repair. - Pruning.
git worktree pruneremoves administrative data for deleted worktrees, except locked ones. - Submodule data lives in the parent's
.git/modules/<name>. That is what lets you delete a submodule's folder and restore it without re-cloning. core.worktreecan point a repository at its working tree; the submodule setup uses it in.git/modules/<name>/config.- Editors and scripts. Don't assume
.gitis a directory; test withgit rev-parserather than[ -d .git ]. - Separate git dir.
git init --separate-git-diruses the same gitfile mechanism.