path: root/Documentation
diff options
authorNguyễn Thái Ngọc Duy <>2019-04-25 09:45:58 (GMT)
committerJunio C Hamano <>2019-05-07 04:04:48 (GMT)
commit80f537f79c16efeb7b92b3409ede434a230b5679 (patch)
tree28b73ceb285fde7cec4ef84c4b685534887397c3 /Documentation
parentfc991b43df83ee32a92b9d906e77276e5dbd639c (diff)
doc: promote "git restore"
The new command "git restore" (together with "git switch") are added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguous context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands. One nice thing about git-restore is the ability to restore "everything", so it can be used in "git status" advice instead of both "git checkout" and "git reset". The three commands suggested by "git status" are add, rm and restore. "git checkout" is also removed from "git help" (i.e. it's no longer considered a commonly used command) Signed-off-by: Nguyễn Thái Ngọc Duy <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation')
10 files changed, 20 insertions, 23 deletions
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 03056da..8a31ccf 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -64,7 +64,7 @@ OPTIONS
directory) and $GIT_DIR/info/exclude, but do still use the ignore
rules given with `-e` options. This allows removing all untracked
files, including build products. This can be used (possibly in
- conjunction with 'git reset') to create a pristine
+ conjunction with 'git restore' or 'git reset') to create a pristine
working directory to test a clean build.
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index a85c2c2..7628193 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -359,7 +359,7 @@ When recording your own work, the contents of modified files in
your working tree are temporarily stored to a staging area
called the "index" with 'git add'. A file can be
reverted back, only in the index but not in the working tree,
-to that of the last commit with `git reset HEAD -- <file>`,
+to that of the last commit with `git restore --staged <file>`,
which effectively reverts 'git add' and prevents the changes to
this file from participating in the next commit. After building
the state to be committed incrementally with these commands,
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 0a24a56..01bfcec 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -422,7 +422,7 @@ One way to test if your MUA is set up correctly is:
$ git fetch <project> master:test-apply
$ git switch test-apply
- $ git reset --hard
+ $ git restore --source=HEAD --staged --worktree :/
$ git am a.patch
If it does not apply correctly, there can be various reasons.
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index c25f8a9..633d71d 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -29,9 +29,9 @@ This means that `git reset <paths>` is the opposite of `git add
`git restore [--source=<tree-ish>] --staged <paths>...`.
After running `git reset <paths>` to update the index entry, you can
-use linkgit:git-checkout[1] to check the contents out of the index to
-the working tree.
-Alternatively, using linkgit:git-checkout[1] and specifying a commit, you
+use linkgit:git-restore[1] to check the contents out of the index to
+the working tree. Alternatively, using linkgit:git-restore[1]
+and specifying a commit with `--source`, you
can copy the contents of a path out of a commit to the index and to the
working tree in one go.
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 018ecf4..9aadc36 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -26,8 +26,8 @@ effect of some earlier commits (often only a faulty one). If you want to
throw away all uncommitted changes in your working directory, you
should see linkgit:git-reset[1], particularly the `--hard` option. If
you want to extract specific files as they were in another commit, you
-should see linkgit:git-checkout[1], specifically the `git checkout
-<commit> -- <filename>` syntax. Take care with these alternatives as
+should see linkgit:git-restore[1], specifically the `--source`
+option. Take care with these alternatives as
both will discard uncommitted changes in your working directory.
See "Reset, restore and revert" in linkgit:git[1] for the differences
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 225513e..1ed3ca3 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -47,8 +47,8 @@ disambiguating `--` at appropriate places.
-$ git checkout -- *.c
-$ git checkout -- \*.c
+$ git restore *.c
+$ git restore \*.c
The former lets your shell expand the fileglob, and you are asking
diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt
index ad455f3..1bd919f 100644
--- a/Documentation/giteveryday.txt
+++ b/Documentation/giteveryday.txt
@@ -51,8 +51,7 @@ following commands.
* linkgit:git-commit[1] to advance the current branch.
- * linkgit:git-reset[1] and linkgit:git-checkout[1] (with
- pathname parameters) to undo changes.
+ * linkgit:git-restore[1] to undo changes.
* linkgit:git-merge[1] to merge between local branches.
@@ -82,7 +81,7 @@ Create a topic branch and develop.::
$ git switch -c alsa-audio <1>
$ edit/compile/test
-$ git checkout -- curses/ux_audio_oss.c <2>
+$ git restore curses/ux_audio_oss.c <2>
$ git add curses/ux_audio_alsa.c <3>
$ edit/compile/test
$ git diff HEAD <4>
diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt
index e0976f6..8bdb7d0 100644
--- a/Documentation/gittutorial-2.txt
+++ b/Documentation/gittutorial-2.txt
@@ -370,13 +370,13 @@ situation:
$ git status
On branch master
Changes to be committed:
- (use "git reset HEAD <file>..." to unstage)
+ (use "git restore --staged <file>..." to unstage)
new file: closing.txt
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
- (use "git checkout -- <file>..." to discard changes in working directory)
+ (use "git restore <file>..." to discard changes in working directory)
modified: file.txt
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index e6ad6b5..59ef5ce 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -110,7 +110,7 @@ $ git status
On branch master
Changes to be committed:
Your branch is up to date with 'origin/master'.
- (use "git reset HEAD <file>..." to unstage)
+ (use "git restore --staged <file>..." to unstage)
modified: file1
modified: file2
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 4e21097..8bce75b 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1446,7 +1446,7 @@ mistake, you can return the entire working tree to the last committed
state with
-$ git reset --hard HEAD
+$ git restore --staged --worktree :/
If you make a commit that you later wish you hadn't, there are two
@@ -1523,12 +1523,10 @@ Checking out an old version of a file
In the process of undoing a previous bad change, you may find it
useful to check out an older version of a particular file using
-linkgit:git-checkout[1]. We've used `git checkout` before to switch
-branches, but it has quite different behavior if it is given a path
-name: the command
+linkgit:git-restore[1]. The command
-$ git checkout HEAD^ path/to/file
+$ git restore --source=HEAD^ path/to/file
replaces path/to/file by the contents it had in the commit HEAD^, and
@@ -3800,8 +3798,8 @@ use linkgit:git-tag[1] for both.
The Workflow
-High-level operations such as linkgit:git-commit[1],
-linkgit:git-checkout[1] and linkgit:git-reset[1] work by moving data
+High-level operations such as linkgit:git-commit[1] and
+linkgit:git-restore[1] work by moving data
between the working tree, the index, and the object database. Git
provides low-level operations which perform each of these steps