From: "Julia Evans via GitGitGadget" <gitgitgadget@gmail•com>
To: git@vger•kernel.org
Cc: "D. Ben Knoble" <ben.knoble@gmail•com>,
Julia Evans <julia@jvns•ca>, Julia Evans <julia@jvns•ca>
Subject: [PATCH v3 5/6] doc: git-checkout: split up restoring files section
Date: Wed, 03 Sep 2025 16:50:01 +0000 [thread overview]
Message-ID: <24793f9a451a1b906952256bc2f67c395a02f66b.1756918202.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1962.v3.git.1756918202.gitgitgadget@gmail.com>
From: Julia Evans <julia@jvns•ca>
Will make it easier to explain the two versions clearly in the following
commit. As a bonus, now the structure of the DESCRIPTION
matches the SYNOPSIS.
Also remove `-f` from `git checkout <tree-ish> <pathspec>` since it's
not relevant in that context.
Signed-off-by: Julia Evans <julia@jvns•ca>
---
Documentation/git-checkout.adoc | 23 +++++++++++++----------
1 file changed, 13 insertions(+), 10 deletions(-)
diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index d35fd32ce8..b361ff011a 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -12,8 +12,8 @@ git checkout [-q] [-f] [-m] [<branch>]
git checkout [-q] [-f] [-m] --detach [<branch>]
git checkout [-q] [-f] [-m] [--detach] <commit>
git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
-git checkout [-f] <tree-ish> [--] <pathspec>...
-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout <tree-ish> [--] <pathspec>...
+git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
@@ -71,14 +71,17 @@ commit would overwrite your uncommitted changes.
+
Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
+`git checkout <tree-ish> [--] <pathspec>...`::
+`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
- Overwrite the contents of the files that match the pathspec.
- When the _<tree-ish>_ (most often a commit) is not given,
- overwrite working tree with the contents in the index.
- When the _<tree-ish>_ is given, overwrite both the index and
- the working tree with the contents at the _<tree-ish>_.
+ Overwrite both the index and the working tree with the
+ contents at the _<tree-ish>_ for the files that match the pathspec.
+
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
+
+ Overwrite working tree with the contents in the index for the files
+ that match the pathspec.
+
The index may contain unmerged entries because of a previous failed merge.
By default, if you try to check out such an entry from the index, the
@@ -89,7 +92,7 @@ using `--ours` or `--theirs`. With `-m`, changes made to the working tree
file can be discarded to re-create the original conflicted merge result.
`git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
- This is similar to the previous mode, but lets you use the
+ This is similar to the previous two modes, but lets you use the
interactive interface to show the "diff" output and choose which
hunks to use in the result. See below for the description of
`--patch` option.
--
gitgitgadget
next prev parent reply other threads:[~2025-09-03 16:50 UTC|newest]
Thread overview: 68+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-08-25 19:08 [PATCH 0/5] doc: git-checkout: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-25 19:08 ` [PATCH 1/5] doc: git-checkout: clarify intro Julia Evans via GitGitGadget
2025-08-26 18:46 ` Junio C Hamano
2025-08-26 18:51 ` Junio C Hamano
2025-08-26 20:56 ` Julia Evans
2025-08-28 14:00 ` D. Ben Knoble
2025-08-28 22:34 ` Julia Evans
2025-08-28 23:44 ` Junio C Hamano
2025-08-29 13:39 ` D. Ben Knoble
2025-08-29 21:00 ` Junio C Hamano
2025-09-03 23:48 ` D. Ben Knoble
2025-08-25 19:08 ` [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-08-26 21:38 ` Junio C Hamano
2025-08-28 12:11 ` Julia Evans
2025-08-28 15:45 ` Junio C Hamano
2025-08-28 18:24 ` Julia Evans
2025-08-25 19:08 ` [PATCH 3/5] doc: git-checkout: don't use "reset" Julia Evans via GitGitGadget
2025-08-25 19:08 ` [PATCH 4/5] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-08-25 19:08 ` [PATCH 5/5] doc: git-checkout: clarify restoring files section Julia Evans via GitGitGadget
2025-08-26 22:43 ` Junio C Hamano
2025-08-28 13:26 ` Julia Evans
2025-08-28 19:08 ` D. Ben Knoble
2025-08-28 19:59 ` Julia Evans
2025-08-28 20:38 ` Junio C Hamano
2025-08-29 13:48 ` D. Ben Knoble
2025-08-29 11:45 ` [PATCH v2 0/5] doc: git-checkout: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-29 11:45 ` [PATCH v2 1/5] doc: git-checkout: clarify intro Julia Evans via GitGitGadget
2025-08-29 15:58 ` Junio C Hamano
2025-09-02 17:14 ` Julia Evans
2025-08-29 11:45 ` [PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-08-29 16:03 ` Junio C Hamano
2025-09-02 17:16 ` Julia Evans
2025-08-29 11:45 ` [PATCH v2 3/5] doc: git-checkout: don't use "reset" Julia Evans via GitGitGadget
2025-08-29 16:22 ` Junio C Hamano
2025-09-01 14:28 ` Julia Evans
2025-09-02 16:10 ` Junio C Hamano
2025-08-29 11:45 ` [PATCH v2 4/5] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-08-29 11:45 ` [PATCH v2 5/5] doc: git-checkout: clarify restoring files section Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 1/6] doc: git-checkout: clarify intro Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 2/6] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 3/6] doc: git-checkout: clarify `-b` and `-B` Julia Evans via GitGitGadget
2025-09-03 16:50 ` [PATCH v3 4/6] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-09-03 16:50 ` Julia Evans via GitGitGadget [this message]
2025-09-03 16:50 ` [PATCH v3 6/6] doc: git-checkout: clarify restoring files section Julia Evans via GitGitGadget
2025-09-03 21:29 ` Junio C Hamano
2025-09-03 21:09 ` [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section Junio C Hamano
2025-09-03 21:28 ` Julia Evans
2025-09-10 19:14 ` [PATCH v4 0/7] " Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 1/7] doc: git-checkout: clarify intro sentence Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 2/7] doc: git-checkout: clarify ARGUMENT DISAMBIGUATION Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 3/7] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 4/7] doc: git-checkout: clarify `-b` and `-B` Julia Evans via GitGitGadget
2025-09-29 18:07 ` Kristoffer Haugsbakk
2025-10-02 18:37 ` [PATCH] doc: git-checkout: fix placeholder markup kristofferhaugsbakk
2025-10-16 22:11 ` [PATCH resend] " kristofferhaugsbakk
2025-10-17 13:56 ` Julia Evans
2025-10-17 15:50 ` [PATCH v2] " kristofferhaugsbakk
2025-09-10 19:14 ` [PATCH v4 5/7] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 6/7] doc: git-checkout: split up restoring files section Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 7/7] doc: git-checkout: clarify " Julia Evans via GitGitGadget
2025-09-11 13:01 ` [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section Ben Knoble
2025-09-12 14:05 ` Julia Evans
2025-09-12 14:26 ` Kristoffer Haugsbakk
2025-09-15 23:22 ` Junio C Hamano
2025-09-16 6:41 ` Kristoffer Haugsbakk
2025-09-12 16:23 ` Junio C Hamano
2025-09-17 18:38 ` Junio C Hamano
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=24793f9a451a1b906952256bc2f67c395a02f66b.1756918202.git.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail$(echo .)com \
--cc=ben.knoble@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=julia@jvns$(echo .)ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox