In Git, when is the repository directory not the .git folder beside your files?

## Discovery, and how it is overridden By default Git walks up from the current directory looking for `.git`. What it finds may be a directory (the ordinary case) or a **file**, and either way the environment can override the whole search. ## Case 1: .git as a file A `.git` file contains exactly one line: `gitdir: <path to the real repository directory>` The path may be absolute or relative. Three common producers: - **Linked worktrees.** `git worktree add` creates a second checkout of the same repository in another directory. Its `.git` file points at `.git/worktrees/<name>` inside the main repository. That per-worktree directory holds the things that must be private to this checkout — its own `HEAD`, `index` and `ORIG_HEAD` — while a `commondir` entry redirects shared state (objects, most refs, config) back to the main repository. That is why every worktree sees the same commits and cannot check out the same branch twice. - **Submodules.** Modern Git stores a submodule's repository in the superproject under `.git/modules/<name>`, leaving a `.git` file in the submodule's working directory. Keeping the repository outside the submodule checkout is what lets the superproject switch to a commit where the submodule does not exist without destroying its history. - **`git init --separate-git-dir=<path>`.** The same redirection for a plain repository, used when the repository must live on different storage from the working tree. ## Case 2: environment and command-line overrides `GIT_DIR` names the repository directory and `GIT_WORK_TREE` names the working tree; `--git-dir` and `--work-tree` are the equivalent options and must appear **before** the subcommand, as in `git --git-dir=... --work-tree=... status`. Setting them decouples the two halves completely. The classic use is versioning configuration files in a home directory: keep a bare repository at, say, `/srv/dotfiles.git`, and run commands with the work tree set to `$HOME`. Nothing pollutes the home directory with a `.git` folder, and the repository can be excluded from ordinary scans and backups on its own terms. The related `core.worktree` config records a working tree location inside the repository's own config, which is what a `--separate-git-dir` setup uses. A sharp edge: `GIT_DIR` exported in a shell affects **every** Git command in that shell, including ones run from inside an unrelated repository. Hooks are also invoked with `GIT_DIR` set, which is why a hook that runs Git against another repository must clear or override these variables explicitly rather than assuming discovery will work. ## Finding out where you actually are Do not infer — ask: - `git rev-parse --git-dir` — the repository directory in use. - `git rev-parse --absolute-git-dir` — the same as an absolute path. - `git rev-parse --show-toplevel` — the working tree root. - `git rev-parse --git-common-dir` — the shared directory, which differs from `--git-dir` inside a linked worktree. - `git rev-parse --is-inside-work-tree` and `--is-bare-repository` — booleans for scripts. These are the reliable way for a script or a hook to orient itself, and they answer the confusing cases ("why does this checkout have no `.git` directory?") immediately. ## Why it matters operationally Moving a repository that uses redirection breaks absolute `gitdir:` paths; `git worktree repair` exists to fix worktree links after such a move. Tools that assume `./.git` is a directory — backup scripts, editors, container build contexts — will misbehave on worktrees and submodules. And a `.git` **file** copied without its target is inert: the checkout looks like a repository and is not one.