Patrick SteinhardtThe "files" backend has the ability to store symbolic refs as symbolic links, which can be configured via "core.preferSymlinkRefs". This feature stems back from the early days: the initial implementation of symbolic refs used symlinks exclusively. The symref format was only introduced in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a textfile., 2005-09-25) and made the default in 9f0bb90d16 (core.prefersymlinkrefs: use symlinks for .git/HEAD, 2006-05-02).
This is all about 20 years ago, and there are no known reasons nowadays why one would want to use symlinks instead of symrefs. Mark the feature for deprecation in Git 3.0.
Note that this only deprecates _writing_ symrefs as symbolic links. Reading such symrefs is still supported for now.
Signed-off-by: Patrick Steinhardt <ps@pks.im> --- Hi,
as discussed in [1], this small patch deprecates "core.preferSymlinkRefs". Thanks!
Patrick
[1]: <xmqqzf9zddia.fsf@gitster.g> --- Documentation/BreakingChanges.adoc | 18 ++++++++++++++++++ Documentation/config/core.adoc | 3 +++ refs/files-backend.c | 18 ++++++++++++++++-- t/t0600-reffiles-backend.sh | 26 +++++++++++++++++++++++--- 4 files changed, 60 insertions(+), 5 deletions(-)
Show changes to 4 files +60 −5
Documentation/BreakingChanges.adoc, Documentation/config/core.adoc, refs/files-backend.c, t/t0600-reffiles-backend.sh
diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc index 90b53abcea2..8178d06417b 100644 --- a/Documentation/BreakingChanges.adoc +++ b/Documentation/BreakingChanges.adoc @@ -295,6 +295,24 @@ The command will be removed. + cf. <xmqqa59i45wc.fsf@gitster.g> +* Support for `core.preferSymlinkRefs=true` has been deprecated and will be + removed in Git 3.0. If set, symbolic refs like "HEAD" would be written as + symbolic links instead of as a plain file using the symref format. ++ +Symbolic references were initially always stored as a symbolic link. This was +changed in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a +textfile., 2005-09-25), where a new symref format was introduced to store those +symbolic refs in a plain file. In 9f0bb90d16 (core.prefersymlinkrefs: use +symlinks for .git/HEAD, 2006-05-02), the Git project switched the default to use +the symref format in favor of symbolic links. ++ +The migration away from symbolic links has happened almost 20 years ago by now, +and there is no known reason why one should prefer them nowadays. Furthermore, +symbolic links are not supported on some platforms. ++ +Note that for now, only the writing side for such symbolic links is deprecated. +Reading such symbolic links is still supported for now. + == 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.adoc b/Documentation/config/core.adoc index 08739bb9d42..e9272bbc0bd 100644 --- a/Documentation/config/core.adoc +++ b/Documentation/config/core.adoc @@ -290,6 +290,9 @@ core.preferSymlinkRefs:: 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. ++ +This configuration is deprecated and will be removed in Git 3.0. Writing +symbolic links for symrefs will not be supported anymore. 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 3e46386531d..b14e0af219e 100644 --- a/refs/files-backend.c +++ b/refs/files-backend.c @@ -2114,14 +2114,28 @@ static int commit_ref_update(struct files_ref_store *refs, return 0; } -#ifdef NO_SYMLINK_HEAD +#if defined(NO_SYMLINK_HEAD) || defined(WITH_BREAKING_CHANGES) #define create_ref_symlink(a, b) (-1) #else static int create_ref_symlink(struct ref_lock *lock, const char *target) { + static int warn_once = 1; + char *ref_path; int ret = -1; - char *ref_path = get_locked_file_path(&lock->lk); + if (warn_once) + warning(_("'core.preferSymlinkRefs=true' is nominated for removal.\n" + "hint: The use of symbolic links for symbolic refs is deprecated\n" + "hint: and will be removed in Git 3.0. The configuration that\n" + "hint: tells Git to use them is thus going away. You can unset\n" + "hint: it with:\n" + "hint:\n" + "hint:\tgit config unset core.preferSymlinkRefs\n" + "hint:\n" + "hint: Git will then use the symref format instead.")); + warn_once = 0; + + ref_path = get_locked_file_path(&lock->lk); unlink(ref_path); ret = symlink(target, ref_path); free(ref_path); diff --git a/t/t0600-reffiles-backend.sh b/t/t0600-reffiles-backend.sh index 1e62c791d97..560cdfe1d66 100755 --- a/t/t0600-reffiles-backend.sh +++ b/t/t0600-reffiles-backend.sh @@ -477,9 +477,29 @@ test_expect_success SYMLINKS 'symref transaction supports symlinks' ' prepare commit EOF - git update-ref --no-deref --stdin <stdin && - test_path_is_symlink .git/TEST_SYMREF_HEAD && - test "$(test_readlink .git/TEST_SYMREF_HEAD)" = refs/heads/new + git update-ref --no-deref --stdin <stdin 2>err && + if test_have_prereq WITH_BREAKING_CHANGES + then + test_path_is_file .git/TEST_SYMREF_HEAD && + echo "ref: refs/heads/new" >expect && + test_cmp expect .git/TEST_SYMREF_HEAD && + test_must_be_empty err + else + test_path_is_symlink .git/TEST_SYMREF_HEAD && + test "$(test_readlink .git/TEST_SYMREF_HEAD)" = refs/heads/new && + cat >expect <<-EOF && + warning: ${SQ}core.preferSymlinkRefs=true${SQ} is nominated for removal. + hint: The use of symbolic links for symbolic refs is deprecated + hint: and will be removed in Git 3.0. The configuration that + hint: tells Git to use them is thus going away. You can unset + hint: it with: + hint: + hint: git config unset core.preferSymlinkRefs + hint: + hint: Git will then use the symref format instead. + EOF + test_cmp expect err + fi ' test_expect_success 'symref transaction supports false symlink config' ' --- base-commit: 5f9d2e334da76ac55790ce4d4ea971a31bcd57fd change-id: 20251014-pks-ref-files-deprecate-symbolic-links-584597a558b5
