The new reader might not know what git refs are, that history is a graph, the distinction between local, remote-tracking, and remote branches, or how to visualize what is going on. After this change, those things are still probably not evident but at least there is an early reminder of some of it. Also explain how to create a branch before explaining how to list them. Based roughly on the description of v0.99.1~53 (Add "git branch" script, 2005-07-11). Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx> --- Documentation/git-branch.txt | 35 ++++++++++++++++++++--------------- 1 files changed, 20 insertions(+), 15 deletions(-) diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index d3eeb94..abad7ba 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -18,6 +18,26 @@ SYNOPSIS DESCRIPTION ----------- +Branches are references to commit objects, representing the tip of a +line of history. The branch you are working on is referred to +by HEAD and the corresponding reference is updated each time +linkgit:git-commit[1] or linkgit:git-merge[1] makes a new commit. + +'git branch' <branchname> [<start-point>]:: + Creates a new branch named `<branchname>`. + If a starting point is specified, that will be where the branch + is created; otherwise, the new branch points to the `HEAD` commit. ++ +This will create a new branch, but it does not switch the working tree +to it. Use "git checkout <newbranch>" to start working on 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 +`branch.autosetupmerge` configuration flag. That setting can be +overridden by using the `--track` and `--no-track` options, and +changed later using `git branch --set-upstream`. + 'git branch' [-r | -a]:: With no arguments, existing branches are listed and the current branch will be highlighted with an asterisk. @@ -34,21 +54,6 @@ DESCRIPTION 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 -`branch.autosetupmerge` configuration flag. That setting can be -overridden by using the `--track` and `--no-track` options, and -changed later using `git branch --set-upstream`. - '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 -- 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