git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[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 directory

Commands 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 use
Kaartic 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
Previous: Kaartic SivaraamNext: Kaartic Sivaraam
Message 22 of 30 in “Improve error reporting to mention "why" a directory is not a repository”
  1. 0/3 Improve error reporting to mention "why" a directory is not a repositoryKaartic Sivaraam, Sep 24, 2026
  2. 1/3 t0009: add tests to cover more error reporting scenariosKaartic Sivaraam, Sep 24, 2026
  3. Junio C HamanoSep 24, 2026
  4. Kaartic SivaraamSep 25, 2026
  5. 2/3 setup: introduce new helper 'is_git_directory_verbose'Kaartic Sivaraam, Sep 24, 2026
  6. Junio C HamanoSep 24, 2026
  7. Kaartic SivaraamSep 25, 2026
  8. 3/3 setup: communicate why a directory is not a valid git directoryKaartic Sivaraam, Sep 24, 2026
  9. Junio C HamanoSep 24, 2026
  10. Kaartic SivaraamSep 25, 2026
  11. 0/4 Improve error reporting to mention "why" a directory is not a repositoryKaartic Sivaraam, Sep 29, 2026
  12. 1/4 setup: normalize an if-else to follow our conventionKaartic Sivaraam, Sep 29, 2026
  13. 2/4 t0009: add tests to cover more error reporting scenariosKaartic Sivaraam, Sep 29, 2026
  14. 3/4 setup: introduce new helper 'is_git_directory_verbose'Kaartic Sivaraam, Sep 29, 2026
  15. Patrick SteinhardtSep 30, 2026
  16. Kaartic SivaraamOct 5, 2026
  17. Junio C HamanoSep 30, 2026
  18. Kaartic SivaraamOct 28, 2026
  19. 4/4 setup: communicate why a directory is not a valid git directoryKaartic Sivaraam, Sep 29, 2026
  20. Patrick SteinhardtSep 30, 2026
  21. Kaartic SivaraamOct 5, 2026
  22. 0/5 Improve error reporting to mention how a Git repository is discoveredKaartic Sivaraam, Oct 28, 2026
  23. 1/5 setup: normalize an if-else to follow our conventionKaartic Sivaraam, Oct 28, 2026
  24. 2/5 t0009: add tests to cover more repository discovery scenariosKaartic Sivaraam, Oct 28, 2026
  25. 3/5 setup: provide hint about the source of the explicit git directoryKaartic Sivaraam, Oct 28, 2026
  26. 4/5 setup: provide hint about auto-discovery boundariesKaartic Sivaraam, Oct 28, 2026
  27. Junio C HamanoOct 28, 2026
  28. 5/5 setup: report when GIT_OBJECT_DIRECTORY is what we could not useKaartic Sivaraam, Oct 28, 2026
  29. Junio C HamanoOct 28, 2026
  30. Junio C HamanoOct 28, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.