@matheusbsbs / matheus-bagliano / commits / 67d9b39cc7

breaking-changes: switch default branch to main

Since 1296cbe4b46 (init: document `init.defaultBranch` better, 2020-12-11) "git-init.adoc" has advertised that the default name of the initial branch may change in the future. The name "main" is chosen to match the default used by the big Git forge web sites. The advice printed when init.defaultBranch is not set is updated to say that the default will change to "main" in Git 3.0. Building with WITH_BREAKING_CHANGES enabled removes the advice and changes the default branch name to "main". The code in guess_remote_head() that looks for "refs/heads/master" is left unchanged as that is only called when the remote server does not support the symref capability in the v0 protocol or the symref extension to the ls-refs list in the v2 protocol. Such an old server is more likely to be using "master" as the default branch name. With the exception of the "git-init.adoc" the documentation is left unchanged. I had hoped to parameterize the name of the default branch by using an asciidoc attribute. Unfortunately attribute expansion is inhibited by backticks and we use backticks to mark up ref names so that idea does not work. As the changes to git-init.adoc show inserting ifdef's around each instance of the branch name "master" is cumbersome and makes the documentation sources harder to read. Apart from "git-init.adoc" there are some other files where "master" is used as the name of the initial branch rather than as an example of a branch name such as "user-manual.adoc" and "gitcore-tutorial.adoc". The name appears a lot in those so updating it with ifdef's is not really practical. We can update that document in the 3.0 release cycle. The other documentation where master is used as an example branch name can be gradually converted over time. Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Phillip Wood committed Sep 10, 2025 at 16:29 UTC 67d9b39cc711468c381f070e241211895fe97136

8 files changed +54 -13

Documentation/BreakingChanges.adoc

@@ -165,6 +165,12 @@ A prerequisite for this change is that the ecosystem is ready to support the

165 "reftable" format. Most importantly, alternative implementations of Git like

166 JGit, libgit2 and Gitoxide need to support it.

167

168 +* In new repositories, the default branch name will be `main`. We have been

169 + warning that the default name will change since 675704c74dd (init:

170 + provide useful advice about init.defaultBranch, 2020-12-11). The new name

171 + matches the default branch name used in new repositories by many of the

172 + big Git forges.

173 +

174 === Removals

175

176 * Support for grafting commits has long been superseded by git-replace(1).

Documentation/git-init.adoc

+9 -3

@@ -77,9 +77,15 @@ If this is a reinitialization, the repository will be moved to the specified pat

77 `-b <branch-name>`::

78 `--initial-branch=<branch-name>`::

79 Use _<branch-name>_ for the initial branch in the newly created

80 -repository. If not specified, fall back to the default name (currently

81 -`master`, but this is subject to change in the future; the name can be

82 -customized via the `init.defaultBranch` configuration variable).

80 +repository. If not specified, fall back to the default name

81 +ifndef::with-breaking-changes[]

82 +(currently `master`, but this will change to `main` when Git 3.0 is released).

83 +endif::with-breaking-changes[]

84 +ifdef::with-breaking-changes[]

85 +`main`.

86 +endif::with-breaking-changes[]

87 +The default name can be customized via the `init.defaultBranch` configuration

88 +variable.

advice.c

@@ -51,7 +51,9 @@ static struct {

51 [ADVICE_AM_WORK_DIR] = { "amWorkDir" },

52 [ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME] = { "checkoutAmbiguousRemoteBranchName" },

53 [ADVICE_COMMIT_BEFORE_MERGE] = { "commitBeforeMerge" },

54 +#ifndef WITH_BREAKING_CHANGES

55 [ADVICE_DEFAULT_BRANCH_NAME] = { "defaultBranchName" },

56 +#endif /* WITH_BREAKING_CHANGES */

57 [ADVICE_DETACHED_HEAD] = { "detachedHead" },

58 [ADVICE_DIVERGING] = { "diverging" },

59 [ADVICE_FETCH_SET_HEAD_WARN] = { "fetchRemoteHEADWarn" },

advice.h

@@ -18,7 +18,9 @@ enum advice_type {

18 ADVICE_AM_WORK_DIR,

19 ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,

20 ADVICE_COMMIT_BEFORE_MERGE,

21 +#ifndef WITH_BREAKING_CHANGES

22 ADVICE_DEFAULT_BRANCH_NAME,

23 +#endif /* WITH_BREAKING_CHANGES */

24 ADVICE_DETACHED_HEAD,

25 ADVICE_DIVERGING,

26 ADVICE_FETCH_SET_HEAD_WARN,

ci/run-build-and-tests.sh

-1

@@ -9,7 +9,6 @@ run_tests=t

10 case "$jobname" in

11 linux-breaking-changes)

12 - export GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME=main

12 export WITH_BREAKING_CHANGES=YesPlease

13 ;;

14 linux-TEST-vars)

