Skip to content

doc: apply new format to git-branch man page #1880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

doc: apply new format to git-branch man page #1880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cd907cc
completion: take into account the formatting backticks for options
jnavila Mar 15, 2025
a22ae89
doc: apply new format to git-branch man page
jnavila Jan 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 53 additions & 52 deletions Documentation/config/branch.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,42 @@
branch.autoSetupMerge::
Tells 'git branch', 'git switch' and 'git checkout' to set up new branches
`branch.autoSetupMerge`::
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Jean-Noël Avila via GitGitGadget" <[email protected]> writes:

> 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
> - Use `backticks` for 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.

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
Expand All @@ -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.
Loading
Loading