libfetchers/git: restore compat with `builtins.fetchGit` from 2.3

Since fb38459d6e58508245553380cccc03c0dbaa1542, each `ref` is appended
with `refs/heads` unless it starts with `refs/` already. This regressed
two use-cases that worked fine before:

* Specifying a commit hash as `ref`: now, if `ref` looks like a commit
  hash it will be directly passed to `git fetch`.

* Specifying a tag without `refs/tags` as prefix: now, the fetcher prepends
  `refs/*` to a ref that doesn't start with `refs/` and doesn't look
  like a commit hash. That way, both a branch and a tag specified in
  `ref` can be fetched.

  The order of preference in git is

  * file in `refs/` (e.g. `HEAD`)
  * file in `refs/tags/`
  * file in `refs/heads` (i.e. a branch)

  After fetching `refs/*`, ref is resolved the same way as git does.

Change-Id: Idd49b97cbdc8c6fdc8faa5a48bef3dec25e4ccc3

1 files changed, 23 insertions, 0 deletions

diff --git a/doc/manual/rl-next/fetchGit-regression.md b/doc/manual/rl-next/fetchGit-regression.md
new file mode 100644
index 000000000..f6b4fb9e5
--- /dev/null
+++ b/doc/manual/rl-next/fetchGit-regression.md
@@ -0,0 +1,23 @@
+---
+synopsis: restore backwards-compatibility of `builtins.fetchGit` with Nix 2.3
+issues: [5291, 5128]
+credits: [ma27]
+category: Fixes
+---
+
+Compatibility with `builtins.fetchGit` from Nix 2.3 has been restored as follows:
+
+* Until now, each `ref` was prefixed with `refs/heads` unless it starts with `refs/` itself.
+
+  Now, this is not done if the `ref` looks like a commit hash.
+
+* Specifying `builtins.fetchGit { ref = "a-tag"; /* … */ }` was broken because `refs/heads` was appended.
+
+  Now, the fetcher doesn't turn a ref into `refs/heads/ref`, but into `refs/*/ref`. That way,
+  the value in `ref` can be either a tag or a branch.
+
+* The ref resolution happens the same way as in git:
+
+  * If `refs/ref` exists, it's used.
+  * If a tag `refs/tags/ref` exists, it's used.
+  * If a branch `refs/heads/ref` exists, it's used.