refs.c

+11 -4

@@ -627,10 +627,12 @@ void expand_ref_prefix(struct strvec *prefixes, const char *prefix)

627 strvec_pushf(prefixes, *p, len, prefix);

628 }

629

630 +#ifndef WITH_BREAKING_CHANGES

631 static const char default_branch_name_advice[] = N_(

632 "Using '%s' as the name for the initial branch. This default branch name\n"

632 -"is subject to change. To configure the initial branch name to use in all\n"

633 -"of your new repositories, which will suppress this warning, call:\n"

633 +"will change to \"main\" in Git 3.0. To configure the initial branch name\n"

634 +"to use in all of your new repositories, which will suppress this warning,\n"

635 +"call:\n"

636 "\n"

637 "\tgit config --global init.defaultBranch <name>\n"

638 "\n"

@@ -639,8 +641,9 @@ static const char default_branch_name_advice[] = N_(

641 "\n"

642 "\tgit branch -m <name>\n"

643 );

644 +#endif /* WITH_BREAKING_CHANGES */

645

643 -char *repo_default_branch_name(struct repository *r, int quiet)

646 +char *repo_default_branch_name(struct repository *r, MAYBE_UNUSED int quiet)

647 {

648 const char *config_key = "init.defaultbranch";

649 const char *config_display_key = "init.defaultBranch";

@@ -649,14 +652,18 @@ char *repo_default_branch_name(struct repository *r, int quiet)

652

653 if (env && *env)

654 ret = xstrdup(env);

652 - else if (repo_config_get_string(r, config_key, &ret) < 0)

655 + if (!ret && repo_config_get_string(r, config_key, &ret) < 0)

656 die(_("could not retrieve `%s`"), config_display_key);

657

658 if (!ret) {

659 +#ifdef WITH_BREAKING_CHANGES

660 + ret = xstrdup("main");

661 +#else

662 ret = xstrdup("master");

663 if (!quiet)

664 advise_if_enabled(ADVICE_DEFAULT_BRANCH_NAME,

665 _(default_branch_name_advice), ret);

666 +#endif /* WITH_BREAKING_CHANGES */

667 }

668

669 full_ref = xstrfmt("refs/heads/%s", ret);

t/t0001-init.sh

+17 -1

@@ -868,7 +868,7 @@ test_expect_success 'overridden default initial branch name (config)' '

868 grep nmb actual

869 '

870

871 -test_expect_success 'advice on unconfigured init.defaultBranch' '

871 +test_expect_success !WITH_BREAKING_CHANGES 'advice on unconfigured init.defaultBranch' '

872 GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME= git -c color.advice=always \

873 init unconfigured-default-branch-name 2>err &&

874 test_decode_color <err >decoded &&

@@ -883,6 +883,22 @@ test_expect_success 'advice on unconfigured init.defaultBranch disabled' '

883 test_grep ! "hint: " err

884 '

885

886 +test_expect_success 'default branch name' '

887 + if test_have_prereq WITH_BREAKING_CHANGES

888 + then

889 + expect=main

890 + else

891 + expect=master

892 + fi &&

893 + echo "refs/heads/$expect" >expect &&

894 + (

895 + sane_unset GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME &&

896 + git init default-initial-branch-name

897 + ) &&

898 + git -C default-initial-branch-name symbolic-ref HEAD >actual &&

899 + test_cmp expect actual

900 +'

901 +

902 test_expect_success 'overridden default main branch name (env)' '

903 test_config_global init.defaultBranch nmb &&

904 GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME=env git init main-branch-env &&

t/test-lib.sh

+7 -4

@@ -127,10 +127,13 @@ then

127 export GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS

128 fi

129

130 -# Explicitly set the default branch name for testing, to avoid the

131 -# transitory "git init" warning under --verbose.

132 -: ${GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME:=master}

133 -export GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME

130 +if test -z "$WITH_BREAKING_CHANGES"

131 +then

132 + # Explicitly set the default branch name for testing, to avoid the

133 + # transitory "git init" warning under --verbose.

134 + : ${GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME:=master}

135 + export GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME

136 +fi

137

138 ################################################################

139 # It appears that people try to run tests without building...