[PATCH (2nd try)] Add git-stash script

[PATCH (2nd try)] Add git-stash script

[しらいしななこ]

When my boss has something to show me and I have to update, for some
reason I am always in the middle of doing something else, and git pull
command refuses to work in such a case.

I wrote this little script to save the changes I made, perform the
update, and then come back to where I was, but on top of the updated
commit.

This is how you would use the script:

  $ git stash
  $ git pull
  $ git stash apply

Signed-off-by: Nanako Shiraishi <nanako3@bluebottle.com>
---

Here is an updated script.

Unfortunately I haven't managed to get the suggestion to use
"export GITHEAD_xxxx=NicerName" from Johannes Schindelin working
yet.

 git-stash.sh |  153 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 153 insertions(+), 0 deletions(-)
 create mode 100755 git-stash.sh

diff --git a/git-stash.sh b/git-stash.sh
new file mode 100755
index 0000000..8bf83c1
--- /dev/null
+++ b/git-stash.sh
@@ -0,0 +1,153 @@
+#!/bin/sh
+# Copyright (c) 2007, Nanako Shiraishi
+
+USAGE='[ | list | show | apply | clear]'
+
+. git-sh-setup
+require_work_tree
+
+TMP="$GIT_DIR/.git-stash.$$"
+trap 'rm -f "$TMP-*"' 0
+
+ref_stash=refs/stash
+
+no_changes () {
+	git-diff-index --quiet --cached HEAD &&
+	git-diff-files --quiet
+}
+
+clear_stash () {
+	logfile="$GIT_DIR/logs/$ref_stash" &&
+	mkdir -p "$(dirname "$logfile")" &&
+	: >"$logfile"
+}
+
+save_stash () {
+	if no_changes
+	then
+		echo >&2 'No local changes to save'
+		exit 0
+	fi
+	test -f "$GIT_DIR/logs/refs/stash" ||
+		clear_stash || die "Cannot initialize stash"
+
+	# state of the base commit
+	if b_commit=$(git-rev-parse --verify HEAD)
+	then
+		head=$(git-log --abbrev-commit --pretty=oneline -n 1 HEAD)
+	else
+		die "You do not have the initial commit yet"
+	fi
+
+	if branch=$(git-symbolic-ref -q HEAD)
+	then
+		branch=${branch#refs/heads/}
+	else
+		branch='(no branch)'
+	fi
+	msg=$(printf '%s: %s' "$branch" "$head")
+
+	# state of the index
+	i_tree=$(git-write-tree) &&
+	i_commit=$(printf 'index on %s' "$msg" |
+		git-commit-tree $i_tree -p $b_commit) ||
+		die "Cannot save the current index state"
+
+	# state of the working tree
+	w_tree=$( (
+		GIT_INDEX_FILE="$TMP-index" &&
+		export GIT_INDEX_FILE &&
+
+		rm -f "$TMP-index" &&
+		git-read-tree $i_tree &&
+		git-add -u &&
+		git-write-tree &&
+		rm -f "$TMP-index"
+	) ) ||
+		die "Cannot save the current worktree state"
+
+	# create the stash
+	w_commit=$(printf 'WIP on %s' "$msg" |
+		git-commit-tree $w_tree -p $b_commit -p $i_commit) ||
+		die "Cannot record working tree state"
+
+	git-update-ref -m "$msg" $ref_stash $w_commit ||
+		die "Cannot save the current status"
+	printf >&2 'Saved WIP on %s\n' "$msg"
+}
+
+list_stash () {
+	git-log --pretty=oneline -g "$@" $ref_stash |
+	sed -n -e 's/^[.0-9a-f]* refs\///p'
+}
+
+show_stash () {
+	flags=$(git-rev-parse --no-revs --flags "$@")
+	if test -z "$flags"
+	then
+		flags=--stat
+	fi
+	s=$(git-rev-parse --revs-only --no-flags --default $ref_stash "$@")
+
+	w_commit=$(git-rev-parse --verify "$s") &&
+	b_commit=$(git-rev-parse --verify "$s^") &&
+	git-diff $flags $b_commit $w_commit
+}
+
+apply_stash () {
+	git-diff-files --quiet ||
+		die 'Cannot restore on top of a dirty state'
+
+	# current index state
+	c_tree=$(git-write-tree) ||
+		die 'Cannot apply a stash in the middle of a merge'
+
+	s=$(git-rev-parse --revs-only --no-flags --default $ref_stash "$@") &&
+	w_tree=$(git-rev-parse --verify "$s:") &&
+	b_tree=$(git-rev-parse --verify "$s^:") ||
+		die "$*: no valid stashed state found"
+
+	if git-merge-recursive $b_tree -- $c_tree $w_tree
+	then
+		# No conflict
+		a="$TMP-added" &&
+		git-diff --cached --name-only --diff-filter=A $c_tree >"$a" &&
+		git-read-tree --reset $c_tree &&
+		git-update-index --add --stdin <"$a" ||
+			die "Cannot unstage modified files"
+		git-status
+		rm -f "$a"
+	else
+		# Merge conflict
+		exit 1
+	fi
+}
+
+# Main command set
+case "$1" in
+list)
+	shift
+	if test $# = 0
+	then
+		set x -n 10
+		shift
+	fi
+	list_stash "$@"
+	;;
+show)
+	shift
+	show_stash "$@"
+	;;
+apply)
+	shift
+	apply_stash "$@"
+	;;
+clear)
+	clear_stash
+	;;
+'')
+	save_stash && git-reset --hard
+	;;
+*)
+	usage
+esac
-- 
1.5.2

----------------------------------------------------------------------
Free pop3 email with a spam filter.
http://www.bluebottle.com

Re: [PATCH (2nd try)] Add git-stash script

[Johannes Schindelin]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 306 bytes --]

Hi,

On Sat, 30 Jun 2007, しらいしななこ wrote:

> Unfortunately I haven't managed to get the suggestion to use "export 
> GITHEAD_xxxx=NicerName" from Johannes Schindelin working yet.

If you provide a test script (see t/t[0-9]*.sh), I'll gladly provide the 
support for GITHEAD_xxxx.

Ciao,
Dscho

[PATCH (3rd try)] Add git-stash script

[しらいしななこ]

When my boss has something to show me and I have to update, for some
reason I am always in the middle of doing something else, and git pull
command refuses to work in such a case.

I wrote this little script to save the changes I made, perform the
update, and then come back to where I was, but on top of the updated
commit.

