Git Reference ยท Environment Variables
GIT_CEILING_DIRECTORIES
Reference for GIT_CEILING_DIRECTORIES and GIT_DISCOVERY_ACROSS_FILESYSTEM: stop Git from walking up the directory tree when it looks for a repository.
When you run git status in ~/project/src/deep/, Git does not require a .git there. It starts in the current directory and climbs, one parent at a time, until it finds a directory containing .git (or a bare repository) or reaches the file-system root. That is why Git works from any subfolder.
GIT_CEILING_DIRECTORIES is a colon-separated list (semicolon on Windows) of directories Git must not climb into. It protects against two problems: a slow network mount somewhere above you, and a stray repository, such as an accidental git init in your home directory, that would otherwise capture every project beneath it.
export GIT_CEILING_DIRECTORIES=/home/ada # never look in /home/ada or above GIT_CEILING_DIRECTORIES=/srv/mnt:/net git status # several ceilings
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
GIT_CEILING_DIRECTORIES=<dir>[:<dir>...] git <command> GIT_DISCOVERY_ACROSS_FILESYSTEM=<bool> git <command>
| Name | Description |
|---|---|
GIT_CEILING_DIRECTORIES |
Absolute directories (separated by :; ; on Windows) that Git will not climb into while searching. |
GIT_DISCOVERY_ACROSS_FILESYSTEM |
If unset or false, Git will not cross from one mounted file system to another while climbing. Set it to 1 to allow crossing. |
Rules: a ceiling stops the search before that directory is examined, so a repository whose root is a ceiling is not found from below it. A ceiling that equals the directory you are standing in has no effect, and entries that do not exist are skipped. Entries should be absolute, normalized paths; symbolic links are not resolved for the comparison unless you list the real path.
Failure mode: when the climb stops without finding a repository, Git reports fatal: not a git repository (or any of the parent directories): .git, the same message as for a plain directory.
Usage notes
- Protect against a repository in
$HOME. Putexport GIT_CEILING_DIRECTORIES="$HOME"in your shell profile. Projects below your home directory still work; a forgotten~/.gitcan no longer swallow everything. - Prompt and status tools that run
gitin every directory you visit become slow on network shares; ceilings on those mount points keep the prompt snappy. - File-system boundary: the default of not crossing mounts avoids climbing out of a container or a bind mount into an unrelated host repository. Containers sometimes need
GIT_DISCOVERY_ACROSS_FILESYSTEM=1because the repository root sits on a different mount than the project folder. - Explicit settings win. If
GIT_DIRis set, or you pass--git-dir, no discovery happens and the ceiling is irrelevant. - Debug with
GIT_TRACE_SETUP=1to see which directory Git decided on. - Security angle: discovery from an untrusted parent directory can pick up a malicious repository's configuration;
safe.directoryprotects ownership mismatches, and ceilings reduce the surface further.