doc: apply new format to git-branch man page
cover doc: apply new format to git-branch man page
Working on git-branch's doc uncovered a bug in the completion logic that did not take into account the new formatting of options. Apart from that, the changes are quite standard now.
Jean-Noël Avila (2):
completion: take into account the formatting backticks for options
doc: apply new format to git-branch man page
Documentation/config/branch.adoc | 105 +++++------ Documentation/git-branch.adoc | 287 +++++++++++++++---------------- generate-configlist.sh | 4 +- 3 files changed, 198 insertions(+), 198 deletions(-)
base-commit: 683c54c999c301c2cd6f715c411407c413b1d84e
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1880%2Fjnavila%2Fdoc_git_branch-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1880/jnavila/doc_git_branch-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1880
Signature · 1 line
gitgitgadget
PATCH 1/2 completion: take into account the formatting backticks for options
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
With the modern formatting of the manpages, the options and commands are now backticked in their definition lists. This patch updates the generation of the completion list to take into account this new format.
--- generate-configlist.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
generate-configlist.sh +2 -2
@@ -13,8 +13,8 @@ print_config_list () { cat <<EOF static const char *config_name_list[] = { EOF - grep -h '^[a-zA-Z].*\..*::$' "$SOURCE_DIR"/Documentation/*config.adoc "$SOURCE_DIR"/Documentation/config/*.adoc | - sed '/deprecated/d; s/::$//; s/, */\n/g' | + grep -h '^`\?[a-zA-Z].*\..*`\?::$' "$SOURCE_DIR"/Documentation/*config.adoc "$SOURCE_DIR"/Documentation/config/*.adoc | + sed '/deprecated/d; s/::$//; s/`//g; s/, */\n/g' | sort | sed 's/^.*$/ "&",/' cat <<EOF
Signature · 1 line
gitgitgadget
Re: [PATCH 1/2] completion: take into account the formatting backticks for options
Quoted 16 lines · Jean-Noël Avila via GitGitGadget
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
With the modern formatting of the manpages, the options and commands are now backticked in their definition lists. This patch updates the generation of the completion list to take into account this new format.
Signed-off-by Jean-Noël Avila <[email protected]>--- generate-configlist.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)generate-configlist.sh +0
-0
generate-configlist.sh print_config_list () { · line 16
Quoted 6 lines
generate-configlist.sh +1
-2@@ -13,8 +13,8 @@ print_config_list () { cat <<EOF static const char *config_name_list[] = { EOF - grep -h '^[a-zA-Z].*\..*::$' "$SOURCE_DIR"/Documentation/*config.adoc "$SOURCE_DIR"/Documentation/config/*.adoc | - sed '/deprecated/d; s/::$//; s/, */\n/g' | + grep -h '^`\?[a-zA-Z].*\..*`\?::$' "$SOURCE_DIR"/Documentation/*config.adoc "$SOURCE_DIR"/Documentation/config/*.adoc |
Using \? in BRE as a short-hand for \{0,1\} (or trying to use any single regexp magic in BRE by adding a backslash when that magic is only available in ERE) is a GNUism, isn't it?
We probably should rewrite the thing as ERE, perhaps like
grep -E -h '^`?[a-zA-Z].*\..*`?::$' ...
Also, if we can avoid piping grep into sed or awk, we should do so, when it does not lose readability. Perhaps we can do something like
sed -E -n -e '/... that pattern .../{
/deprecated/d;
s/::$//;
...
}' "$SOURCE_DIR"/Documentation/*config.adoc ... |
sort |
...in this case?
Quoted 4 lines
generate-configlist.sh +1
-0+ sed '/deprecated/d; s/::$//; s/`//g; s/, */\n/g' | sort | sed 's/^.*$/ "&",/' cat <<EOF
Re: [PATCH 1/2] completion: take into account the formatting backticks for options
Quoted 4 lines · On Monday, 17 March 2025 21:52:13 CET Junio C Hamano wrote:
Quoted 3 lines · Jean-Noël Avila via GitGitGadget
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
With the modern formatting of the manpages, the options and commands are
now
Quoted 15 lines
Quoted 15 lines
backticked in their definition lists. This patch updates the generation of the completion list to take into account this new format.
Signed-off-by Jean-Noël Avila <[email protected]>---
generate-configlist.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)generate-configlist.sh +0
-0@@ -13,8 +13,8 @@ print_config_list () {
Quoted 6 lines
generate-configlist.sh print_config_list () {
Quoted 6 lines
generate-configlist.sh +0
-1cat <<EOF static const char *config_name_list[] = { EOF - grep -h '^[a-zA-Z].*\..*::$' "$SOURCE_DIR"/Documentation/
*config.adoc
Quoted 24 lines
Quoted 5 lines
generate-configlist.sh +0
-0"$SOURCE_DIR"/Documentation/config/*.adoc | - sed '/deprecated/d; s/::$//;s/, */\n/g' |
generate-configlist.sh +1
-0+ grep -h '^`\?[a-zA-Z].*\..*`\?::$'"$SOURCE_DIR"/Documentation/*config.adoc
"$SOURCE_DIR"/Documentation/config/*.adoc |Using \? in BRE as a short-hand for \{0,1\} (or trying to use any single regexp magic in BRE by adding a backslash when that magic is only available in ERE) is a GNUism, isn't it?
We probably should rewrite the thing as ERE, perhaps like
grep -E -h '^`?[a-zA-Z].*\..*`?::$' ...Also, if we can avoid piping grep into sed or awk, we should do so, when it does not lose readability. Perhaps we can do something like
sed -E -n -e '/... that pattern .../{ /deprecated/d; s/::$//; ... }' "$SOURCE_DIR"/Documentation/*config.adoc ... | sort | ...
Quoted 1 line
in this case?
For the GNUism, the tests on MacOS and Windows by gitgitgadget passed. But I get your point and will reroll.
Re: [PATCH 1/2] completion: take into account the formatting backticks for options
Quoted 2 lines · Jean-Noël AVILA
For the GNUism, the tests on MacOS and Windows by gitgitgadget passed. But I get your point and will reroll.
Is there a good test in our test suite that validates the output of this script? I had an impression that even if the regexp match by this grep were a bit off, the only end-user visible effect of such a breakage is that some entries from config_name_list[] may be missing when "git help --config-for-completion" is called, but I do not think of any sensible way to notice that some entries are missing or extra entries exist in the output. So unless the regexp is broken so badly that makes the resulting config-list.h syntactically incorrect, it is unlikely that our test suite would catch anything, I suspect.
If I deliberately break the regexp (this is before your patch), it does not seem to break t0012 (which uses --config-for-completion).
generate-configlist.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
generate-configlist.sh +1 -1
@@ -13,7 +13,7 @@ print_config_list () { cat <<EOF static const char *config_name_list[] = { EOF - grep -h '^[a-zA-Z].*\..*::$' "$SOURCE_DIR"/Documentation/*config.adoc "$SOURCE_DIR"/Documentation/config/*.adoc | + grep -h '^[a-uA-Z].*\..*::$' "$SOURCE_DIR"/Documentation/*config.adoc "$SOURCE_DIR"/Documentation/config/*.adoc | sed '/deprecated/d; s/::$//; s/, */\n/g' | sort | sed 's/^.*$/ "&",/'
Re: [PATCH 1/2] completion: take into account the formatting backticks for options
Quoted 2 lines · On Tuesday, 18 March 2025 05:16:32 CET Junio C Hamano wrote:
Quoted 1 line · Jean-Noël AVILA
For the GNUism, the tests on MacOS and Windows by gitgitgadget passed. But
I
Quoted 13 lines
Quoted 1 line
get your point and will reroll.
Is there a good test in our test suite that validates the output of this script? I had an impression that even if the regexp match by this grep were a bit off, the only end-user visible effect of such a breakage is that some entries from config_name_list[] may be missing when "git help --config-for-completion" is called, but I do not think of any sensible way to notice that some entries are missing or extra entries exist in the output. So unless the regexp is broken so badly that makes the resulting
config-list.hsyntactically incorrect, it is unlikely that our test suite would catch anything, I suspect.
Quoted 3 lines
If I deliberately break the regexp (this is before your patch), it does not seem to break t0012 (which uses --config-for-completion).
I noticed the bug when working with git-branch's doc, because it broke t9902 which specifically tests completion for 'git config get br' and could no longer find the 'branch.' So the tests have eventually found the regression when the formatting went a little more widespread.
As for a way to validate the content of the script, I can only think of committing the config-list.h and checking when the contents diverge.
PATCH 2/2 doc: apply new format to git-branch man page
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
- Switch the synopsis to a synopsis block which automatically formats placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use backticks for keywords and more complex option descriptions. The new rendering engine applies synopsis rules to these spans.
--- Documentation/config/branch.adoc | 105 +++++------ Documentation/git-branch.adoc | 287 +++++++++++++++---------------- 2 files changed, 196 insertions(+), 196 deletions(-)
Documentation/config/branch.adoc +53 -52
@@ -1,41 +1,42 @@ -branch.autoSetupMerge:: - Tells 'git branch', 'git switch' and 'git checkout' to set up new branches +`branch.autoSetupMerge`:: + Tells `git branch`, `git switch` and `git checkout` to set up new branches so that linkgit:git-pull[1] will appropriately merge from the starting point branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` - and `--no-track` options. The valid settings are: `false` -- no - automatic setup is done; `true` -- automatic setup is done when the - starting point is a remote-tracking branch; `always` -- - automatic setup is done when the starting point is either a - local branch or remote-tracking branch; `inherit` -- if the starting point - has a tracking configuration, it is copied to the new - branch; `simple` -- automatic setup is done only when the starting point + and `--no-track` options. This option defaults to `true`. The valid settings + are: +`false`;; no automatic setup is done +`true`;; automatic setup is done when the starting point is a remote-tracking branch +`always`;; automatic setup is done when the starting point is either a + local branch or remote-tracking branch +`inherit`;; if the starting point has a tracking configuration, it is copied to the new + branch +`simple`;; automatic setup is done only when the starting point is a remote-tracking branch and the new branch has the same name as the - remote branch. This option defaults to true. + remote branch. -branch.autoSetupRebase:: - When a new branch is created with 'git branch', 'git switch' or 'git checkout' +`branch.autoSetupRebase`:: + When a new branch is created with `git branch`, `git switch` or `git checkout` that tracks another branch, this variable tells Git to set - up pull to rebase instead of merge (see "branch.<name>.rebase"). - When `never`, rebase is never automatically set to true. - When `local`, rebase is set to true for tracked branches of - other local branches. - When `remote`, rebase is set to true for tracked branches of - remote-tracking branches. - When `always`, rebase will be set to true for all tracking - branches. - See "branch.autoSetupMerge" for details on how to set up a - branch to track another branch. - This option defaults to never. + up pull to rebase instead of merge (see `branch.<name>.rebase`). + The valid settings are: +`never`;; rebase is never automatically set to true. +`local`;; rebase is set to true for tracked branches of other local branches. +`remote`;; rebase is set to true for tracked branches of remote-tracking branches. +`always`;; rebase will be set to true for all tracking branches. -branch.sort:: ++ +See `branch.autoSetupMerge` for details on how to set up a branch to track another branch. +This option defaults to `never`. + +`branch.sort`:: This variable controls the sort ordering of branches when displayed by - linkgit:git-branch[1]. Without the "--sort=<value>" option provided, the + linkgit:git-branch[1]. Without the `--sort=<value>` option provided, the value of this variable will be used as the default. See linkgit:git-for-each-ref[1] field names for valid values. -branch.<name>.remote:: - When on branch <name>, it tells 'git fetch' and 'git push' +`branch.<name>.remote`:: + When on branch _<name>_, it tells `git fetch` and `git push` which remote to fetch from or push to. The remote to push to may be overridden with `remote.pushDefault` (for all branches). The remote to push to, for the current branch, may be further
@@ -46,58 +47,58 @@ branch.<name>.remote:: Additionally, `.` (a period) is the current local repository (a dot-repository), see `branch.<name>.merge`'s final note below. -branch.<name>.pushRemote:: - When on branch <name>, it overrides `branch.<name>.remote` for +`branch.<name>.pushRemote`:: + When on branch _<name>_, it overrides `branch.<name>.remote` for pushing. It also overrides `remote.pushDefault` for pushing - from branch <name>. When you pull from one place (e.g. your + from branch _<name>_. When you pull from one place (e.g. your upstream) and push to another place (e.g. your own publishing repository), you would want to set `remote.pushDefault` to specify the remote to push to for all branches, and use this option to override it for a specific branch. -branch.<name>.merge:: - Defines, together with branch.<name>.remote, the upstream branch - for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which - branch to merge and can also affect 'git push' (see push.default). - When in branch <name>, it tells 'git fetch' the default - refspec to be marked for merging in FETCH_HEAD. The value is +`branch.<name>.merge`:: + Defines, together with `branch.<name>.remote`, the upstream branch + for the given branch. It tells `git fetch`/`git pull`/`git rebase` which + branch to merge and can also affect `git push` (see `push.default`). + When in branch _<name>_, it tells `git fetch` the default + refspec to be marked for merging in `FETCH_HEAD`. The value is handled like the remote part of a refspec, and must match a ref which is fetched from the remote given by - "branch.<name>.remote". - The merge information is used by 'git pull' (which first calls - 'git fetch') to lookup the default branch for merging. Without - this option, 'git pull' defaults to merge the first refspec fetched. + `branch.<name>.remote`. + The merge information is used by `git pull` (which first calls + `git fetch`) to lookup the default branch for merging. Without + this option, `git pull` defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. - If you wish to setup 'git pull' so that it merges into <name> from + If you wish to setup `git pull` so that it merges into <name> from another branch in the local repository, you can point branch.<name>.merge to the desired branch, and use the relative path - setting `.` (a period) for branch.<name>.remote. + setting `.` (a period) for `branch.<name>.remote`. -branch.<name>.mergeOptions:: - Sets default options for merging into branch <name>. The syntax and +`branch.<name>.mergeOptions`:: + Sets default options for merging into branch _<name>_. The syntax and supported options are the same as those of linkgit:git-merge[1], but option values containing whitespace characters are currently not supported. -branch.<name>.rebase:: - When true, rebase the branch <name> on top of the fetched branch, +`branch.<name>.rebase`:: + When true, rebase the branch _<name>_ on top of the fetched branch, instead of merging the default branch from the default remote when - "git pull" is run. See "pull.rebase" for doing this in a non + `git pull` is run. See `pull.rebase` for doing this in a non branch-specific manner. + -When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' +When `merges` (or just `m`), pass the `--rebase-merges` option to `git rebase` so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When the value is `interactive` (or just 'i'), the rebase is run in interactive +When the value is `interactive` (or just `i`), the rebase is run in interactive mode. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] for details). -branch.<name>.description:: +`branch.<name>.description`:: Branch description, can be edited with `git branch --edit-description`. Branch description is - automatically added to the format-patch cover letter or - request-pull summary. + automatically added to the `format-patch` cover letter or + `request-pull` summary.
Documentation/git-branch.adoc +143 -144
499 lines not on this page · raw message
Signature · 1 line
gitgitgadget
Quoted 8 lines · Jean-Noël Avila via GitGitGadget
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
- Switch the synopsis to a synopsis block which automatically formats placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Usebackticksfor keywords and more complex option descriptions. The new rendering engine applies synopsis rules to these spans.
And the one effective reformatting in this patch that is not covered by the list is that the possible values for some variables, that were mentioned in the description prose, are now made into enumerated list.
Nicely done.
v2 cover doc: apply new format to git-branch man page
In reply to Jean-Noël Avila via GitGitGadgetWorking on git-branch's doc uncovered a bug in the completion logic that did not take into account the new formatting of options. Apart from that, the changes are quite standard now.
Changes since V1:
* rework commit messages
* De-GNU-ify and simplify script
Jean-Noël Avila (2):
completion: take into account the formatting backticks for options
doc: apply new format to git-branch man page
Documentation/config/branch.adoc | 105 +++++------ Documentation/git-branch.adoc | 287 +++++++++++++++---------------- generate-configlist.sh | 16 +- 3 files changed, 208 insertions(+), 200 deletions(-)
base-commit: 683c54c999c301c2cd6f715c411407c413b1d84e
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1880%2Fjnavila%2Fdoc_git_branch-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1880/jnavila/doc_git_branch-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1880
Range-diff vs v1:
1: f8883d83f30 ! 1: cd907cc4ff4 completion: take into account the formatting backticks for options
@@ Commit message
backticked in their definition lists. This patch updates the generation of
the completion list to take into account this new format.
+ The script `generate-configlist.sh` is updated to get rid of extraneous
+ commands and fit everything in a single sed script.
+
Signed-off-by: Jean-Noël Avila <[email protected]>
## generate-configlist.sh ##
@@ generate-configlist.sh: print_config_list () {
EOF
- grep -h '^[a-zA-Z].*\..*::$' "$SOURCE_DIR"/Documentation/*config.adoc "$SOURCE_DIR"/Documentation/config/*.adoc |
- sed '/deprecated/d; s/::$//; s/, */\n/g' |
-+ grep -h '^`\?[a-zA-Z].*\..*`\?::$' "$SOURCE_DIR"/Documentation/*config.adoc "$SOURCE_DIR"/Documentation/config/*.adoc |
-+ sed '/deprecated/d; s/::$//; s/`//g; s/, */\n/g' |
- sort |
- sed 's/^.*$/ "&",/'
+- sort |
+- sed 's/^.*$/ "&",/'
++ sed -E '
++/^`?[a-zA-Z].*\..*`?::$/ {
++ /deprecated/d;
++ s/::$//;
++ s/`//g;
++ s/^.*$/ "&",/;
++ s/, */",\n "/g;
++ p;};
++d' \
++ "$SOURCE_DIR"/Documentation/*config.adoc \
++ "$SOURCE_DIR"/Documentation/config/*.adoc|
++ sort
cat <<EOF
+ NULL,
+ }; 2: b2e7867006e ! 2: a22ae89dcd0 doc: apply new format to git-branch man page
@@ Commit message
descriptions. The new rendering engine applies synopsis rules to these spans.
+ Possible values for some variables, that were mentioned in the description
+ prose, are now made into enumerated list.
+
## Documentation/config/branch.adoc ##
Signature · 1 line
gitgitgadget
PATCH v2 1/2 completion: take into account the formatting backticks for options
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
With the modern formatting of the manpages, the options and commands are now backticked in their definition lists. This patch updates the generation of the completion list to take into account this new format.
The script generate-configlist.sh is updated to get rid of extraneous commands and fit everything in a single sed script.
--- generate-configlist.sh | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-)
generate-configlist.sh +12 -4
@@ -13,10 +13,18 @@ print_config_list () { cat <<EOF static const char *config_name_list[] = { EOF - grep -h '^[a-zA-Z].*\..*::$' "$SOURCE_DIR"/Documentation/*config.adoc "$SOURCE_DIR"/Documentation/config/*.adoc | - sed '/deprecated/d; s/::$//; s/, */\n/g' | - sort | - sed 's/^.*$/ "&",/' + sed -E ' +/^`?[a-zA-Z].*\..*`?::$/ { + /deprecated/d; + s/::$//; + s/`//g; + s/^.*$/ "&",/; + s/, */",\n "/g; + p;}; +d' \ + "$SOURCE_DIR"/Documentation/*config.adoc \ + "$SOURCE_DIR"/Documentation/config/*.adoc| + sort cat <<EOF NULL, };
Signature · 1 line
gitgitgadget
PATCH v2 2/2 doc: apply new format to git-branch man page
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
- Switch the synopsis to a synopsis block which automatically formats placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use backticks for keywords and more complex option descriptions. The new rendering engine applies synopsis rules to these spans.
Possible values for some variables, that were mentioned in the description prose, are now made into enumerated list.
--- Documentation/config/branch.adoc | 105 +++++------ Documentation/git-branch.adoc | 287 +++++++++++++++---------------- 2 files changed, 196 insertions(+), 196 deletions(-)
Documentation/config/branch.adoc +53 -52
@@ -1,41 +1,42 @@ -branch.autoSetupMerge:: - Tells 'git branch', 'git switch' and 'git checkout' to set up new branches +`branch.autoSetupMerge`:: + Tells `git branch`, `git switch` and `git checkout` to set up new branches so that linkgit:git-pull[1] will appropriately merge from the starting point branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` - and `--no-track` options. The valid settings are: `false` -- no - automatic setup is done; `true` -- automatic setup is done when the - starting point is a remote-tracking branch; `always` -- - automatic setup is done when the starting point is either a - local branch or remote-tracking branch; `inherit` -- if the starting point - has a tracking configuration, it is copied to the new - branch; `simple` -- automatic setup is done only when the starting point + and `--no-track` options. This option defaults to `true`. The valid settings + are: +`false`;; no automatic setup is done +`true`;; automatic setup is done when the starting point is a remote-tracking branch +`always`;; automatic setup is done when the starting point is either a + local branch or remote-tracking branch +`inherit`;; if the starting point has a tracking configuration, it is copied to the new + branch +`simple`;; automatic setup is done only when the starting point is a remote-tracking branch and the new branch has the same name as the - remote branch. This option defaults to true. + remote branch. -branch.autoSetupRebase:: - When a new branch is created with 'git branch', 'git switch' or 'git checkout' +`branch.autoSetupRebase`:: + When a new branch is created with `git branch`, `git switch` or `git checkout` that tracks another branch, this variable tells Git to set - up pull to rebase instead of merge (see "branch.<name>.rebase"). - When `never`, rebase is never automatically set to true. - When `local`, rebase is set to true for tracked branches of - other local branches. - When `remote`, rebase is set to true for tracked branches of - remote-tracking branches. - When `always`, rebase will be set to true for all tracking - branches. - See "branch.autoSetupMerge" for details on how to set up a - branch to track another branch. - This option defaults to never. + up pull to rebase instead of merge (see `branch.<name>.rebase`). + The valid settings are: +`never`;; rebase is never automatically set to true. +`local`;; rebase is set to true for tracked branches of other local branches. +`remote`;; rebase is set to true for tracked branches of remote-tracking branches. +`always`;; rebase will be set to true for all tracking branches. -branch.sort:: ++ +See `branch.autoSetupMerge` for details on how to set up a branch to track another branch. +This option defaults to `never`. + +`branch.sort`:: This variable controls the sort ordering of branches when displayed by - linkgit:git-branch[1]. Without the "--sort=<value>" option provided, the + linkgit:git-branch[1]. Without the `--sort=<value>` option provided, the value of this variable will be used as the default. See linkgit:git-for-each-ref[1] field names for valid values. -branch.<name>.remote:: - When on branch <name>, it tells 'git fetch' and 'git push' +`branch.<name>.remote`:: + When on branch _<name>_, it tells `git fetch` and `git push` which remote to fetch from or push to. The remote to push to may be overridden with `remote.pushDefault` (for all branches). The remote to push to, for the current branch, may be further
@@ -46,58 +47,58 @@ branch.<name>.remote:: Additionally, `.` (a period) is the current local repository (a dot-repository), see `branch.<name>.merge`'s final note below. -branch.<name>.pushRemote:: - When on branch <name>, it overrides `branch.<name>.remote` for +`branch.<name>.pushRemote`:: + When on branch _<name>_, it overrides `branch.<name>.remote` for pushing. It also overrides `remote.pushDefault` for pushing - from branch <name>. When you pull from one place (e.g. your + from branch _<name>_. When you pull from one place (e.g. your upstream) and push to another place (e.g. your own publishing repository), you would want to set `remote.pushDefault` to specify the remote to push to for all branches, and use this option to override it for a specific branch. -branch.<name>.merge:: - Defines, together with branch.<name>.remote, the upstream branch - for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which - branch to merge and can also affect 'git push' (see push.default). - When in branch <name>, it tells 'git fetch' the default - refspec to be marked for merging in FETCH_HEAD. The value is +`branch.<name>.merge`:: + Defines, together with `branch.<name>.remote`, the upstream branch + for the given branch. It tells `git fetch`/`git pull`/`git rebase` which + branch to merge and can also affect `git push` (see `push.default`). + When in branch _<name>_, it tells `git fetch` the default + refspec to be marked for merging in `FETCH_HEAD`. The value is handled like the remote part of a refspec, and must match a ref which is fetched from the remote given by - "branch.<name>.remote". - The merge information is used by 'git pull' (which first calls - 'git fetch') to lookup the default branch for merging. Without - this option, 'git pull' defaults to merge the first refspec fetched. + `branch.<name>.remote`. + The merge information is used by `git pull` (which first calls + `git fetch`) to lookup the default branch for merging. Without + this option, `git pull` defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. - If you wish to setup 'git pull' so that it merges into <name> from + If you wish to setup `git pull` so that it merges into <name> from another branch in the local repository, you can point branch.<name>.merge to the desired branch, and use the relative path - setting `.` (a period) for branch.<name>.remote. + setting `.` (a period) for `branch.<name>.remote`. -branch.<name>.mergeOptions:: - Sets default options for merging into branch <name>. The syntax and +`branch.<name>.mergeOptions`:: + Sets default options for merging into branch _<name>_. The syntax and supported options are the same as those of linkgit:git-merge[1], but option values containing whitespace characters are currently not supported. -branch.<name>.rebase:: - When true, rebase the branch <name> on top of the fetched branch, +`branch.<name>.rebase`:: + When true, rebase the branch _<name>_ on top of the fetched branch, instead of merging the default branch from the default remote when - "git pull" is run. See "pull.rebase" for doing this in a non + `git pull` is run. See `pull.rebase` for doing this in a non branch-specific manner. + -When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' +When `merges` (or just `m`), pass the `--rebase-merges` option to `git rebase` so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When the value is `interactive` (or just 'i'), the rebase is run in interactive +When the value is `interactive` (or just `i`), the rebase is run in interactive mode. + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] for details). -branch.<name>.description:: +`branch.<name>.description`:: Branch description, can be edited with `git branch --edit-description`. Branch description is - automatically added to the format-patch cover letter or - request-pull summary. + automatically added to the `format-patch` cover letter or + `request-pull` summary.
Documentation/git-branch.adoc +143 -144
499 lines not on this page · raw message
Signature · 1 line
gitgitgadget