Git Separate Work Tree

Git is commonly associated with a repository that contains a .git directory at its root. However, Git internally supports a more flexible model in which the repository metadata and the working tree are completely independent.

This capability is based on two concepts:

• GIT_DIR – the location of the Git repository (objects, refs, index, configuration, etc.).
• GIT_WORK_TREE – the directory that Git treats as the working tree.

By separating these two locations, a single repository can manage files located outside the repository directory itself.

Basic Example

A bare repository can be created in one location while using another directory as its working tree.

git init --bare ~/.myrepo.git

git \
  --git-dir="$HOME/.myrepo.git" \
  --work-tree="$HOME" \
  status

The same configuration can be achieved using environment variables:

export GIT_DIR="$HOME/.myrepo.git"
export GIT_WORK_TREE="$HOME"

Tracking Arbitrary Files

Since the working tree is independent from the repository metadata, Git can track any files located under the chosen work tree.

For example, if the working tree is your home directory, you can selectively track files such as:

• ~/.bashrc
• ~/.gitconfig
• ~/.config/...
• project configuration files
• other selected files scattered throughout the directory hierarchy

Only the files explicitly added to the repository are tracked.

Tracking Files Inside Other Git Repositories

This mechanism also allows tracking individual files that happen to reside inside directories which are themselves separate Git repositories.

This works because the outer repository has its own GIT_DIR and index, completely independent from the inner repository.

Care should be taken to add only the desired files rather than entire embedded repositories, as Git has special handling for nested repositories.

Typical Use Cases

This feature is useful for:

• managing dotfiles
• backing up configuration files
• maintaining system configuration
• selectively versioning files spread across a filesystem
• keeping repository metadata separate from the files being tracked

Tools Built on This Mechanism

Several well-known tools are essentially wrappers around Git’s separate GIT_DIR / GIT_WORK_TREE functionality:

• vcsh — manages multiple Git repositories over a single home directory.
• yadm — a dotfile manager built on Git.
• chezmoi — uses Git as a storage backend while providing additional deployment and templating features.
• GNU Stow (often combined with Git) — although not based directly on this mechanism, it is frequently used alongside it for dotfile management.

These tools primarily provide convenience features, automation, and workflow improvements. The underlying capability comes from Git itself rather than from the tools.