Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash A ceiling hides the repository above 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.

Bash Ceilings equal to the current directory, lists, and a safe home directory

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
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. Put export GIT_CEILING_DIRECTORIES="$HOME" in your shell profile. Projects below your home directory still work; a forgotten ~/.git can no longer swallow everything.
  • Prompt and status tools that run git in 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=1 because the repository root sits on a different mount than the project folder.
  • Explicit settings win. If GIT_DIR is set, or you pass --git-dir, no discovery happens and the ceiling is irrelevant.
  • Debug with GIT_TRACE_SETUP=1 to see which directory Git decided on.
  • Security angle: discovery from an untrusted parent directory can pick up a malicious repository's configuration; safe.directory protects ownership mismatches, and ceilings reduce the surface further.