doc: git-checkout: reorganize examples
The examples are an ordered list, however, they are complex enough that a callout is inside example 1, and that confuses the parsers as the list continuation (`+`) is unclear (are we continuing the previous list item, or the previous callout?). We could use an open block as the asciidoctor documentation suggests, but that has a tiny formatting issue (a newline is missing). To simplify things for everyone (the reader, the writer, and the parser) let's use subsections. After this change, the HTML documentation generated with asciidoc has the right indentation. Cc: Jeff King <peff@peff.net> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Felipe Contreras committed
Apr 18, 2023 at 01:00 UTC
8dda6c3de21df2e2e8c09d860eae93e08cbc82a7
1 file changed
+28
-22
Documentation/git-checkout.txt
+28
-22
@@ -516,10 +516,12 @@ to checkout these paths out of the index.
516
EXAMPLES
517
--------
518
519
-. The following sequence checks out the `master` branch, reverts
520
- the `Makefile` to two revisions back, deletes `hello.c` by
521
- mistake, and gets it back from the index.
522
-+
519
+=== 1. Paths
520
+
521
+The following sequence checks out the `master` branch, reverts
522
+the `Makefile` to two revisions back, deletes `hello.c` by
523
+mistake, and gets it back from the index.
524
+
525
------------
526
$ git checkout master <1>
527
$ git checkout master~2 Makefile <2>
@@ -529,70 +531,74 @@ $ git checkout hello.c <3>
531
<1> switch branch
532
<2> take a file out of another commit
533
<3> restore `hello.c` from the index
532
-+
534
+
535
If you want to check out _all_ C source files out of the index,
536
you can say
535
-+
537
+
538
------------
539
$ git checkout -- '*.c'
540
------------
539
-+
541
+
542
Note the quotes around `*.c`. The file `hello.c` will also be
543
checked out, even though it is no longer in the working tree,
544
because the file globbing is used to match entries in the index
545
(not in the working tree by the shell).
544
-+
546
+
547
If you have an unfortunate branch that is named `hello.c`, this
548
step would be confused as an instruction to switch to that branch.
549
You should instead write:
548
-+
550
+
551
------------
552
$ git checkout -- hello.c
553
------------
554
553
-. After working in the wrong branch, switching to the correct
554
- branch would be done using:
555
-+
555
+=== 2. Merge
556
+
557
+After working in the wrong branch, switching to the correct
558
+branch would be done using:
559
+
560
------------
561
$ git checkout mytopic
562
------------
559
-+
563
+
564
However, your "wrong" branch and correct `mytopic` branch may
565
differ in files that you have modified locally, in which case
566
the above checkout would fail like this:
563
-+
567
+
568
------------
569
$ git checkout mytopic
570
error: You have local changes to 'frotz'; not switching branches.
571
------------
568
-+
572
+
573
You can give the `-m` flag to the command, which would try a
574
three-way merge:
571
-+
575
+
576
------------
577
$ git checkout -m mytopic
578
Auto-merging frotz
579
------------
576
-+
580
+
581
After this three-way merge, the local modifications are _not_
582
registered in your index file, so `git diff` would show you what
583
changes you made since the tip of the new branch.
584
581
-. When a merge conflict happens during switching branches with
582
- the `-m` option, you would see something like this:
583
-+
585
+=== 3. Merge conflict
586
+
587
+When a merge conflict happens during switching branches with
588
+the `-m` option, you would see something like this:
589
+
590
------------
591
$ git checkout -m mytopic
592
Auto-merging frotz
593
ERROR: Merge conflict in frotz
594
fatal: merge program failed
595
------------
590
-+
596
+
597
At this point, `git diff` shows the changes cleanly merged as in
598
the previous example, as well as the changes in the conflicted
599
files. Edit and resolve the conflict and mark it resolved with
600
`git add` as usual:
595
-+
601
+
602
------------
603
$ edit frotz
604
$ git add frotz