Add headings for each form of the "git branch" command. Hopefully this will make the description easier to read straight through without getting lost and help technical writers to see what needs improvement in the treatment of each form. Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx> --- Documentation/git-branch.txt | 53 +++++++++++++++++++++++------------------ 1 files changed, 30 insertions(+), 23 deletions(-) diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 9106d38..d3eeb94 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -18,25 +18,30 @@ SYNOPSIS DESCRIPTION ----------- -With no arguments, existing branches are listed and the current branch will -be highlighted with an asterisk. Option `-r` causes the remote-tracking -branches to be listed, and option `-a` shows both. +'git branch' [-r | -a]:: + With no arguments, existing branches are listed and the current + branch will be highlighted with an asterisk. + Option `-r` causes the remote-tracking branches to be listed, + and option `-a` shows both. -With `--contains`, shows only the branches that contain the named commit -(in other words, the branches whose tip commits are descendants of the -named commit). With `--merged`, only branches merged into the named -commit (i.e. the branches whose tip commits are reachable from the named -commit) will be listed. With `--no-merged` only branches not merged into -the named commit will be listed. If the <commit> argument is missing it -defaults to 'HEAD' (i.e. the tip of the current branch). - -The command's second form creates a new branch head named <branchname> -which points to the current 'HEAD', or <start-point> if given. +'git branch' (--contains | --merged | --no-merged) [<commit>]:: + With `--contains`, shows only the branches that contain the + named commit (in other words, the branches whose tip commits are + descendants of the named commit). With `--merged`, only + branches merged into the named commit (i.e. the branches whose + tip commits are reachable from the named commit) will be listed. + With `--no-merged` only branches not merged into the named + commit will be listed. If the <commit> argument is missing it + defaults to 'HEAD' (i.e. the tip of the current branch). +'git branch' <branchname> [<start-point>]:: + The command's second form creates a new branch head named <branchname> + which points to the current 'HEAD', or <start-point> if given. ++ Note that this will create the new branch, but it will not switch the working tree to it; use "git checkout <newbranch>" to switch to the new branch. - ++ When a local branch is started off a remote-tracking branch, git sets up the branch so that 'git pull' will appropriately merge from the remote-tracking branch. This behavior may be changed via the global @@ -44,16 +49,18 @@ the remote-tracking branch. This behavior may be changed via the global overridden by using the `--track` and `--no-track` options, and changed later using `git branch --set-upstream`. -With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. -If <oldbranch> had a corresponding reflog, it is renamed to match -<newbranch>, and a reflog entry is created to remember the branch -renaming. If <newbranch> exists, -M must be used to force the rename -to happen. - -With a `-d` or `-D` option, `<branchname>` will be deleted. You may -specify more than one branch for deletion. If the branch currently -has a reflog then the reflog will also be deleted. +'git branch' (-m | -M) <oldbranch> <newbranch>:: + With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. + If <oldbranch> had a corresponding reflog, it is renamed to match + <newbranch>, and a reflog entry is created to remember the branch + renaming. If <newbranch> exists, -M must be used to force the rename + to happen. +'git branch' (-d | -D) <branchname>:: + With a `-d` or `-D` option, `<branchname>` will be deleted. You may + specify more than one branch for deletion. If the branch currently + has a reflog then the reflog will also be deleted. ++ Use -r together with -d to delete remote-tracking branches. Note, that it only makes sense to delete remote-tracking branches if they no longer exist in the remote repository or if 'git fetch' was configured not to fetch -- 1.7.4.rc3 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html