On Sun, Jul 01, 2007 at 02:26:08PM +0900, しらいしななこ wrote:
> This describes the git-stash command.
A few minor language nits follow (Junio, I can provide a patch, but if
you haven't pushed it out, it might be simpler to just --amend). Some
are obviously correct, and some are minor or matters of taste. Feel free
to ignore the latter. :)
> +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`
> +commands. The default operation when called without options is to
> +save the changes away.
The 'commands' at the end of the first sentence doesn't quite work. It
needs to be either "with the `foo` command" or "with `foo`" (I think the
latter is preferable, since the list structure makes the article sound
awkward).
> +The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
> +stashes are found in the reflog of this refererence and can be named using
s/refererence/reference/
> +the usual reflog syntax (e.g. `stash@{1}` is the stash one previously made,
> +`stash@{2}` is the one before it, `stash@{2.hours.ago}` is also possible).
"the stash one previously made" is a bit ambiguous (they've all been
previously made!). How about "is the most recently created stash"?
> +(no subcommand)::
> +
> + Save your local modifications to a new 'stash', and run `git-reset
> + --hard` to revert them.
For orthogonality's sake, should this be 'git-stash save', aliased to
just 'git-stash'? It would make this heading a little more intuitive,
and the very first paragraph (describing all of the modes) a little more
clear.
I can work up a patch if there's agreement.
> +list::
> +
> + 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
> + the one before),
"...the one before, etc.)" is slightly more clear to me.
> the name of the branch that was current when the
> + stash was made, and a short description of the commit the stash was
> + based on.
"the name of the branch that was current when the stash was made" seems
a bit awkward, but it's actually quite accurate.
> + Show the changes recorded in the stash. When no `<stash>` is given,
> + shows the latest one. By default, the command shows diffstat, but
> + you can add `-p` option (i.e. `git stash show -p stash@{2}`) to view
> + it in patch form.
s/shows diffstat/shows the diffstat of the changes/
s/i.e./e.g./
Also, you can use any diff options. So maybe the whole thing would be
better written as (Is there a better term for "original parent" here?):
Show the changes recorded in the stash as a diff between the 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@{2}` to view the second most recent stash in patch form).
We refer to "the changes" a lot...maybe it would be better to introduce
and define a term like "stash changes" early on and then use it. But
without that, I'm not sure it's clear that the stash can really be
thought of as a diff (since, after all, git stores states, stashes
included). I guess we talk about that later, but at this point in the
manual I think it's a little confusing.
> +apply [<stash>]::
> +
> + Restores the changes recorded in the stash on top of the current
s/Restores/Restore/ to match the imperative of the other command
descriptions.
> + working tree state. When no `<stash>` is given, applies the latest
> + one. The working directory must match the index. When the changes
> + conflict, you need to resolve them by hand and mark the result with
> + `git add` as usual. When the changes are cleanly merged, your
> + earlier local changes stored in the stash becomes the differences
> + between the index and the working tree (i.e. `git diff`), except
> + that newly created files are registered in the index (i.e. `git diff
> + --cached` is necessary to review the newly added files).
I'm not quite sure I understand what this is saying.
> +clear::
> + Removes all the stashed states.
Maybe a note to indicate that this can lose data? Something like:
...stashed states. Note that those states will then be subject to
pruning, and may be difficult or impossible to recover.
> +When you are in the middle of something, you learn that there are
> +changes that possibly are relevant to what you are doing in the
> +upstream. When your local changes do not conflict with the changes in
> +the upstream, a simple `git pull` will let you move forward.
The first sentence would be more clear if we moved the prepositional
phrase "in the upstream":
When you are in the middle of something, you learn that there are
changes in the upstream that are possibly relevant to what you are
doing.
or even:
When you are in the middle of something, you learn that there are
upstream changes that are possibly relevant to what you are doing.
> ++
> +However, there are cases in which your local changes do conflict with
> +the upstream changes, and `git pull` refuses to overwrite your
> +changes. In such a case, you can first stash your changes away,
> +perform a pull, and then unstash, like this:
I think the "first" in the last sentence is confusing, since we don't
use a "then" in the second step ("perform a pull") to indicate that we
have gone on to the second step.
> +When you are in the middle of something, your boss comes in and
> +demands you to fix something immediately. Traditionally, you would
s/demands you to fix/demands that you fix/
> +make a commit to a temporary branch to store your changes away, and
> +come back to make the emergency fix, like this:
"come back" is pretty vague here. Maybe "return to your original
branch"?
Otherwise, I think the page is very well written, and the examples are
very clear.
-Peff
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
