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

Re: [PATCH] object-name: explain why <ref>~N fails in a shallow clone

From
Junio C Hamano <gitster@pobox.com>
Date
Sep 21, 2026, 16:50 UTC
Message-ID
<xmqq8q4uo8fx.fsf@gitster.g>
In-Reply-To
<pull.2413.git.git.1789898013916.gitgitgadget@gmail.com>
"Harald Nordgren via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 6 quoted lines
> From: Harald Nordgren <haraldnordgren@gmail.com>
>
> Asking for a commit's ancestor with <ref>~N or <ref>^N in a shallow
> clone that does not have N commits of history locally fails with a
> bare "is not a commit" error, with no indication that the repository
> being shallow is the reason, or what to do about it.

I am not sure if bringing up '^N' (the N-th parent of a merge) in an attempt to be more complete helps readers or confuses them. Unlike '<rev>~N', where increasing N raises the required depth of a shallow clone to make the target revision available, both '<rev>^1' and '<rev>^43' of '<rev>' share the same depth. If '<rev>' exists locally and its first parent '<rev>^1' also does, it is likely that '<rev>^2' is also available, as they are at the same depth from '<rev>'.

The title of the commit does not share the problem, which is a good thing ;-).

> Add a hint, shown when the walk runs out of parents exactly at a
> recorded shallow boundary, explaining that history was intentionally
> truncated there. When <ref> looks like <remote>/<branch> and <remote>
> is configured, the suggested command names that remote and branch
Good thinking.

As branch 'B' of remote 'R' is not necessarily stored locally at 'refs/remotes/R/B', implementing the semantics correctly and showing the correct remote name and their branch name by reverse mapping R/B back requires a bit of care, but it should not be impossibly hard.

Show 10 quoted lines
> directly. For <ref>~N it suggests the exact --deepen needed,
> accounting for any history already present instead of just N. For
> <ref>^N the suggestion is always --deepen=1, regardless of N: a
> shallow boundary commit has no parents recorded locally at all, so
> deepening by one generation fetches its complete real parent list in
> one step, whether that commit turns out to have one parent or several.
> The hint only fires when the search stops at an actual shallow
> boundary, not merely because the repository happens to be shallow
> elsewhere, so it does not misfire on a short history that is not
> shallow-truncated.

I think Ben also mentioned this, but <ref> is probably better written as <rev> in the above. A ref(erence) like "master", "origin/next", or "refs/remotes/origin/topic" are all rev(ision)s, and this new advice feature is not limited to requests that are made using references.

    When the revision <rev> is given as a remote-tracking branch,
    the remote and branch are exactly named in the suggested
    command.  For <rev>~N, it suggests ...
> The advice is threaded through GET_OID_QUIETLY so it is not shown
> during the internal re-resolution some commands do while building a
> better error message, which would otherwise print it twice for the
> same failing argument.
Nice.
Show 8 quoted lines
> Signed-off-by: Harald Nordgren <haraldnordgren@gmail.com>
> ---
>     object-name: explain why ~N fails in a shallow clone
>     
>     Asking for a commit's ancestor with <ref>~N in a shallow clone that
>     doesn't have N commits of history locally fails with a "is not a commit"
>     error, with no indication that the repository being shallow is the
>     reason.

It may not be intuitive to new users that in a shallow clone "git log" stops in the middle, instead of going down to the beginning of the history, downloading necessary objects on demand. But fixing it by adding such a feature is totally unrelated and outside the scope of this topic ;-).

Show 12 quoted lines
> diff --git a/Documentation/config/advice.adoc b/Documentation/config/advice.adoc
> index 81f80a9274..5b44037fff 100644
> --- a/Documentation/config/advice.adoc
> +++ b/Documentation/config/advice.adoc
> @@ -128,6 +128,10 @@ all advice messages.
>  		give directions on how to proceed from the current state.
>  	sequencerInUse::
>  		Shown when a sequencer command is already in progress.
> +	shallowHistory::
> +		Shown when `~<n>` or `^<n>` cannot resolve enough ancestors
> +		because history stops at a shallow boundary, to suggest
> +		fetching more history.
It is obvious that users would see such a message when they say
    $ git show HEAD~20
    $ git log HEAD~20..HEAD
