[PATCH v3 0/5] Improve error reporting to mention how a Git repository is discovered
- From
Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
- Date
- Oct 28, 2026, 11:53 UTC
- Message-ID
- <20261028115412.169748-1-kaartic.sivaraam@gmail.com>
- In-Reply-To
- <20260924120502.2642141-1-kaartic.sivaraam@gmail.com>
At the moment, when Git gives up with "fatal: not a git repository", it does not say which directory it actually inspected or where that directory came from. This is especially confusing when a leftover environment variable is steering Git somewhere the user did not expect.
In v2 I tried to address this by explaining why the inspected directory was not a valid repository (missing HEAD, HEAD outside refs/, and so on). Junio pointed out that this is less useful than saying which directory was used as the repository and where that came from, since once the user knows that they can go look at the directory themselves. He also pointed out that v2 was uneven, as it named $GIT_OBJECT_DIRECTORY but did not say where the git directory itself came from.
So this iteration takes that direction instead. The validity checks in is_git_directory() and validate_headref() are left untouched, and we only add information at the points where we are about to die.
With this series:
- An explicitly given git directory says where it came from:
$ cd /srv/git
$ export GIT_DIR=project.git
...
$ cd ~/src/myproject # later, same terminal
$ git status
fatal: not a git repository: 'project.git'
this path was taken from $GIT_DIR (which can also be set with --git-dir or --bare)--git-dir and --bare both just set GIT_DIR, so by the time setup runs we cannot tell them apart. I went with a single wording that is true for all three rather than plumbing that information through. Happy to revisit if it is felt to be worth it.
- The discovery walk says where it started, where it stopped and what GIT_CEILING_DIRECTORIES is set to:
$ echo 'export GIT_CEILING_DIRECTORIES=$HOME' >> ~/.bashrc
...weeks later...
$ cd ~/.config/nvim
$ git status
fatal: not a git repository (or any of the parent directories): .git
searched from '/home/user/.config/nvim' up to '/home/user/.config'
$GIT_CEILING_DIRECTORIES is set to '/home/user'- An unusable $GIT_OBJECT_DIRECTORY, which was the original motivation for this series, is reported wherever we die for want of a repository (explicit git directory, ceiling and mount point):
$ GIT_OBJECT_DIRECTORY=/does/not/exist git --git-dir repo.git rev-parse --is-bare-repository
fatal: not a git repository: 'repo.git'
this path was taken from $GIT_DIR (which can also be set with --git-dir or --bare)
cannot access object directory '/does/not/exist' set via $GIT_OBJECT_DIRECTORY: No such file or directoryCommands that are fine running outside a repository stay silent and do not build these messages at all.
This series does not handle the following, which I think are better done separately:
- The gitfile case (for instance from inside a submodule or a worktree). A gitfile pointing at an invalid repository dies earlier in read_gitfile() with its own message.
- GIT_ALTERNATE_OBJECT_DIRECTORIES. It never leads to "not a git repository". Its diagnostics are misleading in their own way (one of them points at .git/objects/info/alternates even when the entry came from the environment), but they come from the object database rather than from setup.
- The "$GIT_CEILING_DIRECTORIES is set to" line is printed whenever the variable is set, even if none of its entries is above the current directory and the walk went all the way to '/'. The "searched from ... up to '/'" line makes that visible, and getting it exact would mean passing more state out of the discovery walk.
CI:
They seem to pass.
- GitLab: https://gitlab.com/gitlab-org/git/-/merge_requests/672
- GitHub: https://github.com/sivaraam/git/actions/runs/40676055975
Changes since v2:
- Dropped is_git_directory_verbose() and the HEAD-related reasons, as per Junio's review. is_git_directory() and validate_headref() are now unchanged. - New: say where an explicitly given git directory came from. - New: say where the discovery walk started and stopped, and what GIT_CEILING_DIRECTORIES is set to. - Reworked the GIT_OBJECT_DIRECTORY reporting to ask once at the point of failure, and extended it to the discovery walk (ceiling and mount point). - Dropped the test for HEAD being a symlink outside refs/, as the series no longer cares about it. This test was failing on Windows in v2. - Reworked the t0009 tests to check the new messages, including that a command which does not need a repository stays silent. - Kept each message as a single translatable string and added TRANSLATORS comments describing the placeholders.
Range-diff versus v2: (This may not be very helpful because I threw out 3/4 and 4/4 from v2 and have 3 new patches in place of them.)
1: 0b062456eb = 1: b37136baa4 setup: normalize an if-else to follow our convention
2: 7e8dab0078 ! 2: 08f3584c3a t0009: add tests to cover more error reporting scenarios
@@ Metadata
Author: Kaartic Sivaraam <kaartic.sivaraam@gmail.com> ## Commit message ##
- t0009: add tests to cover more error reporting scenarios
+ t0009: add tests to cover more repository setup scenarios - Introduce few more tests to t0009 to cover error reporting scenarios
- when --git-dir is used.
+ Introduce a few more tests to t0009 to cover repository setup
+ scenarios. We introduce these as we intend to do some change
+ in upcoming commits which would benefit from this additional
+ test coverage.Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
@@ t/t0009-git-dir-validation.sh: test_expect_success 'setup: .git as an empty dire
)
' -+test_expect_success 'setup: custom git directory with missing HEAD is rejected' '
++test_expect_success 'setup: --git-dir pointing to an invalid directory is rejected' '
+ test_when_finished "rm -rf parent/empty-dir" &&
+ mkdir -p parent/empty-dir &&
+ test_must_fail git --git-dir parent/empty-dir rev-parse --is-bare-repository 2>stderr &&
+ test_grep "not a git repository" stderr
+'
+
-+test_expect_success 'setup: custom git directory with HEAD as a symlink outside refs/ is rejected' '
-+ test_when_finished "rm -rf parent/head-as-link-to-garbage" &&
-+ mkdir -p parent/head-as-link-to-garbage &&
++test_expect_success 'setup: discovery fails when GIT_DIR points to an invalid directory' '
++ test_must_fail env GIT_DIR="/path/to/does-not-exist" \
++ git rev-parse --is-bare-repository 2>stderr &&
++ test_grep "not a git repository" stderr
++'
++
++test_expect_success 'setup: command that does not need a repository stays silent for invalid GIT_DIR' '
++ echo x | GIT_DIR="/path/to/does-not-exist" git hash-object --stdin 2>stderr &&
++ test_must_be_empty stderr
++'
++
++test_expect_success 'setup: discovery fails when a valid git directory not found within GIT_CEILING_DIRECTORIES' '
++ test_when_finished "rm -rf parent/no-valid-git-directory-within-ceiling" &&
++ mkdir -p parent/no-valid-git-directory-within-ceiling/ceil/sub &&
+ (
-+ cd parent/head-as-link-to-garbage &&
-+ git init --bare real-repo &&
-+ touch garbage &&
-+ rm real-repo/HEAD &&
-+ ln -s ../garbage real-repo/HEAD &&
-+ test_must_fail git --git-dir real-repo rev-parse --is-bare-repository 2>stderr &&
-+ test_grep "not a git repository" stderr
++ cd parent/no-valid-git-directory-within-ceiling/ceil/sub &&
++ test_must_fail env GIT_CEILING_DIRECTORIES="$(pwd)/../../" \
++ git rev-parse --is-bare-repository 2>stderr &&
++ test_grep "not a git repository (or any of the parent directories)" stderr
+ )
+'
+
-+test_expect_success 'setup: custom git directory with invalid GIT_OBJECT_DIRECTORY configuration is rejected' '
++test_expect_success 'setup: discovery fails with unusable $GIT_OBJECT_DIRECTORY and explicit gitdir' '
+ test_when_finished "rm -rf parent/invalid-git-object-directory-config" &&
+ mkdir -p parent/invalid-git-object-directory-config &&
+ (
+ cd parent/invalid-git-object-directory-config &&
+ git init --bare real-repo &&
-+ test_must_fail env GIT_OBJECT_DIRECTORY="$(pwd)/does-not-exist" \
++ test_must_fail env GIT_OBJECT_DIRECTORY="/path/to/does-not-exist" \
+ git --git-dir real-repo rev-parse --is-bare-repository 2>stderr &&
+ test_grep "not a git repository" stderr
+ )
+'
-+
+
test_done
3: 312b861c6c < -: ---------- setup: introduce new helper 'is_git_directory_verbose'
4: 29191f463e < -: ---------- setup: communicate why a directory is not a valid git directory
-: ---------- > 3: 34a110da6d setup: provide hint about the source of the explicit git directory
-: ---------- > 4: 9986739fec setup: provide hint about auto-discovery boundaries
-: ---------- > 5: 7d13445134 setup: report when GIT_OBJECT_DIRECTORY is what we could not useKaartic Sivaraam (5): setup: normalize an if-else to follow our convention t0009: add tests to cover more repository discovery scenarios setup: provide hint about the source of the explicit git directory setup: provide hint about auto-discovery boundaries setup: report when GIT_OBJECT_DIRECTORY is what we could not use
setup.c | 104 ++++++++++++++++++++++++++++++---- t/t0009-git-dir-validation.sh | 77 +++++++++++++++++++++++++ 2 files changed, 171 insertions(+), 10 deletions(-)
-- 2.55.0.1003.g10538fe699