This is how you would use the script:

  $ git stash
  $ git pull
  $ git stash apply

Signed-off-by: Nanako Shiraishi <nanako3@bluebottle.com>
---

Thank you for the hint for labeling the conflict blocks.
I also added an entry to gitignore and Makefile as requested.

 .gitignore   |    1 +
 Makefile     |    3 +-
 git-stash.sh |  160 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 163 insertions(+), 1 deletions(-)
 create mode 100755 git-stash.sh

diff --git a/.gitignore b/.gitignore
index e8b060c..02d9b04 100644
--- a/.gitignore
+++ b/.gitignore
@@ -123,6 +123,7 @@ git-ssh-fetch
 git-ssh-pull
 git-ssh-push
 git-ssh-upload
+git-stash
 git-status
 git-stripspace
 git-submodule
diff --git a/Makefile b/Makefile
index a98e27a..05b1fc0 100644
--- a/Makefile
+++ b/Makefile
@@ -212,7 +212,8 @@ SCRIPT_SH = \
 	git-merge.sh git-merge-stupid.sh git-merge-octopus.sh \
 	git-merge-resolve.sh git-merge-ours.sh \
 	git-lost-found.sh git-quiltimport.sh git-submodule.sh \
-	git-filter-branch.sh
+	git-filter-branch.sh \
+	git-stash.sh
 
 SCRIPT_PERL = \
 	git-add--interactive.perl \
diff --git a/git-stash.sh b/git-stash.sh
new file mode 100755
index 0000000..05ca3a6
--- /dev/null
+++ b/git-stash.sh
@@ -0,0 +1,160 @@
+#!/bin/sh
+# Copyright (c) 2007, Nanako Shiraishi
+
+USAGE='[ | list | show | apply | clear]'
+
+. git-sh-setup
+require_work_tree
+
+TMP="$GIT_DIR/.git-stash.$$"
+trap 'rm -f "$TMP-*"' 0
+
+ref_stash=refs/stash
+
+no_changes () {
+	git-diff-index --quiet --cached HEAD &&
+	git-diff-files --quiet
+}
+
+clear_stash () {
+	logfile="$GIT_DIR/logs/$ref_stash" &&
+	mkdir -p "$(dirname "$logfile")" &&
+	: >"$logfile"
+}
+
+save_stash () {
+	if no_changes
+	then
+		echo >&2 'No local changes to save'
+		exit 0
+	fi
+	test -f "$GIT_DIR/logs/refs/stash" ||
+		clear_stash || die "Cannot initialize stash"
+
+	# state of the base commit
+	if b_commit=$(git-rev-parse --verify HEAD)
+	then
+		head=$(git-log --abbrev-commit --pretty=oneline -n 1 HEAD)
+	else
+		die "You do not have the initial commit yet"
+	fi
+
+	if branch=$(git-symbolic-ref -q HEAD)
+	then
+		branch=${branch#refs/heads/}
+	else
+		branch='(no branch)'
+	fi
+	msg=$(printf '%s: %s' "$branch" "$head")
+
+	# state of the index
+	i_tree=$(git-write-tree) &&
+	i_commit=$(printf 'index on %s' "$msg" |
+		git-commit-tree $i_tree -p $b_commit) ||
+		die "Cannot save the current index state"
+
+	# state of the working tree
+	w_tree=$( (
+		GIT_INDEX_FILE="$TMP-index" &&
+		export GIT_INDEX_FILE &&
+
+		rm -f "$TMP-index" &&
+		git-read-tree $i_tree &&
+		git-add -u &&
+		git-write-tree &&
+		rm -f "$TMP-index"
+	) ) ||
+		die "Cannot save the current worktree state"
+
+	# create the stash
+	w_commit=$(printf 'WIP on %s' "$msg" |
+		git-commit-tree $w_tree -p $b_commit -p $i_commit) ||
+		die "Cannot record working tree state"
+
+	git-update-ref -m "$msg" $ref_stash $w_commit ||
+		die "Cannot save the current status"
+	printf >&2 'Saved WIP on %s\n' "$msg"
+}
+
+list_stash () {
+	git-log --pretty=oneline -g "$@" $ref_stash |
+	sed -n -e 's/^[.0-9a-f]* refs\///p'
+}
+
+show_stash () {
+	flags=$(git-rev-parse --no-revs --flags "$@")
+	if test -z "$flags"
+	then
+		flags=--stat
+	fi
+	s=$(git-rev-parse --revs-only --no-flags --default $ref_stash "$@")
+
+	w_commit=$(git-rev-parse --verify "$s") &&
+	b_commit=$(git-rev-parse --verify "$s^") &&
+	git-diff $flags $b_commit $w_commit
+}
+
+apply_stash () {
+	git-diff-files --quiet ||
+		die 'Cannot restore on top of a dirty state'
+
+	# current index state
+	c_tree=$(git-write-tree) ||
+		die 'Cannot apply a stash in the middle of a merge'
+
+	s=$(git-rev-parse --revs-only --no-flags --default $ref_stash "$@") &&
+	w_tree=$(git-rev-parse --verify "$s:") &&
+	b_tree=$(git-rev-parse --verify "$s^:") ||
+		die "$*: no valid stashed state found"
+
+	eval "
+		GITHEAD_$w_tree='Stashed changes' &&
+		GITHEAD_$c_tree='Updated upstream' &&
+		GITHEAD_$b_tree='Version stash was based on' &&
+		export GITHEAD_$w_tree GITHEAD_$c_tree GITHEAD_$b_tree
+	"
+
+	if git-merge-recursive $b_tree -- $c_tree $w_tree
+	then
+		# No conflict
+		a="$TMP-added" &&
+		git-diff --cached --name-only --diff-filter=A $c_tree >"$a" &&
+		git-read-tree --reset $c_tree &&
+		git-update-index --add --stdin <"$a" ||
+			die "Cannot unstage modified files"
+		git-status
+		rm -f "$a"
+	else
+		# Merge conflict
+		exit 1
+	fi
+}
+
+# Main command set
+case "$1" in
+list)
+	shift
+	if test $# = 0
+	then
+		set x -n 10
+		shift
+	fi
+	list_stash "$@"
+	;;
+show)
+	shift
+	show_stash "$@"
+	;;
+apply)
+	shift
+	apply_stash "$@"
+	;;
+clear)
+	clear_stash
+	;;
+'')
+	save_stash && git-reset --hard
+	;;
+*)
+	usage
+esac
-- 
1.5.2

----------------------------------------------------------------------
Free pop3 email with a spam filter.
http://www.bluebottle.com

