On Wed, Jan 30, 2019 at 4:49 AM Nguyễn Thái Ngọc Duy <pclouds@xxxxxxxxx> wrote: > "git checkout" doing too many things is a source of confusion for many > users (and it even bites old timers sometimes). To remedy that, the > command will be split into two new ones: switch and > something-to-checkout-paths. The good old "git checkout" command is > still here and will be until all (or most of users) are sick of it. > [...] > Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@xxxxxxxxx> > --- > diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt > @@ -0,0 +1,236 @@ > +SYNOPSIS > +'git switch' [<options>] [--guess] <branch> > +'git switch' [<options>] --detach [<start_point>>] > +'git switch' [<options>] [[-c|-C|--orphan] <new_branch>] [<start_point>] What does the third form mean when all optional arguments (that is, _all_ arguments) are omitted? Nit: I realize you inherited this from git-checkout documentation, but can you use '-' rather than '_', as in <start-point>, <new-branch>, to be consistent with other documentation, such as git-branch. > +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.
