[PATCH 0/4] deprecating core.preferSymlinkRefs

[PATCH 0/4] deprecating core.preferSymlinkRefs

[Junio C Hamano]

Removal of support for core.preferSymlinkRefs at Git 3.0 boundary,
so that we only write textual symrefs for things like HEAD and
refs/remotes/origin/HEAD, and still understand symbolic links used
as symrefs in existing repositories, is a serious proposal this
patch series makes.

But at the same time, this is an RFC.  I wrote it to serve as a
candidate for BCP, a guide to those who want to add an entry to the
breaking changes document.  I think anything that is described in
the breaking changes document has to become a patch series that
spans multi-year effort, and that must be done with care.

 - The proposal phase.  A breaking change is outlined, transition
   plan is given, and the first step of the transition (often,
   starting to give a warning and offering an alternative to the
   feature planned to be removed are involved) is presented.  The
   aim is that after N years, the user base will be aware of the
   upcoming removal and would already be prepared to be able to work
   with Git 3.0 that lacks the removed feature.

   In this series, [Patch 1/4] does this.

 - The Git 3.0 phase.  A breaking change is actually implemented.
   It optionally can offer help to those who procrastinated until
   the last-minute to break them, but the feature itself is gone.

   In this series, [PATCH 2/4] and [Patch 3/4] do this.

 - Clean-up phase.  If the previous phase added an additional
   transition help, after M years, such a help meant for transition
   would be removed.

   In this series, [PATCH 4/4] does this.

What I want people to think about is how to ensure quality of the
Git 3.0 phase.  We can iterate and polish the proposal phase with as
much time as we want to spend, just like any new feature.  But Git
3.0 phase is with a solid deadline, and before that time, we cannot
remove the feature for real.  Would we cook such steps in 'next'
forever until the actual Git 3.0?  To those users who are running
'next' based Git, it would mean that some of the changes the
breaking changes document listed would come a lot earlier to them.
On the other hand, unless we somehow have a way to expose willing
volunteers an early access to these "big changes", there is no way
for them to be as stable and tested.  We should not plan to scramble
and be able to perfect these changes between Git v3.0-rc0 and Git
v3.0 final.

Or perhaps use the "experimental.*" configuration stored in the
user's ~/.gitconfig to let users opt into Git 3.0 features (one of
which may be that textual symrefs are always used regardless of the
core.preferSymlinkRefs setting)?  That way, we can merge these big
changes early without worrying about accidentally affecting the
end-user population.

Junio C Hamano (4):
  refs: deprecate core.preferSymlinkRefs
  refs: mostly remove core.preferSymlinkRefs
  refs: remove NO_SYMLINK_HEAD
  refs: remove the last remnants of core.preferSymlinkRefs

 Documentation/BreakingChanges.txt   | 11 ++++++++
 Documentation/config/core.txt       |  6 -----
 Makefile                            |  6 -----
 config.c                            |  5 ----
 config.mak.uname                    |  3 ---
 configure.ac                        |  3 ---
 contrib/buildsystems/CMakeLists.txt |  2 +-
 environment.c                       |  1 -
 environment.h                       |  1 -
 refs/files-backend.c                | 26 -------------------
 t/t0600-reffiles-backend.sh         | 39 ++++++++++++++++-------------
 11 files changed, 34 insertions(+), 69 deletions(-)

-- 
2.46.1-742-g4240f61078

[PATCH 1/4] refs: deprecate core.preferSymlinkRefs

[Junio C Hamano]

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(-)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 2b64665694..57c002dd0d 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -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
diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index 60ca9f2b68..f0245f5050 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -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
diff --git a/refs/files-backend.c b/refs/files-backend.c
index c7f3f4e591..c40a248b9f 100644
--- a/refs/files-backend.c
+++ b/refs/files-backend.c
@@ -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
diff --git a/t/t0600-reffiles-backend.sh b/t/t0600-reffiles-backend.sh
index 20df336cc3..d369330562 100755
--- a/t/t0600-reffiles-backend.sh
+++ b/t/t0600-reffiles-backend.sh
@@ -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
-- 
2.46.1-742-g4240f61078

