From: "Nguyễn Thái Ngọc Duy" <pclouds@gmail.com>
To: pclouds@gmail.com
Cc: avarab@gmail.com, git@vger.kernel.org, gitster@pobox.com,
sbeller@google.com, t.gummerer@gmail.com, sxenos@google.com
Subject: [PATCH v3 02/14] git-checkout.txt: split detached head section out
Date: Thu, 29 Nov 2018 22:58:37 +0100 [thread overview]
Message-ID: <20181129215850.7278-3-pclouds@gmail.com> (raw)
In-Reply-To: <20181129215850.7278-1-pclouds@gmail.com>
This is to be reused by the coming git-switch-branch.txt man page
which also deals with detached HEAD.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
Documentation/detach-head.txt | 132 ++++++++++++++++++++++++++++++++
Documentation/git-checkout.txt | 133 +--------------------------------
2 files changed, 133 insertions(+), 132 deletions(-)
create mode 100644 Documentation/detach-head.txt
diff --git a/Documentation/detach-head.txt b/Documentation/detach-head.txt
new file mode 100644
index 0000000000..bb6f5d7843
--- /dev/null
+++ b/Documentation/detach-head.txt
@@ -0,0 +1,132 @@
+HEAD normally refers to a named branch (e.g. 'master'). Meanwhile, each
+branch refers to a specific commit. Let's look at a repo with three
+commits, one of them tagged, and with branch 'master' checked out:
+
+------------
+ HEAD (refers to branch 'master')
+ |
+ v
+a---b---c branch 'master' (refers to commit 'c')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
+
+When a commit is created in this state, the branch is updated to refer to
+the new commit. Specifically, 'git commit' creates a new commit 'd', whose
+parent is commit 'c', and then updates branch 'master' to refer to new
+commit 'd'. HEAD still refers to branch 'master' and so indirectly now refers
+to commit 'd':
+
+------------
+$ edit; git add; git commit
+
+ HEAD (refers to branch 'master')
+ |
+ v
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
+
+It is sometimes useful to be able to checkout a commit that is not at
+the tip of any named branch, or even to create a new commit that is not
+referenced by a named branch. Let's look at what happens when we
+checkout commit 'b' (here we show two ways this may be done):
+
+------------
+$ git checkout v2.0 # or
+$ git checkout master^^
+
+ HEAD (refers to commit 'b')
+ |
+ v
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
+
+Notice that regardless of which checkout command we use, HEAD now refers
+directly to commit 'b'. This is known as being in detached HEAD state.
+It means simply that HEAD refers to a specific commit, as opposed to
+referring to a named branch. Let's see what happens when we create a commit:
+
+------------
+$ edit; git add; git commit
+
+ HEAD (refers to commit 'e')
+ |
+ v
+ e
+ /
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
+
+There is now a new commit 'e', but it is referenced only by HEAD. We can
+of course add yet another commit in this state:
+
+------------
+$ edit; git add; git commit
+
+ HEAD (refers to commit 'f')
+ |
+ v
+ e---f
+ /
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
+
+In fact, we can perform all the normal Git operations. But, let's look
+at what happens when we then checkout master:
+
+------------
+$ git checkout master
+
+ HEAD (refers to branch 'master')
+ e---f |
+ / v
+a---b---c---d branch 'master' (refers to commit 'd')
+ ^
+ |
+ tag 'v2.0' (refers to commit 'b')
+------------
+
+It is important to realize that at this point nothing refers to commit
+'f'. Eventually commit 'f' (and by extension commit 'e') will be deleted
+by the routine Git garbage collection process, unless we create a reference
+before that happens. If we have not yet moved away from commit 'f',
+any of these will create a reference to it:
+
+------------
+$ git checkout -b foo <1>
+$ git branch foo <2>
+$ git tag foo <3>
+------------
+
+<1> creates a new branch 'foo', which refers to commit 'f', and then
+updates HEAD to refer to branch 'foo'. In other words, we'll no longer
+be in detached HEAD state after this command.
+
+<2> similarly creates a new branch 'foo', which refers to commit 'f',
+but leaves HEAD detached.
+
+<3> creates a new tag 'foo', which refers to commit 'f',
+leaving HEAD detached.
+
+If we have moved away from commit 'f', then we must first recover its object
+name (typically by using git reflog), and then we can create a reference to
+it. For example, to see the last two commits to which HEAD referred, we
+can use either of these commands:
+
+------------
+$ git reflog -2 HEAD # or
+$ git log -g -2 HEAD
+------------
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 65bd1bc50d..25887a6087 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -306,138 +306,7 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
DETACHED HEAD
-------------
-HEAD normally refers to a named branch (e.g. 'master'). Meanwhile, each
-branch refers to a specific commit. Let's look at a repo with three
-commits, one of them tagged, and with branch 'master' checked out:
-
-------------
- HEAD (refers to branch 'master')
- |
- v
-a---b---c branch 'master' (refers to commit 'c')
- ^
- |
- tag 'v2.0' (refers to commit 'b')
-------------
-
-When a commit is created in this state, the branch is updated to refer to
-the new commit. Specifically, 'git commit' creates a new commit 'd', whose
-parent is commit 'c', and then updates branch 'master' to refer to new
-commit 'd'. HEAD still refers to branch 'master' and so indirectly now refers
-to commit 'd':
-
-------------
-$ edit; git add; git commit
-
- HEAD (refers to branch 'master')
- |
- v
-a---b---c---d branch 'master' (refers to commit 'd')
- ^
- |
- tag 'v2.0' (refers to commit 'b')
-------------
-
-It is sometimes useful to be able to checkout a commit that is not at
-the tip of any named branch, or even to create a new commit that is not
-referenced by a named branch. Let's look at what happens when we
-checkout commit 'b' (here we show two ways this may be done):
-
-------------
-$ git checkout v2.0 # or
-$ git checkout master^^
-
- HEAD (refers to commit 'b')
- |
- v
-a---b---c---d branch 'master' (refers to commit 'd')
- ^
- |
- tag 'v2.0' (refers to commit 'b')
-------------
-
-Notice that regardless of which checkout command we use, HEAD now refers
-directly to commit 'b'. This is known as being in detached HEAD state.
-It means simply that HEAD refers to a specific commit, as opposed to
-referring to a named branch. Let's see what happens when we create a commit:
-
-------------
-$ edit; git add; git commit
-
- HEAD (refers to commit 'e')
- |
- v
- e
- /
-a---b---c---d branch 'master' (refers to commit 'd')
- ^
- |
- tag 'v2.0' (refers to commit 'b')
-------------
-
-There is now a new commit 'e', but it is referenced only by HEAD. We can
-of course add yet another commit in this state:
-
-------------
-$ edit; git add; git commit
-
- HEAD (refers to commit 'f')
- |
- v
- e---f
- /
-a---b---c---d branch 'master' (refers to commit 'd')
- ^
- |
- tag 'v2.0' (refers to commit 'b')
-------------
-
-In fact, we can perform all the normal Git operations. But, let's look
-at what happens when we then checkout master:
-
-------------
-$ git checkout master
-
- HEAD (refers to branch 'master')
- e---f |
- / v
-a---b---c---d branch 'master' (refers to commit 'd')
- ^
- |
- tag 'v2.0' (refers to commit 'b')
-------------
-
-It is important to realize that at this point nothing refers to commit
-'f'. Eventually commit 'f' (and by extension commit 'e') will be deleted
-by the routine Git garbage collection process, unless we create a reference
-before that happens. If we have not yet moved away from commit 'f',
-any of these will create a reference to it:
-
-------------
-$ git checkout -b foo <1>
-$ git branch foo <2>
-$ git tag foo <3>
-------------
-
-<1> creates a new branch 'foo', which refers to commit 'f', and then
-updates HEAD to refer to branch 'foo'. In other words, we'll no longer
-be in detached HEAD state after this command.
-
-<2> similarly creates a new branch 'foo', which refers to commit 'f',
-but leaves HEAD detached.
-
-<3> creates a new tag 'foo', which refers to commit 'f',
-leaving HEAD detached.
-
-If we have moved away from commit 'f', then we must first recover its object
-name (typically by using git reflog), and then we can create a reference to
-it. For example, to see the last two commits to which HEAD referred, we
-can use either of these commands:
-
-------------
-$ git reflog -2 HEAD # or
-$ git log -g -2 HEAD
-------------
+include::detach-head.txt[]
ARGUMENT DISAMBIGUATION
-----------------------
--
2.20.0.rc1.380.g3eb999425c.dirty
next prev parent reply other threads:[~2018-11-29 21:59 UTC|newest]
Thread overview: 110+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-11-10 13:35 [PATCH/RFC] checkout: print something when checking out paths Nguyễn Thái Ngọc Duy
2018-11-12 6:21 ` Junio C Hamano
2018-11-12 16:27 ` Duy Nguyen
2018-11-12 20:15 ` Junio C Hamano
2018-11-19 13:08 ` Ævar Arnfjörð Bjarmason
2018-11-19 15:19 ` Duy Nguyen
2018-11-20 2:53 ` Junio C Hamano
2018-11-20 17:45 ` [RFC] Introduce two new commands, switch-branch and restore-paths Duy Nguyen
2018-11-25 22:20 ` Thomas Gummerer
2018-11-26 3:03 ` Junio C Hamano
2018-11-26 15:37 ` Duy Nguyen
2018-11-26 16:00 ` Ævar Arnfjörð Bjarmason
2018-11-26 16:08 ` Duy Nguyen
2018-11-26 23:10 ` Stefan Beller
2018-11-27 0:34 ` Junio C Hamano
2018-11-27 16:52 ` [PATCH/RFC v2 0/7] Introduce new commands switch-branch and checkout-files Nguyễn Thái Ngọc Duy
2018-11-27 16:52 ` [PATCH v2 1/7] parse-options: allow parse_options_concat(NULL, options) Nguyễn Thái Ngọc Duy
2018-11-27 19:43 ` Stefan Beller
2018-11-28 15:22 ` Duy Nguyen
2018-11-28 4:47 ` Junio C Hamano
2018-11-27 16:52 ` [PATCH v2 2/7] checkout: make "opts" in cmd_checkout() a pointer Nguyễn Thái Ngọc Duy
2018-11-27 16:52 ` [PATCH v2 3/7] checkout: move 'confict_style' to checkout_opts Nguyễn Thái Ngọc Duy
2018-11-27 19:50 ` Stefan Beller
2018-11-27 16:52 ` [PATCH v2 4/7] checkout: move dwim_new_local_branch " Nguyễn Thái Ngọc Duy
2018-11-27 19:52 ` Stefan Beller
2018-11-27 16:52 ` [PATCH v2 5/7] checkout: split options[] array in three pieces Nguyễn Thái Ngọc Duy
2018-11-29 6:29 ` Junio C Hamano
2018-11-27 16:52 ` [PATCH v2 6/7] checkout: split into switch-branch and checkout-files Nguyễn Thái Ngọc Duy
2018-11-28 6:03 ` Junio C Hamano
2018-11-28 15:30 ` Duy Nguyen
2018-11-28 19:08 ` Stefan Beller
2018-11-28 19:18 ` Duy Nguyen
2018-11-29 5:55 ` Junio C Hamano
2018-11-28 23:22 ` Stefan Xenos
2018-11-28 23:26 ` Stefan Xenos
2018-11-28 23:37 ` Stefan Xenos
2018-11-29 5:59 ` Junio C Hamano
2018-11-29 15:36 ` Duy Nguyen
2018-11-29 15:46 ` Duy Nguyen
2018-11-29 18:14 ` Stefan Beller
2018-11-29 18:30 ` Duy Nguyen
2018-11-29 19:29 ` Stefan Xenos
2018-11-27 16:52 ` [PATCH v2 7/7] Suggest other commands instead of "git checkout" Nguyễn Thái Ngọc Duy
2018-11-28 6:04 ` Junio C Hamano
2018-11-28 15:33 ` Duy Nguyen
2018-11-29 6:05 ` Junio C Hamano
2018-11-28 20:01 ` [PATCH/RFC v2 0/7] Introduce new commands switch-branch and checkout-files Duy Nguyen
2018-11-28 20:09 ` Duy Nguyen
2018-11-28 20:30 ` Stefan Beller
2018-11-29 15:33 ` Duy Nguyen
2018-12-03 21:42 ` Stefan Beller
2018-11-30 1:47 ` Junio C Hamano
[not found] ` <CAPL8Ziuj7Ffmdvz6NZWSJ+vzAtxFQhO1cfY2wmXm16J_8sY5fw@mail.gmail.com>
2018-11-28 22:53 ` Stefan Xenos
2018-11-29 6:14 ` Junio C Hamano
2018-11-29 21:58 ` [PATCH/RFC v3 00/14] Introduce new commands switch-branch and restore-files Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 01/14] git-checkout.txt: fix one syntax line Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` Nguyễn Thái Ngọc Duy [this message]
2018-11-29 21:58 ` [PATCH v3 03/14] checkout: factor out some code in parse_branchname_arg() Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 04/14] checkout: make "opts" in cmd_checkout() a pointer Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 05/14] checkout: move 'confict_style' and 'dwim_..' to checkout_opts Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 06/14] checkout: split options[] array in three pieces Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 07/14] checkout: split into switch-branch and restore-files Nguyễn Thái Ngọc Duy
2018-12-04 0:45 ` Elijah Newren
2018-12-04 3:33 ` Junio C Hamano
2018-12-04 16:21 ` Duy Nguyen
2018-12-04 17:43 ` Elijah Newren
2018-12-04 18:17 ` Duy Nguyen
2018-12-05 2:25 ` Junio C Hamano
2018-12-05 4:45 ` Elijah Newren
2018-12-05 6:56 ` Junio C Hamano
2018-12-05 2:14 ` Junio C Hamano
2018-12-05 4:22 ` Elijah Newren
2018-11-29 21:58 ` [PATCH v3 08/14] switch-branch: better names for -b and -B Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 09/14] switch-branch: stop accepting pathspec Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 10/14] switch-branch: reject "do nothing" case Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 11/14] switch-branch: only allow explicit detached HEAD Nguyễn Thái Ngọc Duy
2019-03-10 19:32 ` Eckhard Maaß
2019-03-11 14:27 ` Duy Nguyen
2018-11-29 21:58 ` [PATCH v3 12/14] restore-files: take tree-ish from --from option instead Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 13/14] restore-files: make pathspec mandatory Nguyễn Thái Ngọc Duy
2018-11-29 21:58 ` [PATCH v3 14/14] doc: promote "git switch-branch" and "git restore-files" Nguyễn Thái Ngọc Duy
2018-11-29 23:05 ` [PATCH/RFC v3 00/14] Introduce new commands switch-branch and restore-files Ævar Arnfjörð Bjarmason
2018-11-29 23:18 ` Ævar Arnfjörð Bjarmason
2018-11-29 23:37 ` Dan Fabulich
2018-11-30 0:16 ` Dan Fabulich
2018-11-30 6:49 ` Duy Nguyen
2018-11-30 5:37 ` Duy Nguyen
2018-11-30 6:47 ` Junio C Hamano
2018-11-30 11:29 ` Ævar Arnfjörð Bjarmason
2018-11-30 12:10 ` Duy Nguyen
2018-11-30 2:16 ` Junio C Hamano
2018-11-30 5:41 ` Duy Nguyen
2018-11-30 6:46 ` Junio C Hamano
2018-12-02 18:58 ` Thomas Gummerer
2018-12-02 19:46 ` Junio C Hamano
2018-12-04 1:28 ` Elijah Newren
2018-12-04 16:27 ` Duy Nguyen
2018-12-04 17:45 ` Elijah Newren
2018-12-04 18:22 ` Duy Nguyen
2018-12-04 18:31 ` Elijah Newren
2018-12-04 18:39 ` Duy Nguyen
2018-12-04 21:18 ` Eric Sunshine
2018-11-13 18:28 ` [PATCH v2] checkout: print something when checking out paths Nguyễn Thái Ngọc Duy
2018-11-14 10:12 ` Junio C Hamano
2018-11-14 15:31 ` Duy Nguyen
2019-01-28 21:58 ` Junio C Hamano
2019-01-29 1:26 ` Duy Nguyen
2019-02-06 2:51 ` [PATCH 0/2] nd/checkout-noisy updates Nguyễn Thái Ngọc Duy
2019-02-06 2:51 ` [PATCH 1/2] checkout: update count-checkouts messages Nguyễn Thái Ngọc Duy
2019-02-06 2:51 ` [PATCH 2/2] checkout: count and print -m paths separately Nguyễn Thái Ngọc Duy
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20181129215850.7278-3-pclouds@gmail.com \
--to=pclouds@gmail.com \
--cc=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=sbeller@google.com \
--cc=sxenos@google.com \
--cc=t.gummerer@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).