git/advice.h, branch jch

initial branch: give hints after switching the default name

2025-09-18T18:44:47Z

It is likely that those who came to Git after 3.0 switched the default initial branch name to 'main' would still try to follow tutorials that were written before 3.0 happened and with the assumption that the tool would call the initial branch 'master'. To help these new users after 3.0 boundary, let's retain one part of the hint we will be giving before the default changes, namely, how to rename the branch an unconfigured Git has created just once. We do this without telling them how to permanently configure the default name of the initial branch, and that design choice is very much deliberate. The whole point of switching the default name was because we did not want to force individual users to configure their default branch name but while the hard wired default was 'master', they _had_ to configure it away from 'master' in order to conform to the recent norm, and a hint that tells them how to do so is useful. But once the default is renamed to 'main', that no longer is true. A narrower audience who are new users that follow an instruction that assumes the initial branch name is 'master' would only need to learn "here is how to change the branch name to match the tutorial you are following in the repository you created for practice", and "here is how you keep creating repositories with the first branch with a name everybody hates" is unnecessary. It also needs to be noted that the advise token to squelch the message is the same advice.defaultBranchName as before, which is also very much deliberate. The users who do have that configured are those who _have_ been using Git since before 3.0, and they are not the target audience for the new advice message. Reusing the same advise token ensures that they do not have to turn the message off. Helped-by: Phillip Wood Signed-off-by: Junio C Hamano

breaking-changes: switch default branch to main

2025-09-10T20:34:58Z

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 Signed-off-by: Junio C Hamano

advice: allow disabling default branch name advice

2025-03-25T23:09:28Z

The default branch name advice message is displayed when `repo_default_branch_name()` is invoked and the `init.defaultBranch` config is not set. In this scenario, the advice message is always shown even if the `--no-advice` option is used. Adapt `repo_default_branch_name()` to allow the default branch name advice message to be disabled with the `--no-advice` option and corresponding configuration. Signed-off-by: Justin Tobler Acked-by: Phillip Wood Signed-off-by: Junio C Hamano

advice.h: .txt -> .adoc fixes

2025-03-03T21:49:21Z

Signed-off-by: Todd Zullinger Signed-off-by: Junio C Hamano

fetch set_head: move warn advice into advise_if_enabled

2024-12-05T17:59:16Z

Advice about what to do when getting a warning is typed out explicitly twice and is printed as regular output. The output is also tested for. Extract the advice message into a single place and use a wrapper function, so if later the advice is made more chatty the signature only needs to be changed in once place. Remove the testing for the advice output in the tests. Signed-off-by: Bence Ferdinandy Signed-off-by: Junio C Hamano

Merge branch 'ds/advice-sparse-index-expansion'

2024-07-16T18:18:56Z

A new warning message is issued when a command has to expand a sparse index to handle working tree cruft that are outside of the sparse checkout. * ds/advice-sparse-index-expansion: advice: warn when sparse index expands

advice: warn when sparse index expands

2024-07-08T19:23:59Z

Typically, forcing a sparse index to expand to a full index means that Git could not determine the status of a file outside of the sparse-checkout and needed to expand sparse trees into the full list of sparse blobs. This operation can be very slow when the sparse-checkout is much smaller than the full tree at HEAD. When users are in this state, there is usually a modified or untracked file outside of the sparse-checkout mentioned by the output of 'git status'. There are a number of reasons why this is insufficient: 1. Users may not have a full understanding of which files are inside or outside of their sparse-checkout. This is more common in monorepos that manage the sparse-checkout using custom tools that map build dependencies into sparse-checkout definitions. 2. In some cases, an empty directory could exist outside the sparse-checkout and these empty directories are not reported by 'git status' and friends. 3. If the user has '.gitignore' or 'exclude' files, then 'git status' will squelch the warnings and not demonstrate any problems. In order to help users who are in this state, add a new advice message to indicate that a sparse index is expanded to a full index. This message should be written at most once per process, so add a static global 'give_advice_on_expansion' to sparse-index.c. Further, there is a case in 'git sparse-checkout set' that uses the sparse index as an in-memory data structure (even when writing a full index) so we need to disable the message in that kind of case. The t1092-sparse-checkout-compatibility.sh test script compares the behavior of several Git commands across full and sparse repositories, including sparse repositories with and without a sparse index. We need to disable the advice in the sparse-index repo to avoid differences in stderr. By leaving the advice on in the sparse-checkout repo (without the sparse index), we can test the behavior of disabling the advice in convert_to_sparse(). (Indeed, these tests are how that necessity was discovered.) Add a test that reenables the advice and demonstrates that the message is output. The advice message is defined outside of expand_index() to avoid super- wide lines. It is also defined as a macro to avoid compile issues with -Werror=format-security. Signed-off-by: Derrick Stolee Signed-off-by: Junio C Hamano

rebase -i: improve error message when picking merge

2024-05-30T17:02:58Z

The only todo commands that accept a merge commit are "merge" and "reset". All the other commands like "pick" or "reword" fail when they try to pick a a merge commit and print the message error: commit abc123 is a merge but no -m option was given. followed by a hint about the command being rescheduled. This message is designed to help the user when they cherry-pick a merge and forget to pass "-m". For users who are rebasing the message is confusing as there is no way for rebase to cherry-pick the merge. Improve the user experience by detecting the error and printing some advice on how to fix it when the todo list is parsed rather than waiting for the "pick" command to fail. The advice recommends "merge" rather than "exec git cherry-pick -m ..." on the assumption that cherry-picking merges is relatively rare and it is more likely that the user chose "pick" by a mistake. It would be possible to support cherry-picking merges by allowing the user to pass "-m" to "pick" commands but that adds complexity to do something that can already be achieved with exec git cherry-pick -m1 abc123 Reported-by: Stefan Haller Signed-off-by: Phillip Wood Signed-off-by: Junio C Hamano

sequencer: allow disabling conflict advice

2024-03-18T16:28:40Z

Allow disabling the advice shown when a squencer operation results in a merge conflict through a new config 'advice.mergeConflict', which is named generically such that it can be used by other commands eventually. Remove that final '\n' in the first hunk in sequencer.c to avoid an otherwise empty 'hint: ' line before the line 'hint: Disable this message with "git config advice.mergeConflict false"' which is automatically added by 'advise_if_enabled'. Note that we use 'advise_if_enabled' for each message in the second hunk in sequencer.c, instead of using 'if (show_hints && advice_enabled(...)', because the former instructs the user how to disable the advice, which is more user-friendly. Update the tests accordingly. Note that the body of the second test in t3507-cherry-pick-conflict.sh is enclosed in double quotes, so we must escape them in the added line. Note that t5520-pull.sh, which checks that we display the advice for 'git rebase' (via 'git pull --rebase') does not have to be updated because it only greps for a specific line in the advice message. Signed-off-by: Philippe Blain Signed-off-by: Junio C Hamano

Merge branch 'kh/branch-ref-syntax-advice'

2024-03-15T23:05:59Z

When git refuses to create a branch because the proposed branch name is not a valid refname, an advice message is given to refer the user to exact naming rules. * kh/branch-ref-syntax-advice: branch: advise about ref syntax rules advice: use double quotes for regular quoting advice: use backticks for verbatim advice: make all entries stylistically consistent t3200: improve test style