Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Environment Variables

GIT_DIR and GIT_WORK_TREE

Reference for GIT_DIR, GIT_WORK_TREE, GIT_INDEX_FILE, GIT_COMMON_DIR and GIT_CEILING_DIRECTORIES: how Git finds a repository and how to point it elsewhere.

Normally you never tell Git where the repository is. It starts in the current directory and walks upward until it finds a .git directory (or a bare repository), and the directory that holds .git is the working tree. A handful of environment variables, and matching command-line options, override this search. They matter for hooks and scripts, for keeping the repository away from the files it tracks (the well-known "bare repo for dotfiles" setup), and for deployment servers.

The main variables are GIT_DIR (where the repository's data lives), GIT_WORK_TREE (the top of the files it tracks), GIT_INDEX_FILE (which index to use), GIT_COMMON_DIR (the part shared between linked worktrees) and GIT_CEILING_DIRECTORIES (where the upward search must stop).

Terminal
GIT_DIR=/path/to/repo.git GIT_WORK_TREE=/path/to/files git status
git --git-dir=/path/to/repo.git --work-tree=/path/to/files status
git -C /path/to/files status        # change directory first, then discover normally

Try it

Bash Keep the repository away from the files

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 Discovery, ceilings and a private index

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

Variable / option Description
GIT_DIR / --git-dir=<path> The repository directory (the .git folder or a bare repository). Skips discovery completely. Without GIT_WORK_TREE, the current directory is taken as the top of the working tree.
GIT_WORK_TREE / --work-tree=<path> The top of the working tree. Also settable per repository with core.worktree.
GIT_INDEX_FILE Path of the index file to read and write instead of $GIT_DIR/index.
GIT_COMMON_DIR The directory that holds the data shared between linked worktrees (objects, refs, config). Git sets it for you in worktrees.
GIT_OBJECT_DIRECTORY Where object files are stored instead of $GIT_DIR/objects.
GIT_ALTERNATE_OBJECT_DIRECTORIES Extra object stores to read from, separated by : (; on Windows).
GIT_CEILING_DIRECTORIES Colon-separated absolute paths. Discovery does not look in these directories or above them.
GIT_DISCOVERY_ACROSS_FILESYSTEM Set to true to let discovery cross file-system boundaries, which it does not do by default.
-C <path> Not a variable: runs Git as if started in <path>. Can be repeated.

Usage notes

  • Order of precedence. Command-line options (--git-dir, --work-tree) override the environment, and the environment overrides core.worktree and discovery.
  • Be careful when setting GIT_DIR in your shell. Every git command, in any directory, then operates on that repository. Setting it in a hook is the classic way to confuse a script, which is why servers' hooks run with GIT_DIR=. and why you unset GIT_DIR before changing to another repository.
  • Hooks. Git sets GIT_DIR (and sometimes GIT_INDEX_FILE, GIT_WORK_TREE) for hooks. In a pre-commit hook GIT_INDEX_FILE may point at a temporary index, for example during git commit <file>; use plain git commands, not hard-coded .git/index.
  • Bare plus work tree. The dotfiles trick in the first example needs status.showUntrackedFiles no, otherwise git status lists everything else in your home directory as untracked.
  • Detection of a bare repository. If the current directory has no .git but looks like a repository itself (it has HEAD, objects and refs), Git treats it as bare. git rev-parse --is-bare-repository tells you.
  • Safety. Since Git 2.35.2, Git refuses repositories owned by another user unless the path is listed in safe.directory. That check applies to discovery, not to an explicit GIT_DIR you chose.
  • Ceilings are useful in tests and scripts, to stop a stray .git in a parent directory (a home directory that is accidentally a repository) from capturing a directory that should not be inside one.
  • GIT_INDEX_FILE is how scripts build trees and commits without touching the real staging area. Combine it with git read-tree, git add, git write-tree and git commit-tree.
  • A relative GIT_DIR is resolved against the directory where the command starts. Prefer absolute paths.