@@ -135,6 +135,17 @@ Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
<CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
<20230323204047.GA9290@coredump.intra.peff.net>,
+* Support for the `core.preferSymlinkRefs` configuration variable
+ will be removed.
++
+ ** The configuration would obviously not work on a filesystem
+ where symbolic links are not supported.
+ ** The contents of such a symbolic link used as a symref does
+ not match end-user intuition unless it is `HEAD`.
++
+The support to treat existing symbolic links under the
+`$GIT_DIR/refs/` directory as symrefs is not going away.
+
== Superseded features that will not be deprecated
Some features have gained newer replacements that aim to improve the design in
@@ -285,11 +285,10 @@ CIFS/Microsoft Windows.
+
False by default.
-core.preferSymlinkRefs::
- Instead of the default "symref" format for HEAD
- and other symbolic reference files, use symbolic links.
- This is sometimes needed to work with old scripts that
- expect HEAD to be a symbolic link.
+core.preferSymlinkRefs (deprecated)::
+ Instead of the default "symref" format for HEAD and other
+ symbolic reference files, use symbolic links. The support
+ for this variable will be dropped in Git 3.0.
core.alternateRefsCommand::
When advertising tips of available history from an alternate, use the shell to
@@ -2025,6 +2025,8 @@ static int create_ref_symlink(struct ref_lock *lock, const char *target)
if (ret)
fprintf(stderr, "no symlink - falling back to symbolic ref\n");
+ else
+ warning("core.preferSymlinkRefs will be removed in Git 3.0");
return ret;
}
#endif
@@ -469,8 +469,8 @@ test_expect_success POSIXPERM 'git reflog expire honors core.sharedRepository' '
'
test_expect_success SYMLINKS 'symref transaction supports symlinks' '
- test_when_finished "git symbolic-ref -d TEST_SYMREF_HEAD" &&
- git update-ref refs/heads/new @ &&
+ test_when_finished "git symbolic-ref -d TEST_SYMREF_HEAD || :" &&
+ git update-ref refs/heads/new HEAD &&
test_config core.prefersymlinkrefs true &&
cat >stdin <<-EOF &&
start
@@ -478,14 +478,15 @@ test_expect_success SYMLINKS 'symref transaction supports symlinks' '
prepare
commit
EOF
- git update-ref --no-deref --stdin <stdin &&
+ git update-ref --no-deref --stdin <stdin 2>stderr &&
test_path_is_symlink .git/TEST_SYMREF_HEAD &&
- test "$(test_readlink .git/TEST_SYMREF_HEAD)" = refs/heads/new
+ test "$(test_readlink .git/TEST_SYMREF_HEAD)" = refs/heads/new &&
+ test_grep "core\.preferSymlinkRefs will be removed" stderr
'
test_expect_success 'symref transaction supports false symlink config' '
- test_when_finished "git symbolic-ref -d TEST_SYMREF_HEAD" &&
- git update-ref refs/heads/new @ &&
+ test_when_finished "git symbolic-ref -d TEST_SYMREF_HEAD || :" &&
+ git update-ref refs/heads/new HEAD &&
test_config core.prefersymlinkrefs false &&
cat >stdin <<-EOF &&
start
@@ -493,11 +494,12 @@ test_expect_success 'symref transaction supports false symlink config' '
prepare
commit
EOF
- git update-ref --no-deref --stdin <stdin &&
+ git update-ref --no-deref --stdin <stdin 2>stderr &&
test_path_is_file .git/TEST_SYMREF_HEAD &&
git symbolic-ref TEST_SYMREF_HEAD >actual &&
echo refs/heads/new >expect &&
- test_cmp expect actual
+ test_cmp expect actual &&
+ test_grep ! "core\.preferSymlinkRefs will be removed" stderr
'
test_done
This step is for immediate consumption. Symbolic links, e.g. .git/HEAD or .git/refs/remotes/origin/HEAD, have been used to represent a symref since very early versions of Git, and they can still be created if the core.preferSymlinkRefs configuration variable tells us to. They however have two downsides: - Obviously, a filesystem that does not support a symbolic link cannot use the feature. For this reason alone, we have long flipped the default to use textual symref, i.e., a regular file with a format that Git recognises. - Except for HEAD and anything at the root level of the refname hierarchy, following a symbolic link that represents the symref would not lead to the referent ref. For example, in order to express that we consider 'main' branch to be the primary among our tracking branches for the 'origin' remote, we would have a symbolic ref .git/refs/remotes/origin/HEAD but the result of calling readlink(2) on the symbolic link is not 'main', nor "$(pwd)/.git/refs/remotes/origin/main". It is relative to the $GIT_DIR, i.e., "refs/remotes/origin/master". This is highly counter-intuitive. Let's decide and declare to remove the support to create such symbolic links at the Git 3.0 version boundary, and in preparation for the move, start warning when somebody _creates_ a symbolic link to represent a new symref. If a third-party tool still expects that HEAD is nothing but a symbolic link, either its authors have got end-user complaints since we made the textual symrefs the default in mid 2006, or nobody is using such a tool so breaking them does not matter. It would not be a problem in practice if Git would never create a symbolic link to represent a symbolic ref. We do not plan to deprecate (or remove) the support to use existing symbolic links at this point, though. As to the implementation: - We give a warning only where the configuration set to true is actually affecting the behaviour of Git, since the behaviour the user is getting today will change with the planned removal. A configuration set to true will not cause a warning, unless you create a symref (e.g., by switching a branch). - The clean-up procedure of the existing tests did not account for the fact that "git symbolic -d REF" on an non-existing REF to fail, which was corrected, together with use of @ where HEAD is more descriptive and perfectly understandable. Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/BreakingChanges.txt | 11 +++++++++++ Documentation/config/core.txt | 9 ++++----- refs/files-backend.c | 2 ++ t/t0600-reffiles-backend.sh | 18 ++++++++++-------- 4 files changed, 27 insertions(+), 13 deletions(-)