José Miguel Armijo Fidalgo <jm.armijo.f@xxxxxxxxx> writes:
>> You won't see the custom message in `git stash list`
> If this is working as expected, maybe this is a documentation bug?
The documentation says "a short description of the commit the entry
was based on", which dates back to pretty much the day one of the
stash command 09ccdb63 (Document git-stash, 2007-07-01), and hasn't
been updated or enhanced at all ever since.
Back then, the world was simpler. The command has a single very
focused purpose: I am in the middle of doing something, my boss
descends on me, I say "git stash" to clear away everything I am
doing so that I can start working on a totally different thing and I
want to do so as quickly as possible---without even wasting any time
to write any "commit log message".
So "a short description" was just that. Automatically generated
identifier to let you identify the stash entry, so that you can get
back to the state immediately before that emergency. As long as
what is shown serves that purpose, I would say it is working as
expected, as you are not even supposed to _care_ what that message
exactly say ;-)
Readers may compare today's documentation and the original at
09ccdb63 and they will notice that, even the explanation of the
`list` subcommand hasn't changed much, the accompanying example has.
That comes from the code change made at ec96e0f6 (Document "git
stash message...", 2007-07-17) when the command learned "git stash
[save] <message>" to quickly leave a custom note. The description
for the command overall was updated to say that by default we say
"WIP on ..." but a custom message can be used, but the commit did
not update the description for `list`, so the wording "the commit
the entry was based on" was left behind, which may be a
documentation bug.
It is also a bit unfortunate that "git stash create <message>" is
exposed without enough documentation. The only reason that
subcommand exists is to allow scripts to reimplement "git stash
save/push -m <message>", which internally (1) creates a commit that
is to be used as a stash entry and (2) stores it as a stash entry in
the refs/stash. Since both of these suboperations need some
message, "git stash save/push" take a single message and use that
for both. Anybody who is emulating save/push by using create
followed by store can do the same, i.e. use the same message, but
that is not documented clearly.
We may want to update the documentation to say something like the
attached patch.
Documentation/git-stash.adoc | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)
diff --git c/Documentation/git-stash.adoc w/Documentation/git-stash.adoc
index e5e6c9d37f..e7a9165b71 100644
--- c/Documentation/git-stash.adoc
+++ w/Documentation/git-stash.adoc
@@ -38,9 +38,9 @@ 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 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.
+A stash is by default given "WIP on 'branchname' ..." as its message, but
+you can give a more descriptive message on the command line when you run
+"git stash push", "git stash save", or "git stash store".
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
@@ -76,7 +76,8 @@ list [<log-options>]::
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
+ the one before, etc.), and the message given to the entry with `save`,
+ `push`, or `store` when the
entry was made, and a short description of the commit the entry was
based on.
+
@@ -146,8 +147,11 @@ create::
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 "push" above.
+ This is intended to be useful for scripts. It actually takes
+ a _<message>_ argument, but that is for the sole consumption
+ for internal use by `push` and `save` command, so it is not
+ documented here. This is probably not the command you want
+ to use; see "push" above.
store::