but would they see the same when
    $ git log -20 HEAD
    $ git log --since=2.months HEAD

and internally HEAD~20 fails to resolve? Should they see the same hint?

> +	test_must_fail git -C shallow-advice rev-parse origin/main~1 2>err &&
> +	check_shallow_history_advice origin/main "$oid" \
> +		"git fetch --deepen=1 origin main"
This is very straight-forward.
> +		test_must_fail git rev-parse origin/main~5 2>err &&
> +		check_shallow_history_advice origin/main "$oid" \
> +			"git fetch --deepen=3 origin main" &&
Again, very straight-forward.
> +	test_must_fail git -C shallow-advice-caret rev-parse origin/main^1 2>err &&
> +	check_shallow_history_advice origin/main "$oid" \
> +		"git fetch --deepen=1 origin main"
Ditto.
> +		test_must_fail git rev-parse origin/main^2 2>err &&
> +		check_shallow_history_advice origin/main "$oid" \
> +			"git fetch --deepen=1 origin main" &&
Ditto.
> +test_expect_success 'shallowHistory advice not shown for a non-shallow repository' '
> +	test_must_fail git rev-parse HEAD~100000 2>err &&
> +	test_grep ! "^hint:" err
> +'
OK.
Show 10 quoted lines
> +test_expect_success 'shallowHistory advice not shown when resolution succeeds' '
> +	test_commit shallow_ok_1 &&
> +	test_commit shallow_ok_2 &&
> +	test_commit shallow_ok_3 &&
> +	git clone --no-local --depth=3 --branch main --single-branch \
> +		.git shallow-advice-ok &&
> +	test_when_finished "rm -rf shallow-advice-ok" &&
> +	git -C shallow-advice-ok rev-parse origin/main~1 >actual 2>err &&
> +	test_grep ! "^hint:" err
> +'
OK.

I guess the answer to my earlier "does internally failing to resolve due to graft point count?" is "no"?

Thanks.
Previous: D. Ben KnobleNext: Harald Nordgren
Message 3 of 26 in “object-name: explain why <ref>~N fails in a shallow clone”
  1. object-name: explain why <ref>~N fails in a shallow cloneHarald Nordgren via GitGitGadget, Sep 20, 2026
  2. D. Ben KnobleSep 20, 2026
  3. Junio C HamanoSep 21, 2026
  4. Harald NordgrenSep 21, 2026
  5. Junio C HamanoSep 21, 2026
  6. shallow: advise when a walk stops at a shallow boundaryHarald Nordgren via GitGitGadget, Sep 22, 2026
  7. Junio C HamanoSep 22, 2026
  8. object-name: explain why <rev>~N fails in a shallow cloneHarald Nordgren via GitGitGadget, Sep 23, 2026
  9. Junio C HamanoNov 2, 2026
  10. Harald NordgrenNov 2, 2026
  11. Kristoffer HaugsbakkNov 2, 2026
  12. Harald NordgrenNov 2, 2026
  13. Patrick SteinhardtNov 2, 2026
  14. Kristoffer HaugsbakkNov 2, 2026
  15. Harald NordgrenNov 2, 2026
  16. Patrick SteinhardtNov 2, 2026
  17. Harald NordgrenNov 2, 2026
  18. Phillip WoodNov 2, 2026
  19. Harald NordgrenNov 2, 2026
  20. Junio C HamanoNov 2, 2026
  21. Junio C HamanoNov 2, 2026
  22. Kristoffer HaugsbakkNov 2, 2026
  23. Harald NordgrenNov 2, 2026
  24. Patrick SteinhardtNov 2, 2026
  25. Junio C HamanoNov 2, 2026
  26. Junio C HamanoNov 5, 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.