On Thu, Jan 31, 2019 at 12:29:01PM +0700, Duy Nguyen wrote: > > > +EXAMPLES > > > +To check out commit "HEAD~3" for temporary inspection or experiment > > > +without creating a new branch: > > > + > > > +------------ > > > +$ git switch --detach HEAD~3 > > > +HEAD is now at 9fc9555312 Merge branch 'cc/shared-index-permbits' > > > +------------ > > > + > > > +If it turns out whatever you have done is worth keeping, you can > > > +always create a new name for it (without switching away): > > > + > > > +------------ > > > +$ git switch -c good-surprises > > > +------------ > > > > I had to go re-read git-branch documentation to understand why you > > recommended "git switch -c <new-branch>" (or even why this mode > > exists) over plain "git branch <new-branch>". I wonder if the > > difference between the two deserves a bit more discussion here and > > above in the description of the -c/-C options. > > There is this bit in git-branch, will that help? > > -- 8< -- > NOTES > ----- > > If you are creating a branch that you want to checkout immediately, it is > easier to use the "git switch" command with its `-c` option to create > a branch and check it out with a single command. > -- 8< -- > > Otherwise any suggestions are welcome, I guess I could rephrase it a bit like > > -c <new_branch>:: > --create <new_branch>:: > Create a new branch named <new_branch> starting at > <start_point> before switching to the branch. This is similar > to creating a new branch with linkgit:git-branch[1] except > that `git branch` does not switch branches. I think the second sentence, in particular the "except..." part, in this description goes backwards by explaining how 'git branch' differs from this. I think the most to-the-point explanation instead of that second sentence would be something like this: This is a shorthand for 'git branch <new-branch> [<start-point>] && git switch <new-branch>'.
