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).
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
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
| 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 overridescore.worktreeand discovery. - Be careful when setting GIT_DIR in your shell. Every
gitcommand, 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 withGIT_DIR=.and why youunset GIT_DIRbefore changing to another repository. - Hooks. Git sets
GIT_DIR(and sometimesGIT_INDEX_FILE,GIT_WORK_TREE) for hooks. In apre-commithookGIT_INDEX_FILEmay point at a temporary index, for example duringgit commit <file>; use plaingitcommands, not hard-coded.git/index. - Bare plus work tree. The dotfiles trick in the first example needs
status.showUntrackedFiles no, otherwisegit statuslists everything else in your home directory as untracked. - Detection of a bare repository. If the current directory has no
.gitbut looks like a repository itself (it hasHEAD,objectsandrefs), Git treats it as bare.git rev-parse --is-bare-repositorytells 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 explicitGIT_DIRyou chose. - Ceilings are useful in tests and scripts, to stop a stray
.gitin a parent directory (a home directory that is accidentally a repository) from capturing a directory that should not be inside one. GIT_INDEX_FILEis how scripts build trees and commits without touching the real staging area. Combine it withgit read-tree,git add,git write-treeandgit commit-tree.- A relative
GIT_DIRis resolved against the directory where the command starts. Prefer absolute paths.