diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/config/interactive.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-checkout.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-reset.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-restore.txt | 183 | ||||
| -rw-r--r-- | Documentation/git-revert.txt | 3 | ||||
| -rw-r--r-- | Documentation/git.txt | 20 | ||||
| -rw-r--r-- | Documentation/gitcli.txt | 12 |
7 files changed, 226 insertions, 5 deletions
diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt index ad846dd7c9..a2d3c7ec44 100644 --- a/Documentation/config/interactive.txt +++ b/Documentation/config/interactive.txt @@ -2,7 +2,8 @@ interactive.singleKey:: In interactive commands, allow the user to provide one-letter input with a single key (i.e., without hitting enter). Currently this is used by the `--patch` mode of - linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1], + linkgit:git-add[1], linkgit:git-checkout[1], + linkgit:git-restore[1], linkgit:git-commit[1], linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this setting is silently ignored if portable keystroke input is not available; requires the Perl module Term::ReadKey. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 58f18a0842..a294652dd6 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -570,7 +570,8 @@ $ git add frotz SEE ALSO -------- -linkgit:git-switch[1] +linkgit:git-switch[1], +linkgit:git-restore[1] GIT --- diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index cbf901efb4..c25f8a95b9 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -25,7 +25,8 @@ The `<tree-ish>`/`<commit>` defaults to `HEAD` in all forms. the current branch.) + This means that `git reset <paths>` is the opposite of `git add -<paths>`. +<paths>`. This command is equivalent to +`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 @@ -86,8 +87,8 @@ but carries forward unmerged index entries. changes, reset is aborted. -- -If you want to undo a commit other than the latest on a branch, -linkgit:git-revert[1] is your friend. +See "Reset, restore and revert" in linkgit:git[1] for the differences +between the three commands. OPTIONS diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt new file mode 100644 index 0000000000..b608f3f360 --- /dev/null +++ b/Documentation/git-restore.txt @@ -0,0 +1,183 @@ +git-restore(1) +============== + +NAME +---- +git-restore - Restore working tree files + +SYNOPSIS +-------- +[verse] +'git restore' [<options>] [--source=<tree>] [--staged] [--worktree] <pathspec>... +'git restore' (-p|--patch) [<options>] [--source=<tree>] [--staged] [--worktree] [<pathspec>...] + +DESCRIPTION +----------- +Restore specified paths in the working tree with some contents from a +restore source. If a path is tracked but does not exist in the restore +source, it will be removed to match the source. + +The command can also be used to restore the content in the index with +`--staged`, or restore both the working tree and the index with +`--staged --worktree`. + +By default, the restore sources for working tree and the index are the +index and `HEAD` respectively. `--source` could be used to specify a +commit as the restore source. + +See "Reset, restore and revert" in linkgit:git[1] for the differences +between the three commands. + +OPTIONS +------- +-s <tree>:: +--source=<tree>:: + Restore the working tree files with the content from the given + tree. It is common to specify the source tree by naming a + commit, branch or tag associated with it. ++ +If not specified, the default restore source for the working tree is +the index, and the default restore source for the index index is +`HEAD`. When both `--staged` and `--worktree` are specified, +`--source` must also be specified. + +-p:: +--patch:: + Interactively select hunks in the difference between the + restore source and the restore location. See the ``Interactive + Mode'' section of linkgit:git-add[1] to learn how to operate + the `--patch` mode. ++ +Note that `--patch` can accept no pathspec and will prompt to restore +all modified paths. + +-W:: +--worktree:: +-S:: +--staged:: + Specify the restore location. If neither option is specified, + by default the working tree is restored. Specifying `--staged` + will only restore the index. Specifying both restores both. + +-q:: +--quiet:: + Quiet, suppress feedback messages. Implies `--no-progress`. + +--progress:: +--no-progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless `--quiet` + is specified. This flag enables progress reporting even if not + attached to a terminal, regardless of `--quiet`. + +--ours:: +--theirs:: + When restoring files in the working tree from the index, use + stage #2 ('ours') or #3 ('theirs') for unmerged paths. ++ +Note that during `git rebase` and `git pull --rebase`, 'ours' and +'theirs' may appear swapped. See the explanation of the same options +in linkgit:git-checkout[1] for details. + +-m:: +--merge:: + When restoring files on the working tree from the index, + recreate the conflicted merge in the unmerged paths. + +--conflict=<style>:: + The same as `--merge` option above, but changes the way the + conflicting hunks are presented, overriding the + `merge.conflictStyle` configuration variable. Possible values + are "merge" (default) and "diff3" (in addition to what is + shown by "merge" style, shows the original contents). + +--ignore-unmerged:: + When restoring files on the working tree from the index, do + not abort the operation if there are unmerged entries and + neither `--ours`, `--theirs`, `--merge` or `--conflict` is + specified. Unmerged paths on the working tree are left alone. + +--ignore-skip-worktree-bits:: + In sparse checkout mode, by default is to only update entries + matched by `<pathspec>` and sparse patterns in + $GIT_DIR/info/sparse-checkout. This option ignores the sparse + patterns and unconditionally restores any files in + `<pathspec>`. + +--overlay:: +--no-overlay:: + In overlay mode, the command never removes files when + restoring. In no-overlay mode, tracked files that do not + appear in the `--source` tree are removed, to make them match + `<tree>` exactly. The default is no-overlay mode. + +EXAMPLES +-------- + +The following sequence switches to the `master` branch, reverts the +`Makefile` to two revisions back, deletes hello.c by mistake, and gets +it back from the index. + +------------ +$ git switch master +$ git restore --source master~2 Makefile <1> +$ rm -f hello.c +$ git restore hello.c <2> +------------ + +<1> take a file out of another commit +<2> restore hello.c from the index + +If you want to restore _all_ C source files to match the version in +the index, you can say + +------------ +$ git restore '*.c' +------------ + +Note the quotes around `*.c`. The file `hello.c` will also be +restored, even though it is no longer in the working tree, because the +file globbing is used to match entries in the index (not in the +working tree by the shell). + +To restore all files in the current directory + +------------ +$ git restore . +------------ + +or to restore all working tree files with 'top' pathspec magic (see +linkgit:gitglossary[7]) + +------------ +$ git restore :/ +------------ + +To restore a file in the index to match the version in `HEAD` (this is +the same as using linkgit:git-reset[1]) + +------------ +$ git restore --staged hello.c +------------ + +or you can restore both the index and the working tree (this the same +as using linkgit:git-checkout[1]) + +------------ +$ git restore --source=HEAD --staged --worktree hello.c +------------ + +or the short form which is more practical but less readable: + +------------ +$ git restore -s@ -SW hello.c +------------ + +SEE ALSO +-------- +linkgit:git-checkout[1], +linkgit:git-reset[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 837707a8fd..018ecf49d3 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -30,6 +30,9 @@ should see linkgit:git-checkout[1], specifically the `git checkout <commit> -- <filename>` syntax. 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 +between the three commands. + OPTIONS ------- <commit>...:: diff --git a/Documentation/git.txt b/Documentation/git.txt index 00156d64aa..fbed007354 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -210,6 +210,26 @@ people via patch over e-mail. include::cmds-foreignscminterface.txt[] +Reset, restore and revert +~~~~~~~~~~~~~~~~~~~~~~~~~ +There are three commands with similar names: `git reset`, +`git restore` and `git revert`. + +* linkgit:git-revert[1] is about making a new commit that reverts the + changes made by other commits. + +* linkgit:git-restore[1] is about restoring files in the working tree + from either the index or another commit. This command does not + update your branch. The command can also be used to restore files in + the index from another commit. + +* linkgit:git-reset[1] is about updating your branch, moving the tip + in order to add or remove commits from the branch. This operation + changes the commit history. ++ +`git reset` can also be used to restore the index, overlapping with +`git restore`. + Low-level commands (plumbing) ----------------------------- diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 592e06d839..225513ef5e 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -209,6 +209,18 @@ See also http://marc.info/?l=git&m=116563135620359 and http://marc.info/?l=git&m=119150393620273 for further information. +Some other commands that also work on files in the working tree and/or +in the index can take `--staged` and/or `--worktree`. + +* `--staged` is exactly like `--cached`, which is used to ask a + command to only work on the index, not the working tree. + +* `--worktree` is the opposite, to ask a command to work on the + working tree only, not the index. + +* The two options can be specified together to ask a command to work + on both the index and the working tree. + GIT --- Part of the linkgit:git[1] suite |