Re: [PATCH 2/2] Documentation/branch: briefly explain what a branch is
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:50:28
Jonathan Nieder [off-list ref] writes:
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 <redacted> --- Documentation/git-branch.txt | 35 ++++++++++++++++++++--------------- 1 files changed, 20 insertions(+), 15 deletions(-)
I think these two are good readability changes. Just a few nits though.
quoted hunk
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.
I think "makes a new commit" is a somewhat misleading thing to say (think "fast forward" or "rebase that makes more than one"). The important point is "advances your history", isn't it? How about... ... reference is updated with various operations that advance your history, e.g. linkgit:git-commit[1], linkgit:git-pull[1], etc. Obviously we do not want to be exhausitve, so I tried to reword the above in a way that makes it explicit that we are not trying to be.
+'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.
I do not think we define what _switch_ means to explain "it does not switch the working tree to it" anywhere in the glossary. The operation not only "does not switcfh the working tree", but also does not do anything to HEAD. You and I know that, but a new reader might not, and especially after hearing that "branch ... is referred to by HEAD", might get a wrong impression that branch creation may do something to HEAD. Perhaps... This only creates a new branch; you are still on the same branch you were on before. If you want to start working on the new branch, say "git checkout <newbranch>". might be less confusing (we might also want to hint "checkout -b"). Thanks.