Re: [PATCH 1/4] refs: deprecate core.preferSymlinkRefs

[Patrick Steinhardt]

On Wed, Sep 18, 2024 at 04:28:22PM -0700, Junio C Hamano wrote:
> diff --git a/refs/files-backend.c b/refs/files-backend.c
> index c7f3f4e591..c40a248b9f 100644
> --- a/refs/files-backend.c
> +++ b/refs/files-backend.c
> @@ -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

This string should probably be marked for translation, right?

Patrick

[PATCH 2/4] refs: mostly remove core.preferSymlinkRefs

[Junio C Hamano]

This step and the next step are for Git 3.0.

Now we are preparing for a big Git 3.0 transition after warning
against use of this configuration variable to create a new symlink
that represents a symbolic ref for N months, it is time to actually
remove the support of the configuration variable.

In this patch, we mostly ignore core.preferSymlinkRefs and always
create a textual symref when we are asked to create a symref, but
when core.preferSymlinkRefs would have caused us to use a symbolic
link in an older version of Git, we will issue a warning.  We also
have in our build infrastructure to selectively set the CPP macro
NO_SYMLINK_HEAD, but an accompanying patch will remove them.

The final warning is meant to help users who set the configuration
variable and expected it to create a symlink, but instead got a
textual symref.  They may not even recognise the configuration after
they set it long time ago and forgot about it by now, so we keep the
"git config --help" entry for the variable to help them recall what
it was about.

After a few releases, we will get rid of this warning and the
codebase will look as if such a configuration variable never
existed, but we are not quite there yet.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/config/core.txt |  4 ++--
 refs/files-backend.c          | 29 +++---------------------
 t/t0600-reffiles-backend.sh   | 42 +++++++++++++++++++++++------------
 3 files changed, 33 insertions(+), 42 deletions(-)

diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index f0245f5050..a6f67cab27 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -285,10 +285,10 @@ CIFS/Microsoft Windows.
 +
 False by default.
 
-core.preferSymlinkRefs (deprecated)::
+core.preferSymlinkRefs (removed)::
 	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.
+	for this variable was dropped in Git 3.0.
 
 core.alternateRefsCommand::
 	When advertising tips of available history from an alternate, use the shell to
diff --git a/refs/files-backend.c b/refs/files-backend.c
index c40a248b9f..1296272252 100644
--- a/refs/files-backend.c
+++ b/refs/files-backend.c
@@ -2011,26 +2011,6 @@ static int commit_ref_update(struct files_ref_store *refs,
 	return 0;
 }
 
