Skip to content
Tutorials Center
My learning

Topics

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".

Terminal
# contents of a linked worktree's .git file
gitdir: /path/to/main/.git/worktrees/feature

Try it

Bash Inspect a linked worktree

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.

Bash Submodules use a gitfile too

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

Terminal
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-dir vs --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 .git file points at the original repository, so the copy is not independent.
  • Moving. Use git worktree move and git submodule commands; they update pointers on both sides. If you moved things by hand, run git worktree repair.
  • Pruning. git worktree prune removes 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.worktree can point a repository at its working tree; the submodule setup uses it in .git/modules/<name>/config.
  • Editors and scripts. Don't assume .git is a directory; test with git rev-parse rather than [ -d .git ].
  • Separate git dir. git init --separate-git-dir uses the same gitfile mechanism.