git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: "Robert P. J. Day" <rpjday@crashcourse.ca>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: Git Mailing list <git@vger.kernel.org>
Subject: Re: [PATCH] doc: emphasize stash "--keep-index" stashes staged content
Date: Thu, 12 Oct 2017 03:16:10 -0400 (EDT)
Message-ID: <alpine.LFD.2.21.1710120257450.24121@localhost.localdomain> (raw)
In-Reply-To: <20171012041631.GC155740@aiede.mtv.corp.google.com>

On Wed, 11 Oct 2017, Jonathan Nieder wrote:

> Hi,
>
> Robert P. J. Day wrote:
>
> > It's not immediately obvious from the man page that the "--keep-index"
> > option still adds the staged content to the stash, so make that
> > abundantly clear.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> > ---
> >
> > diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> > index 00f95fee1..037144037 100644
> > --- a/Documentation/git-stash.txt
> > +++ b/Documentation/git-stash.txt
> > @@ -68,8 +68,8 @@ 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.
> >  +
> > -If the `--keep-index` option is used, all changes already added to the
> > -index are left intact.
> > +If the `--keep-index` option is used, all changes already staged in the
> > +index are left intact in the index, while still being added to the stash.
>
> Aside from Junio's note about "in the index" vs "in the working tree":

  yes, that was a good point, i will ponder further.

> The "Testing partial commits" item in the EXAMPLES section explains
> what --keep-index is useful for.  I wonder if some allusion to that
> would make the explanation in the OPTIONS section easier to
> understand.
>
> Something that I end up still curious about when reading this
> description is what will happen when I "git stash pop".  Will it
> apply only the changes that were stashed away and removed from the
> working tree, or will it apply the changes that were kept in the
> index, too? If the latter, why?  Is there some way I can turn that
> behavior off?

  at risk of embarrassing myself, it seems that the simplest way to
explain stashing WRT to those --keep-index and --index options is to
first explain that, regardless of --keep-index with push, stash will
*always* stash all of your changes in the working tree, and will
further distinguish between staged and unstaged content. that's based
on the diagram in the man page:

                  .----W
                 /    /
           -----H----I

so the initial explanation should be that the above *always* happens,
no matter what.

  the next sentence should then say, "if you add --keep-index, then
staged changes are preserved in the working tree and index", or
something like that. but the use of --keep-index does not (unless i'm
reading this incorrectly) in any way affect what is stashed, correct?

  in that same vein, the explanation should then go on to explain that
popping always restores the *entire* stash to the working tree -- all
of it -- and the use of "--index" simply means that the portion of
the stash representing what had been staged will be restaged.

  not to belabour the point, but i think it's important to emphasize
early that --keep-index and --index in no way affect what is stashed,
and what is popped, which i think is a common misunderstanding.

> E.g. in the "Testing partial commits" example, it seems like the
> natural behavior for "git stash pop" would be just restore the
> changes that were removed from the working tree.  That would also
> match an assumption of save/push and pop being symmetrical ('inverse
> operations').
>
> Is this related to "git stash pop --index"?  I notice that the
> EXAMPLES section doesn't give any examples of that option.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

      reply index

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-10-11  8:46 Robert P. J. Day
2017-10-12  0:38 ` Junio C Hamano
2017-10-12  4:16 ` Jonathan Nieder
2017-10-12  7:16   ` Robert P. J. Day [this message]

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=alpine.LFD.2.21.1710120257450.24121@localhost.localdomain \
    --to=rpjday@crashcourse.ca \
    --cc=git@vger.kernel.org \
    --cc=jrnieder@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

git@vger.kernel.org mailing list mirror (one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/
       or Tor2web: https://www.tor2web.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox