diff options
Diffstat (limited to 'Documentation/git-stash.txt')
| -rw-r--r-- | Documentation/git-stash.txt | 240 |
1 files changed, 160 insertions, 80 deletions
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index db7e803038..31f1beb65b 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -9,12 +9,14 @@ SYNOPSIS -------- [verse] 'git stash' list [<options>] -'git stash' show [<stash>] +'git stash' show [<options>] [<stash>] 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] - [-u|--include-untracked] [-a|--all] [<message>]] +'git stash' [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] + [-u|--include-untracked] [-a|--all] [-m|--message <message>] + [--pathspec-from-file=<file> [--pathspec-file-nul]] + [--] [<pathspec>...]] 'git stash' clear 'git stash' create [<message>] 'git stash' store [-m|--message <message>] [-q|--quiet] <commit> @@ -30,7 +32,7 @@ and reverts the working directory to match the `HEAD` commit. The modifications stashed away by this command can be listed with `git stash list`, inspected with `git stash show`, and restored (potentially on top of a different commit) with `git stash apply`. -Calling `git stash` without any arguments is equivalent to `git stash save`. +Calling `git stash` without any arguments is equivalent to `git stash push`. A stash is by default listed as "WIP on 'branchname' ...", but you can give a more descriptive message on the command line when you create one. @@ -39,45 +41,38 @@ The latest stash you created is stored in `refs/stash`; older stashes are found in the reflog of this reference and can be named using the usual reflog syntax (e.g. `stash@{0}` is the most recently created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}` -is also possible). +is also possible). Stashes may also be referenced by specifying just the +stash index (e.g. the integer `n` is equivalent to `stash@{n}`). -OPTIONS -------- +COMMANDS +-------- -save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: +push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]:: - Save your local modifications to a new 'stash', and run `git reset - --hard` to revert them. The <message> part is optional and gives - the description along with the stashed state. For quickly making - a snapshot, you can omit _both_ "save" and <message>, but giving - only <message> does not trigger this action to prevent a misspelled - subcommand from making an unwanted stash. -+ -If the `--keep-index` option is used, all changes already added to the -index are left intact. -+ -If the `--include-untracked` option is used, all untracked files are also -stashed and then cleaned up with `git clean`, leaving the working directory -in a very clean state. If the `--all` option is used instead then the -ignored files are stashed and cleaned in addition to the untracked files. + Save your local modifications to a new 'stash entry' and roll them + back to HEAD (in the working tree and in the index). + The <message> part is optional and gives + the description along with the stashed state. + -With `--patch`, you can interactively select hunks from the diff -between HEAD and the working tree to be stashed. The stash entry is -constructed such that its index state is the same as the index state -of your repository, and its worktree contains only the changes you -selected interactively. The selected changes are then rolled back -from your worktree. See the ``Interactive Mode'' section of -linkgit:git-add[1] to learn how to operate the `--patch` mode. -+ -The `--patch` option implies `--keep-index`. You can use -`--no-keep-index` to override this. +For quickly making a snapshot, you can omit "push". In this mode, +non-option arguments are not allowed to prevent a misspelled +subcommand from making an unwanted stash entry. The two exceptions to this +are `stash -p` which acts as alias for `stash push -p` and pathspec elements, +which are allowed after a double hyphen `--` for disambiguation. + +save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: + + This option is deprecated in favour of 'git stash push'. It + differs from "stash push" in that it cannot take pathspec. + Instead, all non-option arguments are concatenated to form the stash + message. list [<options>]:: - List the stashes that you currently have. Each 'stash' is listed - with its name (e.g. `stash@{0}` is the latest stash, `stash@{1}` is + List the stash entries that you currently have. Each 'stash entry' is + listed with its name (e.g. `stash@{0}` is the latest entry, `stash@{1}` is the one before, etc.), the name of the branch that was current when the - stash was made, and a short description of the commit the stash was + entry was made, and a short description of the commit the entry was based on. + ---------------------------------------------------------------- @@ -88,38 +83,33 @@ stash@{1}: On master: 9cc0589... Add git-stash The command takes options applicable to the 'git log' command to control what is shown and how. See linkgit:git-log[1]. -show [<stash>]:: +show [<options>] [<stash>]:: - Show the changes recorded in the stash as a diff between the - stashed state and its original parent. When no `<stash>` is given, - shows the latest one. By default, the command shows the diffstat, but - it will accept any format known to 'git diff' (e.g., `git stash show - -p stash@{1}` to view the second most recent stash in patch form). + Show the changes recorded in the stash entry as a diff between the + stashed contents and the commit back when the stash entry was first + created. + By default, the command shows the diffstat, but it will accept any + format known to 'git diff' (e.g., `git stash show -p stash@{1}` + to view the second most recent entry in patch form). + You can use stash.showStat and/or stash.showPatch config variables + to change the default behavior. pop [--index] [-q|--quiet] [<stash>]:: Remove a single stashed state from the stash list and apply it on top of the current working tree state, i.e., do the inverse - operation of `git stash save`. The working directory must + operation of `git stash push`. The working directory must match the index. + Applying the state can fail with conflicts; in this case, it is not removed from the stash list. You need to resolve the conflicts by hand and call `git stash drop` manually afterwards. -+ -If the `--index` option is used, then tries to reinstate not only the working -tree's changes, but also the index's ones. However, this can fail, when you -have conflicts (which are stored in the index, where you therefore can no -longer apply the changes as they were originally). -+ -When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must -be a reference of the form `stash@{<revision>}`. apply [--index] [-q|--quiet] [<stash>]:: Like `pop`, but do not remove the state from the stash list. Unlike `pop`, `<stash>` may be any commit that looks like a commit created by - `stash save` or `stash create`. + `stash push` or `stash create`. branch <branchname> [<stash>]:: @@ -127,48 +117,137 @@ branch <branchname> [<stash>]:: the commit at which the `<stash>` was originally created, applies the changes recorded in `<stash>` to the new working tree and index. If that succeeds, and `<stash>` is a reference of the form - `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>` - is given, applies the latest one. + `stash@{<revision>}`, it then drops the `<stash>`. + -This is useful if the branch on which you ran `git stash save` has +This is useful if the branch on which you ran `git stash push` has changed enough that `git stash apply` fails due to conflicts. Since -the stash is applied on top of the commit that was HEAD at the time -`git stash` was run, it restores the originally stashed state with -no conflicts. +the stash entry is applied on top of the commit that was HEAD at the +time `git stash` was run, it restores the originally stashed state +with no conflicts. clear:: - Remove all the stashed states. Note that those states will then + Remove all the stash entries. Note that those entries will then be subject to pruning, and may be impossible to recover (see 'Examples' below for a possible strategy). drop [-q|--quiet] [<stash>]:: - Remove a single stashed state from the stash list. When no `<stash>` - is given, it removes the latest one. i.e. `stash@{0}`, otherwise - `<stash>` must be a valid stash log reference of the form - `stash@{<revision>}`. + Remove a single stash entry from the list of stash entries. create:: - Create a stash (which is a regular commit object) and return its - object name, without storing it anywhere in the ref namespace. + Create a stash entry (which is a regular commit object) and + return its object name, without storing it anywhere in the ref + namespace. This is intended to be useful for scripts. It is probably not - the command you want to use; see "save" above. + the command you want to use; see "push" above. store:: Store a given stash created via 'git stash create' (which is a dangling merge commit) in the stash ref, updating the stash reflog. This is intended to be useful for scripts. It is - probably not the command you want to use; see "save" above. + probably not the command you want to use; see "push" above. + +OPTIONS +------- +-a:: +--all:: + This option is only valid for `push` and `save` commands. ++ +All ignored and untracked files are also stashed and then cleaned +up with `git clean`. + +-u:: +--include-untracked:: + This option is only valid for `push` and `save` commands. ++ +All untracked files are also stashed and then cleaned up with +`git clean`. + +--index:: + This option is only valid for `pop` and `apply` commands. ++ +Tries to reinstate not only the working tree's changes, but also +the index's ones. However, this can fail, when you have conflicts +(which are stored in the index, where you therefore can no longer +apply the changes as they were originally). + +-k:: +--keep-index:: +--no-keep-index:: + This option is only valid for `push` and `save` commands. ++ +All changes already added to the index are left intact. + +-p:: +--patch:: + This option is only valid for `push` and `save` commands. ++ +Interactively select hunks from the diff between HEAD and the +working tree to be stashed. The stash entry is constructed such +that its index state is the same as the index state of your +repository, and its worktree contains only the changes you selected +interactively. The selected changes are then rolled back from your +worktree. See the ``Interactive Mode'' section of linkgit:git-add[1] +to learn how to operate the `--patch` mode. ++ +The `--patch` option implies `--keep-index`. You can use +`--no-keep-index` to override this. + +--pathspec-from-file=<file>:: + This option is only valid for `push` command. ++ +Pathspec is passed in `<file>` instead of commandline args. If +`<file>` is exactly `-` then standard input is used. Pathspec +elements are separated by LF or CR/LF. Pathspec elements can be +quoted as explained for the configuration variable `core.quotePath` +(see linkgit:git-config[1]). See also `--pathspec-file-nul` and +global `--literal-pathspecs`. + +--pathspec-file-nul:: + This option is only valid for `push` command. ++ +Only meaningful with `--pathspec-from-file`. Pathspec elements are +separated with NUL character and all other characters are taken +literally (including newlines and quotes). + +-q:: +--quiet:: + This option is only valid for `apply`, `drop`, `pop`, `push`, + `save`, `store` commands. ++ +Quiet, suppress feedback messages. + +\--:: + This option is only valid for `push` command. ++ +Separates pathspec from options for disambiguation purposes. + +<pathspec>...:: + This option is only valid for `push` command. ++ +The new stash entry records the modified states only for the files +that match the pathspec. The index entries and working tree files +are then rolled back to the state in HEAD only for these files, +too, leaving files that do not match the pathspec intact. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. + +<stash>:: + This option is only valid for `apply`, `branch`, `drop`, `pop`, + `show` commands. ++ +A reference of the form `stash@{<revision>}`. When no `<stash>` is +given, the latest stash is assumed (that is, `stash@{0}`). DISCUSSION ---------- -A stash is represented as a commit whose tree records the state of the -working directory, and its first parent is the commit at `HEAD` when -the stash was created. The tree of the second parent records the -state of the index when the stash is made, and it is made a child of +A stash entry is represented as a commit whose tree records the state +of the working directory, and its first parent is the commit at `HEAD` +when the entry was created. The tree of the second parent records the +state of the index when the entry is made, and it is made a child of the `HEAD` commit. The ancestry graph looks like this: .----W @@ -213,12 +292,12 @@ return to your original branch to make the emergency fix, like this: + ---------------------------------------------------------------- # ... hack hack hack ... -$ git checkout -b my_wip +$ git switch -c my_wip $ git commit -a -m "WIP" -$ git checkout master +$ git switch master $ edit emergency fix $ git commit -a -m "Fix in a hurry" -$ git checkout my_wip +$ git switch my_wip $ git reset --soft HEAD^ # ... continue hacking ... ---------------------------------------------------------------- @@ -236,14 +315,14 @@ $ git stash pop Testing partial commits:: -You can use `git stash save --keep-index` when you want to make two or +You can use `git stash push --keep-index` when you want to make two or more commits out of the changes in the work tree, and you want to test each change before committing: + ---------------------------------------------------------------- # ... hack hack hack ... $ git add --patch foo # add just first part to the index -$ git stash save --keep-index # save all other changes to the stash +$ git stash push --keep-index # save all other changes to the stash $ edit/build/test first part $ git commit -m 'First part' # commit fully tested change $ git stash pop # prepare to work on all other changes @@ -252,12 +331,12 @@ $ edit/build/test remaining parts $ git commit foo -m 'Remaining parts' ---------------------------------------------------------------- -Recovering stashes that were cleared/dropped erroneously:: +Recovering stash entries that were cleared/dropped erroneously:: -If you mistakenly drop or clear stashes, they cannot be recovered +If you mistakenly drop or clear stash entries, they cannot be recovered through the normal safety mechanisms. However, you can try the -following incantation to get a list of stashes that are still in your -repository, but not reachable any more: +following incantation to get a list of stash entries that are still in +your repository, but not reachable any more: + ---------------------------------------------------------------- git fsck --unreachable | @@ -271,7 +350,8 @@ SEE ALSO linkgit:git-checkout[1], linkgit:git-commit[1], linkgit:git-reflog[1], -linkgit:git-reset[1] +linkgit:git-reset[1], +linkgit:git-switch[1] GIT --- |