Re: [PATCH (3rd try)] Add git-stash script

[Jeff King]

On Sat, Jun 30, 2007 at 02:37:09PM +0900, しらいしななこ wrote:

> +ref_stash=refs/stash
[...]
> +save_stash () {
> +	if no_changes
> +	then
> +		echo >&2 'No local changes to save'
> +		exit 0
> +	fi
> +	test -f "$GIT_DIR/logs/refs/stash" ||
> +		clear_stash || die "Cannot initialize stash"

Nit: this should be .../logs/$ref_stash

-Peff

Re: [PATCH (3rd try)] Add git-stash script

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Sat, Jun 30, 2007 at 02:37:09PM +0900, しらいしななこ wrote:
>
>> +ref_stash=refs/stash
> [...]
>> +save_stash () {
>> +	if no_changes
>> +	then
>> +		echo >&2 'No local changes to save'
>> +		exit 0
>> +	fi
>> +	test -f "$GIT_DIR/logs/refs/stash" ||
>> +		clear_stash || die "Cannot initialize stash"
>
> Nit: this should be .../logs/$ref_stash

Sharp eyes.

I'll take a look and possibly comment on it later, but from a
cursory look I do not see major problems, so if I decide to
apply it I'll try to remember fixing this up when I do so...

Re: [PATCH (3rd try)] Add git-stash script

[Johannes Schindelin]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1104 bytes --]

Hi,

On Sat, 30 Jun 2007, しらいしななこ wrote:

> diff --git a/git-stash.sh b/git-stash.sh
> [...]
> +	printf >&2 'Saved WIP on %s\n' "$msg"

You have an awful lot of printfs in the code. Why not just use echos?

> +list_stash () {
> +	git-log --pretty=oneline -g "$@" $ref_stash |

Wouldn't you want "--default $ref_stash" here?

> +apply_stash () {
> +	git-diff-files --quiet ||
> +		die 'Cannot restore on top of a dirty state'

You meant "no_changes", right? I think you miss changes in the index 
otherwise.

> +		git-diff --cached --name-only --diff-filter=A $c_tree >"$a" &&
> +		git-read-tree --reset $c_tree &&
> +		git-update-index --add --stdin <"$a" ||
> +			die "Cannot unstage modified files"

Isn't there a way to avoid the temporary file here?

> +	else
> +		# Merge conflict
> +		exit 1

Since $? is already != 0, and it might tell the savvy user what kind of 
error merge-recursive returned, why not use "exit", which is equivalent to 
"exit $?"?

> +		set x -n 10
> +		shift

This is more elegantly written as "set -- -n 10", or in our context even 
"set -- -10".

Ciao,
Dscho

Re: [PATCH (3rd try)] Add git-stash script

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

>> diff --git a/git-stash.sh b/git-stash.sh
>> [...]
>> +	printf >&2 'Saved WIP on %s\n' "$msg"
>
> You have an awful lot of printfs in the code. Why not just use echos?

I had the same impression, but I would say it is Ok (actually
printf is even better).  Judging from our recent changes
(e.g. a23bfae) I think it is prudent to avoid echo when printing
user supplied messages.  Not that corrupted backslash sequence
matters that much on stderr, though ;-).

>> +list_stash () {
>> +	git-log --pretty=oneline -g "$@" $ref_stash |
>
> Wouldn't you want "--default $ref_stash" here?

But "git log --pretty=oneline -g master --default refs/stash"
would not make much sense would it?  The design currently seems
to follow what I suggested earlier, namely to use a single stash
ref per repository, so $ref_stash is spelled as a variable but
it is a constant.  IOW, you do not specify "alternate stash"
from the command line.

Unfortunately we do not have a good way to reject non-flag rev
parameters in "$@" to error out "git stash list master".  What
we would want here is a way to allow things like --since=1.hour
and -20 while rejecting branch/tag names and other parameters.

>> +apply_stash () {
>> +	git-diff-files --quiet ||
>> +		die 'Cannot restore on top of a dirty state'
>
> You meant "no_changes", right? I think you miss changes in the index 
> otherwise.

Interestingly, I think this is actually correct in the sense
that the code is internally consistent, as it uses the current
index, not the HEAD, as the base of application.  It however is
debatable if this sequence (which is allowed because it does not
use no_changes here) makes sense:

	: hack hack hack
	: get interrupted
	$ git stash
	: do something else on a clean slate
	$ git commit
        : hack hack hack
        $ git add -u
        $ git unstash

>> +		git-diff --cached --name-only --diff-filter=A $c_tree >"$a" &&
>> +		git-read-tree --reset $c_tree &&
>> +		git-update-index --add --stdin <"$a" ||
>> +			die "Cannot unstage modified files"
>
> Isn't there a way to avoid the temporary file here?

We could obviously do

	files=$(git-diff --cached ...) &&
        git-read-tree --reset $c_tree &&
        echo "$files" | git-update-index --add --stdin

Oops, the last "echo" may have to be "printf '%s'" ;-)

There might be quite many files that have been added to make the
$files variable too big to be given to echo, though.

	git-diff --cached ... |
        (
        	git-read-tree --reset $c_tree &&
                git-update-index --add --stdin
	)

would not work, unless you copy the index into a temporary file
and have the upstream git-diff use it.  But then we are using a
temporary file anyway.

>> +		set x -n 10
>> +		shift
>
> This is more elegantly written as "set -- -n 10", or in our context even 
> "set -- -10".

That is Ok in POSIX only world, but so far we have stayed away
from using "set -- potentially-dangerous-string" in any of our
scripts.  I would feel x + shift is safer and more comfortable
but probably that is largely because I am old fashioned.

Re: [PATCH (3rd try)] Add git-stash script

[しらいしななこ]

Quoting Johannes Schindelin <Johannes.Schindelin@gmx.de>:

> Hi,

Hello.

> On Sat, 30 Jun 2007, しらいしななこ wrote:
>
>> diff --git a/git-stash.sh b/git-stash.sh
>> [...]
>> +	printf >&2 'Saved WIP on %s\n' "$msg"
>
> You have an awful lot of printfs in the code. Why not just use echos?

I just imitated other scripts.  I can change it to

echo >&2 "Saved WIP on $msg"

but after reading Junio's comments, I think I probably should not.

>> +list_stash () {
>> +	git-log --pretty=oneline -g "$@" $ref_stash |
>
> Wouldn't you want "--default $ref_stash" here?

I do not know, and I'm sorry I do not understand Junio's comments.

What does --default do in this case?

>> +apply_stash () {
>> +	git-diff-files --quiet ||
>> +		die 'Cannot restore on top of a dirty state'
>
> You meant "no_changes", right? I think you miss changes in the index 
> otherwise.

After I read exchanges between you and Junio I do not know which way
is preferred.  Using no_changes does not forbid me from doing that,
but I think Junio's example will be forbidden.  The original scenario
was that I apply a stashed change to an unmodified state, and there is
no problem either way.

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

----------------------------------------------------------------------
Free pop3 email with a spam filter.
http://www.bluebottle.com

[PATCH] Add a manual page for git-stash

[Johannes Schindelin]

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 Documentation/git-stash.txt |  116 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 116 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/git-stash.txt

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
new file mode 100644
index 0000000..b109f6e
--- /dev/null
+++ b/Documentation/git-stash.txt
@@ -0,0 +1,116 @@
+git-stash(1)
+=============
+
+NAME
+----
+git-stash - Stash the changes in a dirty working directory away
+
+SYNOPSIS
+--------
+[verse]
+'git-stash' [clear]
+'git-stash' [list | show | apply] [<stashname>]
+
+DESCRIPTION
+-----------
+Use 'git stash' when you want to record the current state of the
+working directory and the index, but want to go back to a clean
+working directory.
+
+For example, if you have to pull, but are in the middle of some
+interesting work, not yet ready to be committed, use git-stash.
+
+The default operation (when called without options), is to save
+the changes away.
+
+
+OPTIONS
+-------
+clear::
+	Undo _all_ stashes (dangerous!).
+
+list [<stashname>]::
+	List all stashed states.
+
+show [<stashname>]::
+	Show a combined diff of the stashed working directory, index and
+	HEAD.
+
+apply [<stashname>]::
+	Try to apply the stashed changes to the current HEAD. You need
+	a clean working directory for that, i.e. you must not have changes
+	relative to HEAD in your working directory or index.
+
+<stashname>::
+	A name of a stashed state. Typically something like 'stash@{2}'
+	or 'stash@{2.days.ago}'.
+
+
+EXAMPLES
+--------
+
+Get to a clean working directory, quick:
+
+---------------------
+$ git stash
+---------------------
+
+See what you stashed:
+
+---------------------
+$ git stash list
+---------------------
+
+Inspect the last stashed state:
+
+---------------------
+$ git stash show
+---------------------
+
+Inspect the second last stashed state:
+
+--------------------------
+$ git stash show stash@{1}
+--------------------------
+
+Apply the second last stashed state:
+
+---------------------------
+$ git stash apply stash@{1}
+---------------------------
+
+
+DISCUSSION
+----------
+
+The state is saved as three commits:
+
+- HEAD,
+- a commit which contains the state of the index, which has HEAD as a
+  parent, and
+- a commit which contains the state of the working directory (only the
+  tracked files, though), which has both HEAD and the second commit
+  as parents.
+
+The third commit holds the complete information of the stash, and is
+stored as the ref 'refs/stash'.
+
+Since that commit does not have any reference to other stashed states,
+the stash listing relies on the reflog of 'refs/stash'. Therefore,
+the stashed states are garbage collected like all the other reflogs.
+
+
+SEE ALSO
+--------
+gitlink:git-commit[1],
+gitlink:git-log[1],
+gitlink:git-reflog[1]
+
+Author
+------
+Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>
+
+
+GIT
+---
+Part of the gitlink:git[7] suite
-- 
1.5.2.2.3249.g33841

Re: [PATCH] Add a manual page for git-stash

[Frank Lichtenheld]

On Sat, Jun 30, 2007 at 04:44:39PM +0100, Johannes Schindelin wrote:
> +Author
> +------
> +Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>

AFAICT "Author" is usually used for the author of the documented program
and "Documentation" for the author of the documentation itself.

Gruesse,
-- 
Frank Lichtenheld <frank@lichtenheld.de>
www: http://www.djpig.de/

Re: [PATCH] Add a manual page for git-stash

[Johannes Schindelin]

Hi,

On Sat, 30 Jun 2007, Frank Lichtenheld wrote:

> On Sat, Jun 30, 2007 at 04:44:39PM +0100, Johannes Schindelin wrote:
> > +Author
> > +------
> > +Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>
> 
> AFAICT "Author" is usually used for the author of the documented program
> and "Documentation" for the author of the documentation itself.

Oh? If that is so, please disregard this hunk.

Although in that case, git-bundle.txt is misattributed.

Ciao,
Dscho

Re: [PATCH] Add a manual page for git-stash

[Frank Lichtenheld]

On Sat, Jun 30, 2007 at 06:48:27PM +0100, Johannes Schindelin wrote:
> On Sat, 30 Jun 2007, Frank Lichtenheld wrote:
> > On Sat, Jun 30, 2007 at 04:44:39PM +0100, Johannes Schindelin wrote:
> > > +Author
> > > +------
> > > +Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>
> > 
> > AFAICT "Author" is usually used for the author of the documented program
> > and "Documentation" for the author of the documentation itself.
> 
> Oh? If that is so, please disregard this hunk.

Documentation$ grep -B2 -i "\(written\|documentation\) by" *.txt

seems to suggest that I'm right.

> Although in that case, git-bundle.txt is misattributed.

Indeed.

Gruesse,
-- 
Frank Lichtenheld <frank@lichtenheld.de>
www: http://www.djpig.de/

Re: [PATCH] Add a manual page for git-stash

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> +DESCRIPTION
> +-----------
> +Use 'git stash' when you want to record the current state of the
> +working directory and the index, but want to go back to a clean
> +working directory.
> +
> +For example, if you have to pull, but are in the middle of some
> +interesting work, not yet ready to be committed, use git-stash.
> +
> +The default operation (when called without options), is to save
> +the changes away.
> +
> +
> +OPTIONS
> +-------
> +clear::
> +	Undo _all_ stashes (dangerous!).
> +
> +list [<stashname>]::
> +	List all stashed states.
> +

I suspect that is not what the implementation intends to do.
"list -n 4", "list --since=1.hour" would make sense, but "list
stash@{12}" would probably not.

> +show [<stashname>]::
> +	Show a combined diff of the stashed working directory, index and
> +	HEAD.

Is that what it does?  I had an impression that "show stash@{2}"
shows a regular diff between the base and the stashed working
tree state.

> +apply [<stashname>]::
> +	Try to apply the stashed changes to the current HEAD. You need
> +	a clean working directory for that, i.e. you must not have changes
> +	relative to HEAD in your working directory or index.

The implementation appears to apply on a clean index without
restriction to where the HEAD is.  I hinted that that behaviour
is fine in my previous message, but on the other hand haven't
convinced myself enough to say that it would not confuse end
users.  Maybe insisting on not just clean index but no changes
from the HEAD would reduce confusion?  I dunno.

> +<stashname>::
> +	A name of a stashed state. Typically something like 'stash@{2}'
> +	or 'stash@{2.days.ago}'.

Probably this should be defined in DESCRIPTION, along with the
definition of what a stash is ("records the difference between
the HEAD when the stash was created and the working tree state
in such a way that it can be applied to a different state
later").

> +DISCUSSION
> +----------
> +
> +The state is saved as three commits:
> +
> +- HEAD,
> +- a commit which contains the state of the index, which has HEAD as a
> +  parent, and
> +- a commit which contains the state of the working directory (only the
> +  tracked files, though), which has both HEAD and the second commit
> +  as parents.
> +
> +The third commit holds the complete information of the stash, and is
> +stored as the ref 'refs/stash'.
> +
> +Since that commit does not have any reference to other stashed states,
> +the stash listing relies on the reflog of 'refs/stash'. Therefore,
> +the stashed states are garbage collected like all the other reflogs.

Nit; s/the other reflogs/the other reflog entries/

> +Author
> +------
> +Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>

You wrote that ;-)?

Re: [PATCH] Add a manual page for git-stash

[Johannes Schindelin]

Hi,

On Sat, 30 Jun 2007, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > +DESCRIPTION
> > +-----------
> > +Use 'git stash' when you want to record the current state of the
> > +working directory and the index, but want to go back to a clean
> > +working directory.
> > +
> > +For example, if you have to pull, but are in the middle of some
> > +interesting work, not yet ready to be committed, use git-stash.
> > +
> > +The default operation (when called without options), is to save
> > +the changes away.
> > +
> > +
> > +OPTIONS
> > +-------
> > +clear::
> > +	Undo _all_ stashes (dangerous!).
> > +
> > +list [<stashname>]::
> > +	List all stashed states.
> > +
> 
> I suspect that is not what the implementation intends to do.
> "list -n 4", "list --since=1.hour" would make sense, but "list
> stash@{12}" would probably not.

Okay, I misunderstood the _intention_ of the code, then.

> > +show [<stashname>]::
> > +	Show a combined diff of the stashed working directory, index and
> > +	HEAD.
> 
> Is that what it does?  I had an impression that "show stash@{2}"
> shows a regular diff between the base and the stashed working
> tree state.

Ah, you're completely right! Somehow my tired eyes read what I expected to 
find there.

> > +apply [<stashname>]::
> > +	Try to apply the stashed changes to the current HEAD. You need
> > +	a clean working directory for that, i.e. you must not have changes
> > +	relative to HEAD in your working directory or index.
> 
> The implementation appears to apply on a clean index without
> restriction to where the HEAD is.  I hinted that that behaviour
> is fine in my previous message, but on the other hand haven't
> convinced myself enough to say that it would not confuse end
> users.  Maybe insisting on not just clean index but no changes
> from the HEAD would reduce confusion?  I dunno.

I am sure confused why the index state is stashed away when it is not 
used...

> > +<stashname>::
> > +	A name of a stashed state. Typically something like 'stash@{2}'
> > +	or 'stash@{2.days.ago}'.
> 
> Probably this should be defined in DESCRIPTION, along with the
> definition of what a stash is ("records the difference between
> the HEAD when the stash was created and the working tree state
> in such a way that it can be applied to a different state
> later").

Okay.

> > +DISCUSSION
> > +----------
> > +
> > +The state is saved as three commits:
> > +
> > +- HEAD,
> > +- a commit which contains the state of the index, which has HEAD as a
> > +  parent, and
> > +- a commit which contains the state of the working directory (only the
> > +  tracked files, though), which has both HEAD and the second commit
> > +  as parents.
> > +
> > +The third commit holds the complete information of the stash, and is
> > +stored as the ref 'refs/stash'.
> > +
> > +Since that commit does not have any reference to other stashed states,
> > +the stash listing relies on the reflog of 'refs/stash'. Therefore,
> > +the stashed states are garbage collected like all the other reflogs.
> 
> Nit; s/the other reflogs/the other reflog entries/

Okay.

> > +Author
> > +------
> > +Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>
> 
> You wrote that ;-)?

No. ;-)

Hey, be nice. It's a new role for me, usually others document what _I_ 
wrote, not vice versa :-)

Ciao,
Dscho

Re: [PATCH] Add a manual page for git-stash

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

>> > +apply [<stashname>]::
>> > +	Try to apply the stashed changes to the current HEAD. You need
>> > +	a clean working directory for that, i.e. you must not have changes
>> > +	relative to HEAD in your working directory or index.
>> 
>> The implementation appears to apply on a clean index without
>> restriction to where the HEAD is.  I hinted that that behaviour
>> is fine in my previous message, but on the other hand haven't
>> convinced myself enough to say that it would not confuse end
>> users.  Maybe insisting on not just clean index but no changes
>> from the HEAD would reduce confusion?  I dunno.
>
> I am sure confused why the index state is stashed away when it is not 
> used...

Yeah, I think Nanako kept this from her previous round because I
mentioned that "git show stash" (not "git stash show") is
interesting in that it gives stashed (HEAD, index, working tree)
in --cc fashion.  I also mentioned that it might make sense to
stash untracked files in the working tree portion of the commit,
and if we do that then we would need to record what was known to
git by the index tree so that we can discard them from the index
upon applying, but (1) I no longer think it is useful to try
carrying forward the untracked file states, and (2) it would
make "git show stash" uninteresting (too much cruft).

So perhaps we would want to drop the index tree portion from the
stash.

>> > +Author
>> > +------
>> > +Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>
>> 
>> You wrote that ;-)?
>
> No. ;-)
>
> Hey, be nice. It's a new role for me, usually others document what _I_ 
> wrote, not vice versa :-)