-#ifdef NO_SYMLINK_HEAD
-#define create_ref_symlink(a, b) (-1)
-#else
-static int create_ref_symlink(struct ref_lock *lock, const char *target)
-{
-	int ret = -1;
-
-	char *ref_path = get_locked_file_path(&lock->lk);
-	unlink(ref_path);
-	ret = symlink(target, ref_path);
-	free(ref_path);
-
-	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
-
 static int create_symref_lock(struct ref_lock *lock, const char *target,
 			      struct strbuf *err)
 {
@@ -3003,13 +2983,10 @@ static int files_transaction_finish(struct ref_store *ref_store,
 			}
 		}
 
-		/*
-		 * We try creating a symlink, if that succeeds we continue to the
-		 * next update. If not, we try and create a regular symref.
-		 */
+		/* Warn against core.preferSymlinkRefs set to true */
 		if (update->new_target && prefer_symlink_refs)
-			if (!create_ref_symlink(lock, update->new_target))
-				continue;
+			/* we used to, but no longer, create a symlink here */
+			warning("core.preferSymlinkRefs was removed in Git 3.0");
 
 		if (update->flags & REF_NEEDS_COMMIT) {
 			clear_loose_ref_cache(refs);
diff --git a/t/t0600-reffiles-backend.sh b/t/t0600-reffiles-backend.sh
index d369330562..4e517cdc13 100755
--- a/t/t0600-reffiles-backend.sh
+++ b/t/t0600-reffiles-backend.sh
@@ -468,26 +468,40 @@ test_expect_success POSIXPERM 'git reflog expire honors core.sharedRepository' '
 	esac
 '
 
-test_expect_success SYMLINKS 'symref transaction supports symlinks' '
+test_expect_success SYMLINKS 'symlinks used as symrefs are still supported' '
 	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
-	symref-create TEST_SYMREF_HEAD refs/heads/new
-	prepare
-	commit
-	EOF
-	git update-ref --no-deref --stdin <stdin 2>stderr &&
+	# manually do this, as core.prefersymlinkrefs no longer
+	# affects how a symref is created (as a textual symref).
+	ln -f -s refs/heads/new .git/TEST_SYMREF_HEAD &&
 	test_path_is_symlink .git/TEST_SYMREF_HEAD &&
-	test "$(test_readlink .git/TEST_SYMREF_HEAD)" = refs/heads/new &&
-	test_grep "core\.preferSymlinkRefs will be removed" stderr
+	echo refs/heads/new >expect &&
+	git symbolic-ref TEST_SYMREF_HEAD >actual &&
+	test_cmp actual expect
+'
+
+test_expect_success 'core.prefersymlinkrefs gets a warning' '
+	test_when_finished "git symbolic-ref -d TEST_SYMREF_HEAD || :" &&
+	git update-ref refs/heads/new HEAD &&
+
+	test_config core.prefersymlinkrefs true &&
+	git symbolic-ref TEST_SYMREF_HEAD refs/heads/new 2>stderr &&
+	test_grep "core\.preferSymlinkRefs was removed" stderr &&
+
+	git symbolic-ref -d TEST_SYMREF_HEAD &&
+	git config core.prefersymlinkrefs false &&
+	git symbolic-ref TEST_SYMREF_HEAD refs/heads/new 2>stderr &&
+	test_grep ! "core\.preferSymlinkRefs was removed" stderr &&
+
+	git symbolic-ref -d TEST_SYMREF_HEAD &&
+	git config --unset core.prefersymlinkrefs &&
+	git symbolic-ref TEST_SYMREF_HEAD refs/heads/new 2>stderr &&
+	test_grep ! "core\.preferSymlinkRefs was removed" stderr
 '
 
-test_expect_success 'symref transaction supports false symlink config' '
+test_expect_success 'symref transaction' '
 	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
 	symref-create TEST_SYMREF_HEAD refs/heads/new
@@ -499,7 +513,7 @@ test_expect_success 'symref transaction supports false symlink config' '
 	git symbolic-ref TEST_SYMREF_HEAD >actual &&
 	echo refs/heads/new >expect &&
 	test_cmp expect actual &&
-	test_grep ! "core\.preferSymlinkRefs will be removed" stderr
+	test_grep ! "core\.preferSymlinkRefs was removed" stderr
 '
 
 test_done
-- 
2.46.1-742-g4240f61078

Re: [PATCH 2/4] refs: mostly remove core.preferSymlinkRefs

[Jeff King]

On Wed, Sep 18, 2024 at 04:28:23PM -0700, Junio C Hamano wrote:

> diff --git a/t/t0600-reffiles-backend.sh b/t/t0600-reffiles-backend.sh
> index d369330562..4e517cdc13 100755
> --- a/t/t0600-reffiles-backend.sh
> +++ b/t/t0600-reffiles-backend.sh
> [...]
> @@ -468,26 +468,40 @@ test_expect_success POSIXPERM 'git reflog expire honors core.sharedRepository' '
>  	esac
>  '
>  
> -test_expect_success SYMLINKS 'symref transaction supports symlinks' '
> +test_expect_success SYMLINKS 'symlinks used as symrefs are still supported' '
>  	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
> -	symref-create TEST_SYMREF_HEAD refs/heads/new
> -	prepare
> -	commit
> -	EOF
> -	git update-ref --no-deref --stdin <stdin 2>stderr &&
> +	# manually do this, as core.prefersymlinkrefs no longer
> +	# affects how a symref is created (as a textual symref).
> +	ln -f -s refs/heads/new .git/TEST_SYMREF_HEAD &&

There are two other tests that probably should get the same treatment.
In the patch below I've just deleted them, but I think since they are
really about the reading side, they'd probably want a similar manual
setup.

diff --git a/t/t7201-co.sh b/t/t7201-co.sh
index 2d984eb4c6..72eb5f62e7 100755
--- a/t/t7201-co.sh
+++ b/t/t7201-co.sh
@@ -407,18 +407,6 @@ test_expect_success 'checkout w/--track from tag fails' '
 	test "z$(git rev-parse main^0)" = "z$(git rev-parse HEAD)"
 '
 
-test_expect_success 'detach a symbolic link HEAD' '
-	git checkout main &&
-	git config --bool core.prefersymlinkrefs yes &&
-	git checkout side &&
-	git checkout main &&
-	it=$(git symbolic-ref HEAD) &&
-	test "z$it" = zrefs/heads/main &&
-	here=$(git rev-parse --verify refs/heads/main) &&
-	git checkout side^ &&
-	test "z$(git rev-parse --verify refs/heads/main)" = "z$here"
-'
-
 test_expect_success 'checkout with --track fakes a sensible -b <name>' '
 	git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" &&
 	git update-ref refs/remotes/origin/koala/bear renamer &&
diff --git a/t/t9903-bash-prompt.sh b/t/t9903-bash-prompt.sh
index 95e9955bca..b4d7206bea 100755
--- a/t/t9903-bash-prompt.sh
+++ b/t/t9903-bash-prompt.sh
@@ -50,15 +50,6 @@ test_expect_success 'prompt - branch name' '
 	test_cmp expected "$actual"
 '
 
-test_expect_success SYMLINKS 'prompt - branch name - symlink symref' '
-	printf " (main)" >expected &&
-	test_when_finished "git checkout main" &&
-	test_config core.preferSymlinkRefs true &&
-	git checkout main &&
-	__git_ps1 >"$actual" &&
-	test_cmp expected "$actual"
-'
-
 test_expect_success 'prompt - unborn branch' '
 	printf " (unborn)" >expected &&
 	git checkout --orphan unborn &&


I noticed these because I had a similar proposal long ago, which never
got merged (I don't think because anybody particularly disagreed, but it
fell through the cracks and never got picked up again):

  https://lore.kernel.org/git/20151230065343.GA26964@sigill.intra.peff.net/

What you have here is (modulo the two hunks above) more complete than
what I have, so I don't think there's anything else to try to salvage
from it. A little bit of the history in the linked commit message is
interesting as to how we ended up here, but ultimately not really that
important.

-Peff

Re: [PATCH 2/4] refs: mostly remove core.preferSymlinkRefs

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I noticed these because I had a similar proposal long ago, which never
> got merged (I don't think because anybody particularly disagreed, but it
> fell through the cracks and never got picked up again):
>
>   https://lore.kernel.org/git/20151230065343.GA26964@sigill.intra.peff.net/
>
> What you have here is (modulo the two hunks above) more complete than
> what I have, so I don't think there's anything else to try to salvage
> from it. A little bit of the history in the linked commit message is
> interesting as to how we ended up here, but ultimately not really that
> important.

It was useful to find out another reason (which I failed to mention
in this series) why symbolic links will be misleading: when it points
at a ref that is in packed-refs.

Thanks.

[PATCH 3/4] refs: remove NO_SYMLINK_HEAD

[Junio C Hamano]

This step is for Git 3.0.

Remove the build-time setting NO_SYMLINK_HEAD that is used to
override the end-user supplied core.preferSymlinkRefs and force
use of textual symrefs, as core.preferSymlinkRefs is now gone
and we use textual symrefs only.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Makefile                            | 6 ------
 config.mak.uname                    | 3 ---
 configure.ac                        | 3 ---
 contrib/buildsystems/CMakeLists.txt | 2 +-
 4 files changed, 1 insertion(+), 13 deletions(-)

diff --git a/Makefile b/Makefile
index 275a5ee3c9..029a468702 100644
--- a/Makefile
+++ b/Makefile
@@ -81,9 +81,6 @@ include shared.mak
 #
 # Define NO_SYS_SELECT_H if you don't have sys/select.h.
 #
-# Define NO_SYMLINK_HEAD if you never want .git/HEAD to be a symbolic link.
-# Enable it on Windows.  By default, symrefs are still used.
-#
 # Define NO_SVN_TESTS if you want to skip time-consuming SVN interoperability
 # tests.  These tests take up a significant amount of the total test time
 # but are not needed unless you plan to talk to SVN repos.
@@ -1767,9 +1764,6 @@ ifdef OPEN_RETURNS_EINTR
 	COMPAT_CFLAGS += -DOPEN_RETURNS_EINTR
 	COMPAT_OBJS += compat/open.o
 endif
-ifdef NO_SYMLINK_HEAD
-	BASIC_CFLAGS += -DNO_SYMLINK_HEAD
-endif
 ifdef NO_GETTEXT
 	BASIC_CFLAGS += -DNO_GETTEXT
 	USE_GETTEXT_SCHEME ?= fallthrough
diff --git a/config.mak.uname b/config.mak.uname
index d5112168a4..a38b152312 100644
--- a/config.mak.uname
+++ b/config.mak.uname
@@ -238,7 +238,6 @@ ifeq ($(uname_O),Cygwin)
 		NO_D_TYPE_IN_DIRENT = YesPlease
 		NO_STRCASESTR = YesPlease
 		NO_MEMMEM = YesPlease
-		NO_SYMLINK_HEAD = YesPlease
 		NO_IPV6 = YesPlease
 		OLD_ICONV = UnfortunatelyYes
 		# There are conflicting reports about this.
@@ -446,7 +445,6 @@ ifeq ($(uname_S),Windows)
 	NEEDS_CRYPTO_WITH_SSL = YesPlease
 	NO_LIBGEN_H = YesPlease
 	NO_POLL = YesPlease
-	NO_SYMLINK_HEAD = YesPlease
 	NO_IPV6 = YesPlease
 	NO_SETENV = YesPlease
 	NO_STRCASESTR = YesPlease
@@ -661,7 +659,6 @@ ifeq ($(uname_S),MINGW)
 	NEEDS_CRYPTO_WITH_SSL = YesPlease
 	NO_LIBGEN_H = YesPlease
 	NO_POLL = YesPlease
-	NO_SYMLINK_HEAD = YesPlease
 	NO_SETENV = YesPlease
 	NO_STRCASESTR = YesPlease
 	NO_STRLCPY = YesPlease
diff --git a/configure.ac b/configure.ac
index d1a96da14e..307349f323 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1195,9 +1195,6 @@ AC_COMPILE_IFELSE([BSD_SYSCTL_SRC],
 GIT_CONF_SUBST([HAVE_BSD_SYSCTL])
 
 ## Other checks.
-# Define NO_SYMLINK_HEAD if you never want .git/HEAD to be a symbolic link.
-# Enable it on Windows.  By default, symrefs are still used.
-#
 # Define NO_PTHREADS if we do not have pthreads.
 #
 # Define PTHREAD_LIBS to the linker flag used for Pthread support.
diff --git a/contrib/buildsystems/CMakeLists.txt b/contrib/buildsystems/CMakeLists.txt
index 832f46b316..d6bce22d34 100644
--- a/contrib/buildsystems/CMakeLists.txt
+++ b/contrib/buildsystems/CMakeLists.txt
@@ -267,7 +267,7 @@ if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
 	endif()
 	include_directories(${CMAKE_SOURCE_DIR}/compat/win32)
 	add_compile_definitions(HAVE_ALLOCA_H NO_POSIX_GOODIES NATIVE_CRLF NO_UNIX_SOCKETS WIN32
-				_CONSOLE DETECT_MSYS_TTY STRIP_EXTENSION=".exe"  NO_SYMLINK_HEAD UNRELIABLE_FSTAT
+				_CONSOLE DETECT_MSYS_TTY STRIP_EXTENSION=".exe" UNRELIABLE_FSTAT
 				NOGDI OBJECT_CREATION_MODE=1 __USE_MINGW_ANSI_STDIO=0
 				USE_NED_ALLOCATOR OVERRIDE_STRDUP MMAP_PREVENTS_DELETE USE_WIN32_MMAP
 				HAVE_WPGMPTR ENSURE_MSYSTEM_IS_SET HAVE_RTLGENRANDOM)
-- 
2.46.1-742-g4240f61078

[PATCH 4/4] refs: remove the last remnants of core.preferSymlinkRefs

[Junio C Hamano]

This step is for some time after Git 3.0.

Now it is almost N years since we removed the support for the
variable at Git 3.0 boundary, it is time to remove the warning about
this ancient variable and the behaviour change we went through with
it.

This concludes the journey to make sure we no longer create a
symbolic link to represent a symref, while still recognising
existing ones.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/config/core.txt |  5 -----
 config.c                      |  5 -----
 environment.c                 |  1 -
 environment.h                 |  1 -
 refs/files-backend.c          |  5 -----
 t/t0600-reffiles-backend.sh   | 15 ++-------------
 6 files changed, 2 insertions(+), 30 deletions(-)

diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index a6f67cab27..1887da78e3 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -285,11 +285,6 @@ CIFS/Microsoft Windows.
 +
 False by default.
 
-core.preferSymlinkRefs (removed)::
-	Instead of the default "symref" format for HEAD and other
-	symbolic reference files, use symbolic links.  The support
-	for this variable was dropped in Git 3.0.
-
 core.alternateRefsCommand::
 	When advertising tips of available history from an alternate, use the shell to
 	execute the specified command instead of linkgit:git-for-each-ref[1]. The
diff --git a/config.c b/config.c
index 56b5862e59..8693cd510d 100644
--- a/config.c
+++ b/config.c
@@ -1445,11 +1445,6 @@ static int git_default_core_config(const char *var, const char *value,
 		return 0;
 	}
 
-	if (!strcmp(var, "core.prefersymlinkrefs")) {
-		prefer_symlink_refs = git_config_bool(var, value);
-		return 0;
-	}
-
 	if (!strcmp(var, "core.logallrefupdates")) {
 		if (value && !strcasecmp(value, "always"))
 			log_all_ref_updates = LOG_REFS_ALWAYS;
diff --git a/environment.c b/environment.c
index 1d6c48b52d..2c3a60149b 100644
--- a/environment.c
+++ b/environment.c
@@ -40,7 +40,6 @@ int has_symlinks = 1;
 int minimum_abbrev = 4, default_abbrev = -1;
 int ignore_case;
 int assume_unchanged;
-int prefer_symlink_refs;
 int is_bare_repository_cfg = -1; /* unspecified */
 int warn_ambiguous_refs = 1;
 int warn_on_object_refname_ambiguity = 1;
diff --git a/environment.h b/environment.h
index 0148738ed6..6b595bd210 100644
--- a/environment.h
+++ b/environment.h
@@ -127,7 +127,6 @@ extern int has_symlinks;
 extern int minimum_abbrev, default_abbrev;
 extern int ignore_case;
 extern int assume_unchanged;
-extern int prefer_symlink_refs;
 extern int warn_ambiguous_refs;
 extern int warn_on_object_refname_ambiguity;
 extern char *apply_default_whitespace;
diff --git a/refs/files-backend.c b/refs/files-backend.c
index 1296272252..eef01fee06 100644
--- a/refs/files-backend.c
+++ b/refs/files-backend.c
@@ -2983,11 +2983,6 @@ static int files_transaction_finish(struct ref_store *ref_store,
 			}
 		}
 
-		/* Warn against core.preferSymlinkRefs set to true */
-		if (update->new_target && prefer_symlink_refs)
-			/* we used to, but no longer, create a symlink here */
-			warning("core.preferSymlinkRefs was removed in Git 3.0");
-
 		if (update->flags & REF_NEEDS_COMMIT) {
 			clear_loose_ref_cache(refs);
 			if (commit_ref(lock)) {
diff --git a/t/t0600-reffiles-backend.sh b/t/t0600-reffiles-backend.sh
index 4e517cdc13..4db86757ac 100755
--- a/t/t0600-reffiles-backend.sh
+++ b/t/t0600-reffiles-backend.sh
@@ -480,22 +480,12 @@ test_expect_success SYMLINKS 'symlinks used as symrefs are still supported' '
 	test_cmp actual expect
 '
 
-test_expect_success 'core.prefersymlinkrefs gets a warning' '
+test_expect_success 'core.prefersymlinkrefs no longer gets a warning' '
 	test_when_finished "git symbolic-ref -d TEST_SYMREF_HEAD || :" &&
 	git update-ref refs/heads/new HEAD &&
 
 	test_config core.prefersymlinkrefs true &&
 	git symbolic-ref TEST_SYMREF_HEAD refs/heads/new 2>stderr &&
-	test_grep "core\.preferSymlinkRefs was removed" stderr &&
-
-	git symbolic-ref -d TEST_SYMREF_HEAD &&
-	git config core.prefersymlinkrefs false &&
-	git symbolic-ref TEST_SYMREF_HEAD refs/heads/new 2>stderr &&
-	test_grep ! "core\.preferSymlinkRefs was removed" stderr &&
-
-	git symbolic-ref -d TEST_SYMREF_HEAD &&
-	git config --unset core.prefersymlinkrefs &&
-	git symbolic-ref TEST_SYMREF_HEAD refs/heads/new 2>stderr &&
 	test_grep ! "core\.preferSymlinkRefs was removed" stderr
 '
 
@@ -512,8 +502,7 @@ test_expect_success 'symref transaction' '
 	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_grep ! "core\.preferSymlinkRefs was removed" stderr
+	test_cmp expect actual
 '
 
 test_done
-- 
2.46.1-742-g4240f61078

Re: [PATCH 0/4] deprecating core.preferSymlinkRefs

[Derrick Stolee]

On 9/18/24 7:28 PM, Junio C Hamano wrote:
> Removal of support for core.preferSymlinkRefs at Git 3.0 boundary,
> so that we only write textual symrefs for things like HEAD and
> refs/remotes/origin/HEAD, and still understand symbolic links used
> as symrefs in existing repositories, is a serious proposal this
> patch series makes.

I missed a lot of this discussion about 3.0, but I'm fascinated by
the prospect.

> What I want people to think about is how to ensure quality of the
> Git 3.0 phase.  We can iterate and polish the proposal phase with as
> much time as we want to spend, just like any new feature.  But Git
> 3.0 phase is with a solid deadline, and before that time, we cannot
> remove the feature for real.  Would we cook such steps in 'next'
> forever until the actual Git 3.0?  To those users who are running
> 'next' based Git, it would mean that some of the changes the
> breaking changes document listed would come a lot earlier to them.
> On the other hand, unless we somehow have a way to expose willing
> volunteers an early access to these "big changes", there is no way
> for them to be as stable and tested.  We should not plan to scramble
> and be able to perfect these changes between Git v3.0-rc0 and Git
> v3.0 final.
> 
> Or perhaps use the "experimental.*" configuration stored in the
> user's ~/.gitconfig to let users opt into Git 3.0 features (one of
> which may be that textual symrefs are always used regardless of the
> core.preferSymlinkRefs setting)?  That way, we can merge these big
> changes early without worrying about accidentally affecting the
> end-user population.
I do like the idea of having someone set 'feature.git3=true' in
their global config and having that mean that they are ready to
accept the Git 3.0 breaking changes as they are available in
a Git 2.x release. As much early testing as we can get would be
beneficial.

This would be a way to get your patches 2 & 3 into 'master' and
released, but I'm not sure exactly how to keep patch 4 queued
for a potential future release. The best I could think of is to
have a long-running 'master-v3' branch that takes these cleanup
patches and then merges ongoing 'master' changes into them. It
would be a gross history to manage, but it could potentially
work. It does lead to concerns as to how to communicate that a
change to 'master' has broken the 'master-v3' CI or how an
incoming change could create conflicts with 'master-v3'.

Sorry I don't have full solutions for you. Only more problems.

Thanks,
-Stolee

Re: [PATCH 0/4] deprecating core.preferSymlinkRefs

[Junio C Hamano]

Derrick Stolee <stolee@gmail.com> writes:

> I do like the idea of having someone set 'feature.git3=true' in
> their global config and having that mean that they are ready to
> accept the Git 3.0 breaking changes as they are available in
> a Git 2.x release. As much early testing as we can get would be
> beneficial.
>
> This would be a way to get your patches 2 & 3 into 'master' and
> released, but I'm not sure exactly how to keep patch 4 queued
> for a potential future release.

I actually am not worried about that one, i.e., "Clean-up phase",
even less than I would worry about the "Proposal phase".  Cleaning
up after the dust settles can be done at a leisurely pace after the
big version bump.

I think the feature.git3 opt-in knob would be a nice approach.
Thanks.

Re: [PATCH 0/4] deprecating core.preferSymlinkRefs

[Patrick Steinhardt]

On Wed, Sep 18, 2024 at 04:28:21PM -0700, Junio C Hamano wrote:
> Removal of support for core.preferSymlinkRefs at Git 3.0 boundary,
> so that we only write textual symrefs for things like HEAD and
> refs/remotes/origin/HEAD, and still understand symbolic links used
> as symrefs in existing repositories, is a serious proposal this
> patch series makes.

I probably don't have have to say that I fully support dropping support
for the writing side of this :) I was also recently reminded that we
still have ".git/branches", which I'd very much like to drop support for
with Git 3.0, too. I'll send a separate patch series for that soonish.

> But at the same time, this is an RFC.  I wrote it to serve as a
> candidate for BCP, a guide to those who want to add an entry to the
> breaking changes document.  I think anything that is described in
> the breaking changes document has to become a patch series that
> spans multi-year effort, and that must be done with care.
> 
>  - The proposal phase.  A breaking change is outlined, transition
>    plan is given, and the first step of the transition (often,
>    starting to give a warning and offering an alternative to the
>    feature planned to be removed are involved) is presented.  The
>    aim is that after N years, the user base will be aware of the
>    upcoming removal and would already be prepared to be able to work
>    with Git 3.0 that lacks the removed feature.
> 
>    In this series, [Patch 1/4] does this.
> 
>  - The Git 3.0 phase.  A breaking change is actually implemented.
>    It optionally can offer help to those who procrastinated until
>    the last-minute to break them, but the feature itself is gone.
> 
>    In this series, [PATCH 2/4] and [Patch 3/4] do this.
> 
>  - Clean-up phase.  If the previous phase added an additional
>    transition help, after M years, such a help meant for transition
>    would be removed.
> 
>    In this series, [PATCH 4/4] does this.
> 
> What I want people to think about is how to ensure quality of the
> Git 3.0 phase.  We can iterate and polish the proposal phase with as
> much time as we want to spend, just like any new feature.  But Git
> 3.0 phase is with a solid deadline, and before that time, we cannot
> remove the feature for real.  Would we cook such steps in 'next'
> forever until the actual Git 3.0?  To those users who are running
> 'next' based Git, it would mean that some of the changes the
> breaking changes document listed would come a lot earlier to them.
> On the other hand, unless we somehow have a way to expose willing
> volunteers an early access to these "big changes", there is no way
> for them to be as stable and tested.  We should not plan to scramble
> and be able to perfect these changes between Git v3.0-rc0 and Git
> v3.0 final.
> 
> Or perhaps use the "experimental.*" configuration stored in the
> user's ~/.gitconfig to let users opt into Git 3.0 features (one of
> which may be that textual symrefs are always used regardless of the
> core.preferSymlinkRefs setting)?  That way, we can merge these big
> changes early without worrying about accidentally affecting the
> end-user population.

I guess you've split this out into a separate discussion by now at [1],
right? I've already commented on that series, so I'm not going to repeat
what I've said here :)

Patrick

[1]: <xmqq7cb77810.fsf@gitster.g>

Re: [PATCH 0/4] deprecating core.preferSymlinkRefs

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> I guess you've split this out into a separate discussion by now at [1],
> right? I've already commented on that series, so I'm not going to repeat
> what I've said here :)
>
> Patrick
>
> [1]: <xmqq7cb77810.fsf@gitster.g>

Yes, it seems that we are converging on that thread that we cannot
afford to do the runtime switching thing, so when I have time to
reroll this topic, I'll see how it actually works.

Thanks.