@matheusbsbs / matheus-bagliano / commits / 9488e87586
Fork 0

git-stash: require "save" to be explicit and update documentation

Signed-off-by: Junio C Hamano <gitster@pobox.com>

Junio C Hamano committed Jul 1, 2007 at 15:29 UTC 9488e875862de4e3c9b022ecd9d0845bc28d1996
2 files changed +30 -31
Documentation/git-stash.txt
+28 -29
@@ -8,32 +8,32 @@ git-stash - Stash the changes in a dirty working directory away
8 SYNOPSIS
9 --------
10 [verse]
11 -'git-stash'
12 -'git-stash' [list | show [<stash>] | apply [<stash>] | clear]
11 +'git-stash' (save | list | show [<stash>] | apply [<stash>] | clear)
12
13 DESCRIPTION
14 -----------
15
17 -Use 'git-stash' when you want to record the current state of the
16 +Use 'git-stash save' when you want to record the current state of the
17 working directory and the index, but want to go back to a clean
18 working directory. The command saves your local modifications away
19 and reverts the working directory to match the `HEAD` commit.
20
21 The modifications stashed away by this command can be listed with
22 `git-stash list`, inspected with `git-stash show`, and restored
24 -(potentially on top of a different commit) with `git-stash apply`
25 -commands. The default operation when called without options is to
26 -save the changes away.
23 +(potentially on top of a different commit) with `git-stash apply`.
24 +The default operation when called without options is to save the
25 +changes away.
26
27 The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
29 -stashes are found in the reflog of this refererence and can be named using
30 -the usual reflog syntax (e.g. `stash@{1}` is the stash one previously made,
31 -`stash@{2}` is the one before it, `stash@{2.hours.ago}` is also possible).
28 +stashes are found in the reflog of this reference and can be named using
29 +the usual reflog syntax (e.g. `stash@{1}` is the most recently
30 +created stash, `stash@{2}` is the one before it, `stash@{2.hours.ago}`
31 +is also possible).
32
33 OPTIONS
34 -------
35
36 -(no subcommand)::
36 +save::
37
38 Save your local modifications to a new 'stash', and run `git-reset
39 --hard` to revert them.
@@ -42,7 +42,7 @@ list::
42
43 List the stashes that you currently have. Each 'stash' is listed
44 with its name (e.g. `stash@{0}` is the latest stash, `stash@{1} is
45 - the one before), the name of the branch that was current when the
45 + the one before, etc.), the name of the branch that was current when the
46 stash was made, and a short description of the commit the stash was
47 based on.
48 +
@@ -53,25 +53,24 @@ stash@{1}: master: 9cc0589... Merge branch 'master' of gfi
53
54 show [<stash>]::
55
56 - Show the changes recorded in the stash. When no `<stash>` is given,
57 - shows the latest one. By default, the command shows diffstat, but
58 - you can add `-p` option (i.e. `git stash show -p stash@{2}`) to view
59 - it in patch form.
56 + Show the changes recorded in the stash as a diff between the the
57 + stashed state and its original parent. When no `<stash>` is given,
58 + shows the latest one. By default, the command shows the diffstat, but
59 + it will accept any format known to `git-diff` (e.g., `git-stash show
60 + -p stash@{2}` to view the second most recent stash in patch form).
61
62 apply [<stash>]::
63
63 - Restores the changes recorded in the stash on top of the current
64 + Restore the changes recorded in the stash on top of the current
65 working tree state. When no `<stash>` is given, applies the latest
65 - one. The working directory must match the index. When the changes
66 - conflict, you need to resolve them by hand and mark the result with
67 - `git add` as usual. When the changes are cleanly merged, your
68 - earlier local changes stored in the stash becomes the differences
69 - between the index and the working tree (i.e. `git diff`), except
70 - that newly created files are registered in the index (i.e. `git diff
71 - --cached` is necessary to review the newly added files).
66 + one. The working directory must match the index.
67 ++
68 +This operation can fail with conflicts; you need to resolve them
69 +by hand in the working tree.
70
71 clear::
74 - Removes all the stashed states.
72 + Remove all the stashed states. Note that those states will then
73 + be subject to pruning, and may be difficult or impossible to recover.
74
75
76 DISCUSSION
@@ -98,13 +97,13 @@ EXAMPLES
97 Pulling into a dirty tree::
98
99 When you are in the middle of something, you learn that there are
101 -changes that possibly are relevant to what you are doing in the
102 -upstream. When your local changes do not conflict with the changes in
100 +upstream changes that are possibly relevant to what you are
101 +doing. When your local changes do not conflict with the changes in
102 the upstream, a simple `git pull` will let you move forward.
103 +
104 However, there are cases in which your local changes do conflict with
105 the upstream changes, and `git pull` refuses to overwrite your
107 -changes. In such a case, you can first stash your changes away,
106 +changes. In such a case, you can stash your changes away,
107 perform a pull, and then unstash, like this:
108 +
109 ----------------------------------------------------------------
@@ -119,9 +118,9 @@ $ git stash apply
118 Interrupted workflow::
119
120 When you are in the middle of something, your boss comes in and
122 -demands you to fix something immediately. Traditionally, you would
121 +demands that you fix something immediately. Traditionally, you would
122 make a commit to a temporary branch to store your changes away, and
124 -come back to make the emergency fix, like this:
123 +return to your original branch to make the emergency fix, like this:
124 +
125 ----------------------------------------------------------------
126 ... hack hack hack ...
git-stash.sh
+2 -2
@@ -132,7 +132,7 @@ apply_stash () {
132
133 # Main command set
134 case "$1" in
135 -list)
135 +list | '')
136 shift
137 if test $# = 0
138 then
@@ -152,7 +152,7 @@ apply)
152 clear)
153 clear_stash
154 ;;
155 -'')
155 +save)
156 save_stash && git-reset --hard
157 ;;
158 *)