Actually I have been wondering if it is a good idea to start
dropping the Author section.  Perhaps replace it by list of
stakeholders or people who have been active in the area recently
and who are likely to be able to help when an end-user has
troubles with the command.

Re: [PATCH] Add a manual page for git-stash

[Johannes Schindelin]

Hi,

On Sat, 30 Jun 2007, Junio C Hamano wrote:

> So perhaps we would want to drop the index tree portion from the stash.

That was actually the only reason I found it useful to write a script for 
it. Otherwise, the revised alias would do just fine.

Ciao,
Dscho

[PATCH] Document git-stash

[しらいしななこ]

This describes the git-stash command.

I borrowed a few paragraphs from Johannes's version, and added a few
examples.

Signed-off-by: Nanako Shiraishi <nanako3@bluebottle.com>
---
 Documentation/cmd-list.perl |    1 +
 Documentation/git-stash.txt |  162 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 163 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/git-stash.txt

diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index fcea1d7..8ee8122 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -178,6 +178,7 @@ git-show-ref                            plumbinginterrogators
 git-sh-setup                            purehelpers
 git-ssh-fetch                           synchingrepositories
 git-ssh-upload                          synchingrepositories
+git-stash                               mainporcelain
 git-status                              mainporcelain
 git-stripspace                          purehelpers
 git-submodule                           mainporcelain
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
new file mode 100644
index 0000000..17ebc83
--- /dev/null
+++ b/Documentation/git-stash.txt
@@ -0,0 +1,162 @@
+git-stash(1)
+============
+
+NAME
+----
+git-stash - Stash the changes in a dirty working directory away
+
+SYNOPSIS
+--------
+[verse]
+'git-stash'
+'git-stash' [list | show [<stash>] | apply [<stash>] | clear]
+
+DESCRIPTION
+-----------
+
+Use 'git-stash' when you want to record the current state of the
+working directory and the index, but want to go back to a clean
+working directory.  The command saves your local modifications away
+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`
+commands.  The default operation when called without options is to
+save the changes away.
+
+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
+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).
+
+OPTIONS
+-------
+
+(no subcommand)::
+
+	Save your local modifications to a new 'stash', and run `git-reset
+	--hard` to revert them.
+
+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 name of the branch that was current when the
+	stash was made, and a short description of the commit the stash was
+	based on.
++
+----------------------------------------------------------------
+stash@{0}: submit: 6ebd0e2... Add git-stash
+stash@{1}: master: 9cc0589... Merge branch 'master' of gfi
+----------------------------------------------------------------
+
+show [<stash>]::
+
+	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.
+
+apply [<stash>]::
+
+	Restores the changes recorded in the stash on top of the current
+	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).
+
+clear::
+	Removes all the stashed states.
+
+
+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
+the `HEAD` commit.  The ancestry graph looks like this:
+
+            .----W
+           /    /
+     ...--H----I
+
+where `H` is the `HEAD` commit, `I` is a commit that records the state
+of the index, and `W` is a commit that records the state of the working
+tree.
+
+
+EXAMPLES
+--------
+
+Pulling into a dirty tree::
+
+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.
++
+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:
++
+----------------------------------------------------------------
+$ git pull
+...
+file foobar not up to date, cannot merge.
+$ git stash
+$ git pull
+$ git stash apply
+----------------------------------------------------------------
+
+Interrupted workflow::
+
+When you are in the middle of something, your boss comes in and
+demands you to fix something immediately.  Traditionally, you would
+make a commit to a temporary branch to store your changes away, and
+come back to make the emergency fix, like this:
++
+----------------------------------------------------------------
+... hack hack hack ...
+$ git checkout -b my_wip
+$ git commit -a -m "WIP"
+$ git checkout master
+$ edit emergency fix
+$ git commit -a -m "Fix in a hurry"
+$ git checkout my_wip
+$ git reset --soft HEAD^
+... continue hacking ...
+----------------------------------------------------------------
++
+You can use `git-stash` to simplify the above, like this:
++
+----------------------------------------------------------------
+... hack hack hack ...
+$ git stash
+$ edit emergency fix
+$ git commit -a -m "Fix in a hurry"
+$ git stash apply
+... continue hacking ...
+----------------------------------------------------------------
+
+SEE ALSO
+--------
+gitlink:git-checkout[1],
+gitlink:git-commit[1],
+gitlink:git-reflog[1],
+gitlink:git-reset[1]
+
+AUTHOR
+------
+Written by Nanako Shiraishi <nanako3@bluebottle.com>
+
+GIT
+---
+Part of the gitlink:git[7] suite
-- 
1.5.2.2

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

----------------------------------------------------------------------
Get a free email account with anti spam protection.
http://www.bluebottle.com

Re: [PATCH] Document git-stash

[Junio C Hamano]

Thanks.

Re: [PATCH] Document git-stash

[Jeff King]

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

Re: [PATCH] Document git-stash

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> 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).

Although I sent out a Thanks already, I haven't even applied it
yet.  Language nits are very much appreciated in the
Documentation area.  Will take a look but it is getting late
here in California, so it has to wait for about 8 to 10 hours.

Re: [PATCH] Document git-stash

[しらいしななこ]

Hi,

Quoting Jeff King <peff@peff.net>:

>> +(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.

Johannes earlier asked for the same thing, and I think it is a good change.

>> +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.

I don't understand myself anymore, either (^_^;) I just tried to follow
Jnio's earlier suggestion in his message.  He said this.

| The three-way merge is done correctly here, and I would imagine
| the users would feel the UI quite natural _if_ this merge
| conflicts.  "git diff" would show only the conflicted paths
| (because the updates coming from the old working tree is placed
| in the index for cleanly merged paths), editing a conflicted
| file and "git add $that_path" would resolve.  That's exactly the
| same workflow for a conflicted merge.
|
| However, I think it is a bit counterintuitive to update the
| working tree change to the index if the merge did not conflict.
| It might be better to run an equivalent of "git reset", so that
| after "git save restore", the user can say "git diff" (not "git
| diff HEAD") to view the local changes.  Perhaps...

>> +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.

I see.  When I wrote it, I thought that saying "removes" was enough.  It
seemed obvious to me that you would lose it when you remove it.

Thanks for fixing my language.  I am not very good at writing English,
but you probably have already found it out (^_^;).

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

----------------------------------------------------------------------
Finally - A spam blocker that actually works.
http://www.bluebottle.com

Re: [PATCH] Document git-stash

[Jeff King]

On Sun, Jul 01, 2007 at 06:06:29PM +0900, しらいしななこ wrote:

> I don't understand myself anymore, either (^_^;) I just tried to follow
> Jnio's earlier suggestion in his message.  He said this.

OK, we will wait for Junio to clarify tomorrow. :)

> >> +	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.
> 
> I see.  When I wrote it, I thought that saying "removes" was enough.  It
> seemed obvious to me that you would lose it when you remove it.

It is "enough" in the sense that the meaning is clear, but in general it
is very hard to convince git to forget things, and I think that is a
feature. There are so few commands in git where you can "lose" data that
I think it is worth marking them with a big X.

Really, I don't see the need to use 'clear' in general. The reflog works
as a stack, so old stashes will get out of the "top 10" eventually
anyway. In the long run, they will be cleaned up by "git reflog expire"
(or indirectly by "git gc").

> Thanks for fixing my language.  I am not very good at writing English,
> but you probably have already found it out (^_^;).

Quite the contrary. If it had been very badly written, it would have
just been easier to rewrite it than to point out the few mistakes. :)

-Peff

Re: [PATCH] Document git-stash

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Sun, Jul 01, 2007 at 06:06:29PM +0900, しらいしななこ wrote:
>
>> I don't understand myself anymore, either (^_^;) I just tried to follow
>> Jnio's earlier suggestion in his message.  He said this.
>
> OK, we will wait for Junio to clarify tomorrow. :)

Jeez.  I tried to stay lazy and have all the work done by
somebody else (and taking the credit at the end, as I was
mentored by you-know-who ;-), but you guys managed to suck me
into this.

There are a few issues when you replay a stash on a state that
is different from the state the stash was created on.

Stash records the then-current HEAD, index and the working tree
(I'll call them H, I and W for brevity from now on).  Ideally,
we would want to have the difference between the resulting index
and working tree to be similar to the difference between I and
W.

Replaying the stash is done on a clean working tree.  That is,
we require that at least the index and working tree match (we
could also require that the index and HEAD match, but I do not
think it changes anything in this discussion).  And we apply the
change between H and W with three-way merge.

For paths that are cleanly merged with this three-way merge,
merge-recursive updates the working tree and the index.  That
means if you do "git diff", you would not see the local changes
that were carried forward would not be visible, and you would
need "git diff HEAD" to view them.  I found it confusing, and
that was the suggestion I sent was about.  Nana's "3rd try", which
I applied and pushed to 'next', addresses this issue by running
"read-tree --reset $c_tree" (where $c_tree is the contents of
the index before replaying the stash).

This is not ideal.  We would want to see "git diff" for such a
path show difference similar to difference between I and W.

There is a little glitch, though.  Such an operation can also be
done with a three-way merge (git-merge-file would most likely be
useful), but what would we do when this second merge conflicts?
If we insist on making the "git diff" output to match the diff
between I and W for the path, somebody needs to resolve the
conflict and put the result in the index, but if git-merge-file
couldn't, the user is left to do that.  I strongly suspect that
we would not want that aggravation (besides, the working tree
cannot be used anymore as it contains what we would want to
leave there as the result of unstashing).  The second best thing
is probably to leave the index as it was before the stash was
applied for such a path (in other words, for such a path, we
discard the difference between I and W, favoring to use W).

We could still attempt to carry the difference between I and W
for paths that the second merge cleanly resolves, but then "git
diff" will show full diff between H and W for some paths (that
is, the ones the second merge did not cleanly resolve) while
diff between I and W for others (the ones that resolved
cleanly).  That is not what the current code does, though.

I am hoping that the "best effort" would make it more convenient
to use, but I also suspect that it might make things more
confusing to the end user and certainly more difficult to explain.

So that's about the cleanly-merged case.

What we should do about the paths that the first merge (i.e. the
one that updates the working tree) does not resolve cleanly?  We
would want to keep the index the way merge-recursive left, for
conflicting paths at least.  We would have higher stages for
them, so that the user will not accidentally commit things that
have not been merged, and can use usual conflict resolution
techniques like "git diff" to view the combined diff between
three versions.

Re: [PATCH] Document git-stash

[Jeff King]

On Sun, Jul 01, 2007 at 02:39:56PM -0700, Junio C Hamano wrote:

> For paths that are cleanly merged with this three-way merge,
> merge-recursive updates the working tree and the index.  That
> means if you do "git diff", you would not see the local changes
> that were carried forward would not be visible, and you would
> need "git diff HEAD" to view them.  I found it confusing, and
> that was the suggestion I sent was about.  Nana's "3rd try", which
> I applied and pushed to 'next', addresses this issue by running
> "read-tree --reset $c_tree" (where $c_tree is the contents of
> the index before replaying the stash).
> 
> This is not ideal.  We would want to see "git diff" for such a
> path show difference similar to difference between I and W.

Ah, I get it now. Thanks for the explanation.

I see you gutted the confusing text from the manpage...I think what you
have now is conceptually much simpler, and it won't bite anyone unless
they are trying to do something clever with the index. In which case I
hope they will be able to use the description of how the stash is stored
to poke around.

-Peff

Re: [PATCH] Document git-stash

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

>> +(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 would further suggest that we _require_ 'git stash save' to
create a new one and perhaps make the non-subcommand case run
'git stash list'.  While I was trying the code out I
accidentally created a new stash when I did not mean to, which
pushed the stash I wanted to apply down in the list every time I
made such a mistake.

Re: [PATCH] Document git-stash

[Johannes Schindelin]

Hi,

On Sun, 1 Jul 2007, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> >> +(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 would further suggest that we _require_ 'git stash save' to
> create a new one and perhaps make the non-subcommand case run
> 'git stash list'.  While I was trying the code out I
> accidentally created a new stash when I did not mean to, which
> pushed the stash I wanted to apply down in the list every time I
> made such a mistake.

Well, the normal thing you want to do if you say "git stash" is best 
described by "Git, stash!".

However, unstash would by a nice feature. Not easy, but nice. Not easy, 
because we would be actively outsmarting the reflog machinery we use for 
the stash.

Ciao,
Dscho

Re: [PATCH] Document git-stash

[Jeff King]

On Sun, Jul 01, 2007 at 02:54:00PM -0700, Junio C Hamano wrote:

> I would further suggest that we _require_ 'git stash save' to
> create a new one and perhaps make the non-subcommand case run
> 'git stash list'.  While I was trying the code out I
> accidentally created a new stash when I did not mean to, which
> pushed the stash I wanted to apply down in the list every time I
> made such a mistake.

I think that makes sense...it's somehow cleaner to me if the
non-subcommand case doesn't make any changes (maybe just because I like
to explore commands by running them).

I see you have already applied this change. However, you missed a spot
in the documentation. Patch will follow, along with a couple of minor
cleanups for the script.

-Peff

Re: [PATCH] Document git-stash

[Johannes Schindelin]

Hi,

On Mon, 2 Jul 2007, Jeff King wrote:

> On Sun, Jul 01, 2007 at 02:54:00PM -0700, Junio C Hamano wrote:
> 
> > I would further suggest that we _require_ 'git stash save' to create a 
> > new one and perhaps make the non-subcommand case run 'git stash list'.  
> > While I was trying the code out I accidentally created a new stash 
> > when I did not mean to, which pushed the stash I wanted to apply down 
> > in the list every time I made such a mistake.
> 
> I think that makes sense...it's somehow cleaner to me if the 
> non-subcommand case doesn't make any changes (maybe just because I like 
> to explore commands by running them).

I disagree entirely.

The _only_ default subcommand for git-stash, which makes _any_ sense, is 
"save". I have run my own version of it several times, and it _literally_ 
was in those circumstances "hack, hack, hack, aargh, stash that, I'll need 
it later". "git cherry-pick stash" and "git reflog show stash" were needed 
far less.

I am utterly uninterested in the stash list.

Ciao,
Dscho

[PATCH] git-stash: Make "save" the default operation again

[Johannes Schindelin]

The default operation really should be that which you are most likely
to use. And that _is_ to stash the current changes away. Indeed, quite
often you will want it to stash away changes you never plan to commit,
like extensive debugging output.

Sometimes you will stash away changes that you realize only later will
never be needed.

So, neither "list" nor "apply" are ase often used in practice as "save".
The manpage already reflects that, so change the script to the better.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---

	Think about it again. You tested git-stash. That is not the normal 
	modus operandi. You needed to inspect the stashed changes. In the
	examples given in the manpage, you usually want to work with the
	last stashed changes, if at all. So you _rarely_ inspect the 
	stashed changes. From my experience I agree.

	If you make "list" the default, people will get used to _that_, 
	even if it means more typing, and quite a few "Aargh, I just 
	wanted to stash the current state, and I get a list instead!" 
	moments.

	Then there is no way to change it back to some sane default 
	operation.

 git-stash.sh |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/git-stash.sh b/git-stash.sh
index ec18ef6..04ce30a 100755
--- a/git-stash.sh
+++ b/git-stash.sh
@@ -132,7 +132,7 @@ apply_stash () {
 
 # Main command set
 case "$1" in
-list | '')
+list)
 	shift
 	if test $# = 0
 	then
@@ -152,7 +152,7 @@ apply)
 clear)
 	clear_stash
 	;;
-save)
+save|'')
 	save_stash && git-reset --hard
 	;;
 *)
-- 
1.5.2.2.3293.gad30

Re: [PATCH] git-stash: Make "save" the default operation again

[Jeff King]

On Mon, Jul 02, 2007 at 11:44:29AM +0100, Johannes Schindelin wrote:

> So, neither "list" nor "apply" are ase often used in practice as "save".
> The manpage already reflects that, so change the script to the better.

I have to admit that I don't really care all that much, so I'll let you
guys duke it out.

-Peff

Re: [PATCH] git-stash: Make "save" the default operation again

[Johannes Schindelin]

Hi,

On Mon, 2 Jul 2007, Jeff King wrote:

> On Mon, Jul 02, 2007 at 11:44:29AM +0100, Johannes Schindelin wrote:
> 
> > So, neither "list" nor "apply" are ase often used in practice as 
> > "save". The manpage already reflects that, so change the script to the 
> > better.
> 
> I have to admit that I don't really care all that much, so I'll let you 
> guys duke it out.

I do have to admit that I do care. Especially since my alias is no longer 
working (having the same name as a git program).

Ciao,
Dscho

Re: [PATCH] git-stash: Make "save" the default operation again

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

>> On Mon, Jul 02, 2007 at 11:44:29AM +0100, Johannes Schindelin wrote:
>> 
>> > So, neither "list" nor "apply" are ase often used in practice as 
>> > "save". The manpage already reflects that, so change the script to the 
>> > better.
>> 
>> I have to admit that I don't really care all that much, so I'll let you 
>> guys duke it out.
>
> I do have to admit that I do care. Especially since my alias is no longer 
> working (having the same name as a git program).

Ok, two votes from long-timer Dscho and original poster Nana are
sufficient for me to change my mind.

Thanks.

Re: [PATCH] Add a manual page for git-stash

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
> ---
>  Documentation/git-stash.txt |  116 +++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 116 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/git-stash.txt

By the way, whoever does the documentation needs to list it in
the command list (Documentation/cmd-list.perl).

[PATCH] Add tests for git-stash

[Johannes Schindelin]

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---

	In the current version of git-stash, the last test fails.
	Basically, it tests if different changes to the file "file"
	in the working directory and the index are reconstructed.
	They are not (index changes are not there), but I think they 
	should be.

 t/t3903-stash.sh |   55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 55 insertions(+), 0 deletions(-)
 create mode 100755 t/t3903-stash.sh

diff --git a/t/t3903-stash.sh b/t/t3903-stash.sh
new file mode 100755
index 0000000..6d42373
--- /dev/null
+++ b/t/t3903-stash.sh
@@ -0,0 +1,55 @@
+#!/bin/sh
+#
+# Copyright (c) 2007 Johannes E Schindelin
+#
+
+test_description='Test git-stash'
+
+. ./test-lib.sh
+
+test_expect_success 'stash some dirty working directory' '
+	echo 1 > file &&
+	git add file &&
+	test_tick &&
+	git commit -m initial &&
+	echo 2 > file &&
+	git add file &&
+	echo 3 > file &&
+	test_tick &&
+	git stash &&
+	git diff-files --quiet &&
+	git diff-index --cached --quiet HEAD
+'
+
+cat > expect << EOF
+diff --git a/file b/file
+index 0cfbf08..00750ed 100644
+--- a/file
++++ b/file
+@@ -1 +1 @@
+-2
++3
+EOF
+
+test_expect_success 'parents of stash' '
+	test $(git rev-parse stash^) = $(git rev-parse HEAD) &&
+	git diff stash^2..stash > output &&
+	diff -u output expect
+'
+
+test_expect_success 'apply needs clean working directory' '
+	echo 4 > other-file &&
+	git add other-file &&
+	! git stash apply
+'
+
+test_expect_success 'apply stashed changes' '
+	test_tick &&
+	git commit -m other-file &&
+	git stash apply &&
+	test 3 = $(cat file) &&
+	test 2 = $(git show :file) &&
+	test 1 = $(git show HEAD:file)
+'
+
+test_done
-- 
1.5.2.2.3249.g33841