[PATCH v2 14/14] completion: update 'git reset' new stage options

[PATCH v2 14/14] completion: update 'git reset' new stage options

[Felipe Contreras]

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 contrib/completion/git-completion.bash | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 1dde51f..082f207 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -2231,7 +2231,8 @@ _git_reset ()
 
 	case "$cur" in
 	--*)
-		__gitcomp "--merge --mixed --hard --soft --patch"
+		__gitcomp "--merge --mixed --hard --soft --patch --keep --merge
+			--stage --no-stage --work --no-work"
 		return
 		;;
 	esac
-- 
1.8.4-fc

[PATCH v2 04/14] grep: add --staged option

[Felipe Contreras]

Synonym for --cached.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-grep.txt | 5 ++++-
 builtin/grep.c             | 2 ++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 8497aa4..9f7899c 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -25,7 +25,7 @@ SYNOPSIS
 	   [-W | --function-context]
 	   [-f <file>] [-e] <pattern>
 	   [--and|--or|--not|(|)|-e <pattern>...]
-	   [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>...]
+	   [ [--[no-]exclude-standard] [--cached | --staged | --no-index | --untracked] | <tree>...]
 	   [--] [<pathspec>...]
 
 DESCRIPTION
@@ -60,6 +60,9 @@ OPTIONS
 	Instead of searching tracked files in the working tree, search
 	blobs registered in the index file.
 
+--staged::
+	Synonym for `--cached`.
+
 --no-index::
 	Search files in the current directory that is not managed by Git.
 
diff --git a/builtin/grep.c b/builtin/grep.c
index d3b3b1d..b953911 100644
--- a/builtin/grep.c
+++ b/builtin/grep.c
@@ -640,6 +640,8 @@ int cmd_grep(int argc, const char **argv, const char *prefix)
 	struct option options[] = {
 		OPT_BOOLEAN(0, "cached", &cached,
 			N_("search in index instead of in the work tree")),
+		OPT_BOOLEAN(0, "staged", &cached,
+			N_("search in index instead of in the work tree")),
 		OPT_NEGBIT(0, "no-index", &use_index,
 			 N_("find in contents not managed by git"), 1),
 		OPT_BOOLEAN(0, "untracked", &untracked,
-- 
1.8.4-fc

[PATCH v2 07/14] stash: add --stage to pop and apply

[Felipe Contreras]

Synonym of --index.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-stash.txt | 8 ++++----
 git-stash.sh                | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 21a01c2..5fdaa35 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 'git stash' list [<options>]
 'git stash' show [<stash>]
 'git stash' drop [-q|--quiet] [<stash>]
-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
+'git stash' ( pop | apply ) [--index|--stage] [-q|--quiet] [<stash>]
 'git stash' branch <branchname> [<stash>]
 'git stash' [save [-p|--patch] [-k|--[no-]keep-index|--[no-]stage] [-q|--quiet]
 	     [-u|--include-untracked] [-a|--all] [<message>]]
@@ -96,7 +96,7 @@ show [<stash>]::
 	it will accept any format known to 'git diff' (e.g., `git stash show
 	-p stash@{1}` to view the second most recent stash in patch form).
 
-pop [--index] [-q|--quiet] [<stash>]::
+pop [--index|--stage] [-q|--quiet] [<stash>]::
 
 	Remove a single stashed state from the stash list and apply it
 	on top of the current working tree state, i.e., do the inverse
@@ -110,12 +110,12 @@ and call `git stash drop` manually afterwards.
 If the `--index` option is used, then tries to reinstate not only the working
 tree's changes, but also the index's ones. However, this can fail, when you
 have conflicts (which are stored in the index, where you therefore can no
-longer apply the changes as they were originally).
+longer apply the changes as they were originally). `--stage` is a synonym.
 +
 When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must
 be a reference of the form `stash@{<revision>}`.
 
-apply [--index] [-q|--quiet] [<stash>]::
+apply [--index|--stage] [-q|--quiet] [<stash>]::
 
 	Like `pop`, but do not remove the state from the stash list. Unlike `pop`,
 	`<stash>` may be any commit that looks like a commit created by
diff --git a/git-stash.sh b/git-stash.sh
index 47220d0..e2eb8dc 100755
--- a/git-stash.sh
+++ b/git-stash.sh
@@ -5,7 +5,7 @@ dashless=$(basename "$0" | sed -e 's/-/ /')
 USAGE="list [<options>]
    or: $dashless show [<stash>]
    or: $dashless drop [-q|--quiet] [<stash>]
-   or: $dashless ( pop | apply ) [--index] [-q|--quiet] [<stash>]
+   or: $dashless ( pop | apply ) [--index|--stage] [-q|--quiet] [<stash>]
    or: $dashless branch <branchname> [<stash>]
    or: $dashless [save [--patch] [-k|--[no-]keep-index|--[no-]stage] [-q|--quiet]
 		       [-u|--include-untracked] [-a|--all] [<message>]]
@@ -373,7 +373,7 @@ parse_flags_and_rev()
 			-q|--quiet)
 				GIT_QUIET=-t
 			;;
-			--index)
+			--index|--stage)
 				INDEX_OPTION=--index
 			;;
 			-*)
-- 
1.8.4-fc

[PATCH v2 00/14] Officially start moving to the term 'staging area'

[Felipe Contreras]

tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we should move
away from the name "the index".

It has been discussed many times in the past that 'index' is not an
appropriate description for what the high-level user does with it, and
it has been agreed that 'staging area' is the best term.

The term 'staging area' is more intuitive for newcomers which are more
familiar with English than with Git, and it seems to be a
straightforward mental notion for people with different mother tongues.

In fact it is so intuitive that it's used already in a lot online
documentation, and the people that do teach Git professionally use this
term, because it's easier for many kinds of audiences to grasp.

The meaning of the words 'cache' and 'index' doesn't represent correctly
the mental model of the high-level user:

cache: a 'cache' is a place for easier access; a squirrel caches nuts
so it doesn't have to go looking for them in the future when it might
be much more difficult. Git porcelain is not using the staging area
for easier future access; it's not a cache.

index: an 'index' is a guide of pointers to something else; a book
index has a list of entries so the reader can locate information
easily without having to go through the whole book. Git porcelain is
not using the staging area to find out entries quicker; it's not an
index.

stage: a 'stage' is a special area designated for convenience in order
for some activity to take place; an orator would prepare a stage in
order for her speak to be successful, otherwise many people might not
be able to hear, or see her. Git porcelain is using the staging area
precisely as a special area to be separated from the working directory
for convenience.

The term 'stage' is a good noun itself, but also 'staging area', it
has a good verb; 'to stage', and a nice past-participle; 'staged'.

The first step in moving Git towards this term, is first to add --stage
options for every command that uses --index or --cache. However, there's
a problem with the 'git apply' command, because it treats --index and
--cache differently. Different solutions were proposed, including a
special --stage-only option, however, I think the best solution is a
--[no-]work option to specify if the working directory should be touched
or not, so --index becomes --staged, and --cached becomes --staged
--no-work.

In addition, the 'git stage' command can be extended so the staging area
can be brought closer to the user, like other important Git concepts,
like 'git branch, 'git tag', and 'git remote'. For example, the command
'git stage edit' (which allows the user to edit directly the diff from
HEAD to the staging area) can have a home, where previously there was no
place. It would become natural then to do 'git stage diff', and then
'git stage edit' (to edit the previous diff).

After adding the new --stage options and making sure no functionality is
lost, they can become the recommended ones in the documentation,
eventually, the old ones get deprecated, and eventually obsoleted.

Also, the documentation would need to be updated to replace many
instances of 'the index', with 'the staging area' in porcelain commands.

Moreover, the --stage and --work options also make sense for 'git
reset', and after these options are added, the complicated table to
explain the different behaviors between --soft, --mixed, and --hard
becomes so simple it's not needed any more:

      working stage HEAD target             working stage HEAD
      ----------------------------------------------------
       A       B     C    D     --no-stage  A       B     D
				--stage     A       D     D
				--work      D       D     D

      working stage HEAD target             working stage HEAD
      ----------------------------------------------------
       A       B     C    C     --no-stage  A       B     C
				--stage     A       C     C
				--work      C       C     C

      working stage HEAD target             working stage HEAD
      ----------------------------------------------------
       B       B     C    D     --no-stage  B       B     D
				--stage     B       D     D
				--work      D       D     D

      working stage HEAD target             working stage HEAD
      ----------------------------------------------------
       B       B     C    C     --no-stage  B       B     C
				--stage     B       C     C
				--work      C       C     C

      working stage HEAD target             working stage HEAD
      ----------------------------------------------------
       B       C     C    D     --no-stage  B       C     D
				--stage     B       D     D
				--work      D       D     D

      working stage HEAD target             working stage HEAD
      ----------------------------------------------------
       B       C     C    C     --no-stage  B       C     C
				--stage     B       C     C
				--work      C       C     C

It might be possible to do 'git reset --no-stage --work', to reset the
working directory, but leave the staging area alone.

For more reference about the previous discussions:

http://thread.gmane.org/gmane.comp.version-control.git/197111
http://thread.gmane.org/gmane.comp.version-control.git/166675
http://thread.gmane.org/gmane.comp.version-control.git/115666

Changes since v1:

diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 6167061..95f5485 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -9,10 +9,10 @@ git-apply - Apply a patch to files and/or to the index
 SYNOPSIS
 --------
 [verse]
-'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--3way]
+'git apply' [--stat] [--numstat] [--summary] [--check] [--index|--stage] [--3way]
 	  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
 	  [--allow-binary-replacement | --binary] [--reject] [-z]
-	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached|--staged]
+	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
 	  [--ignore-space-change | --ignore-whitespace ]
 	  [--whitespace=(nowarn|warn|fix|error|error-all)]
 	  [--exclude=<path>] [--include=<path>] [--directory=<root>]
@@ -67,7 +67,7 @@ OPTIONS
 	up-to-date, it is flagged as an error.  This flag also
 	causes the index file to be updated.
 
---staged::
+--stage::
 	Synonym for --index.
 
 --cached::
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index b4066fd..5fdaa35 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -54,7 +54,7 @@ save [-p|--patch] [--[no-]keep-index|--[no-]stage] [-u|--include-untracked] [-a|
 	subcommand from making an unwanted stash.
 +
 If the `--keep-index` option is used, all changes already added to the
-index are left intact. Same with `--no-stage`, which is a snynonym.
+index are left intact. Same with `--no-stage`, which is a synonym.
 +
 If the `--include-untracked` option is used, all untracked files are also
 stashed and then cleaned up with `git clean`, leaving the working directory
diff --git a/builtin/stage.c b/builtin/stage.c
index d3c58d5..f537c1d 100644
--- a/builtin/stage.c
+++ b/builtin/stage.c
@@ -13,6 +13,7 @@
 static const char *const stage_usage[] = {
 	N_("git stage [options] [--] <paths>..."),
 	N_("git stage add [options] [--] <paths>..."),
+	N_("git stage apply [options] [<patch>...]"),
 	N_("git stage reset [-q|--patch] [--] <paths>..."),
 	N_("git stage diff [options] [<commit]> [--] <paths>..."),
 	N_("git stage rm [options] [--] <paths>..."),

Felipe Contreras (14):
  Add proper 'stage' command
  stage: add edit command
  diff: document --staged
  grep: add --staged option
  rm: add --staged option
  stash: add --stage option to save
  stash: add --stage to pop and apply
  submodule: add --staged options
  apply: add --stage option
  apply: add --work, --no-work options
  completion: update --staged options
  reset: add --stage and --work options
  reset: allow --keep with --stage
  completion: update 'git reset' new stage options

 Documentation/git-apply.txt            |  11 ++-
 Documentation/git-diff.txt             |   4 +-
 Documentation/git-grep.txt             |   5 +-
 Documentation/git-reset.txt            |   8 +++
 Documentation/git-rm.txt               |   5 +-
 Documentation/git-stage.txt            |  50 +++++++++++--
 Documentation/git-stash.txt            |  14 ++--
 Documentation/git-submodule.txt        |   8 ++-
 Makefile                               |   2 +-
 builtin.h                              |   1 +
 builtin/apply.c                        |   7 ++
 builtin/grep.c                         |   2 +
 builtin/reset.c                        |  27 +++++++
 builtin/rm.c                           |   1 +
 builtin/stage.c                        | 127 +++++++++++++++++++++++++++++++++
 contrib/completion/git-completion.bash |  39 ++++++++--
 git-stash.sh                           |  12 +++-
 git-submodule.sh                       |  10 +--
 git.c                                  |   2 +-
 19 files changed, 298 insertions(+), 37 deletions(-)
 create mode 100644 builtin/stage.c

-- 
1.8.4-fc

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Felipe Contreras]

On Mon, Oct 14, 2013 at 5:29 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we should move
> away from the name "the index".

Junio, can you make an exception and reply to this thread? The change
to move away from the term "the index" has been suggested many times
since many years ago, it is an extremely important change to users,
and all the Git developers agree it must be done.

Virtually everyone has agreed already that the term "staging area" is
the best option and this patch series is a good first step. Other than
the --work patches, this series could easily be merged to the 'pu'
branch. Yet not only is this series not there, but you haven't said
what needs to be done to get there.

It has been more than a month that I demonstrated to you that virtual
nobody has any problems with moving away from term "the index"[1][2],
and yet you haven't even responded.

I'm not even asking about this series, all I want to know is if any
change that tries to move away from the term "the index" towards
"staging area" would ever be considered for inclusion. Yes or no.

All I want is a simple answer to a simple question. Is that too much to ask?

[1] http://article.gmane.org/gmane.comp.version-control.git/233469
[2] http://article.gmane.org/gmane.comp.version-control.git/233468

-- 
Felipe Contreras

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> Junio, can you make an exception and reply to this thread? The change
> to move away from the term "the index" has been suggested many times
> since many years ago, it is an extremely important change to users,
> and all the Git developers agree it must be done.

"It must be done" is different from "any change is good, as long as
it introduces more instances of word 'stage'". As we established, we
do not seem to be able to do a sensible design discussion with you
without wasting time for nothing, I won't directly comment on that
patch series, at least for now.

However, since you asked, I would share a couple of comments
regarding the index, cache and staging area.

(1) "Staging area".

The phrase "staging area" is not an everyday phrase or common CS
lingo, and that unfortunately makes it a suboptimal choice of words
especially to those of us, to whom a large portion of their exposure
to the English language is through the command words we use when we
talk to our computers.

I personally do not mind explaining the index is "like a staging
area, where an army piles up ammunition to a temporary dump before
starting a major campaign." to native speakers, though ;-).

The index can also be thought of "like the buffer cache, where new
contents of files are kept before they are committed to disk
platter."  At least, non-native speaker with CS background would
understand that, much better than "the index" (no, I am not saying
that we should call it "the cache"; I am just saying "the index" is
not a good word, but we may need to find a better word than "the
staging area").

The noun phrase "staging area" and the verb "to stage" are good
(especially when we do not worry too much about us foreigners), but
we need to make sure "stage" is not mistaken as a noun when used in
a context that talks about the index as a whole, to avoid confusion
with the use of the word "stage" long established since

    http://thread.gmane.org/gmane.comp.version-control.git/231/focus=286

to call "ours" stage#2, etc.


(2) "cached" vs "index".

I think this is the more major issue between the two issues (the
other one being "why do we force people to say 'index'?").  Some
commands take "--cached", some others take "--index", some take
both.  What these two mean are documented in gitcli manual page, but
that is far from sufficient.  The users can get confused by this UI
mistake in different ways.

 * We do need to have "git apply" that mimics "patch" (i.e. works
   only to a working tree files, or even outside Git repository)
   without any option, "git apply --mode1" that only applies the
   change to the index, and "git apply --mode2" that applies the
   change to both the index and the working tree. No renaming of
   "the index" does not change this need to have three different
   mode of operation.

   It was a major UI mistake to call one of the modes "--cached" and
   another "--index", because there is no way, other than rote
   learning, for people to choose the one between the two depending
   that is right for the situation they face.

   If "--cached" were called "--index-only", it might have been a
   lot more learnable (and then "--index" could be renamed to
   "--index-and-working-tree" at the same time to reduce the
   confusion further).  Alternatively, with the synonym "--staged"
   for "--cached" already in place for "git diff", we could
   introduce "--staged-and-working-tree" as a synonym for "--index"
   to achieve the same effect (of course we need to find a way to
   shorten "-and-working-tree" part in a sensible way).

 * "git grep" barfs when given "--index", even though it does accept
   "--cached" and searches the patterns in contents that are in the
   index. This is technically correct, as the command does not
   search both in the index and in the working tree, but again,
   there is no way other than rote learning for users to tell that
   "--cached" is the correct one to use, even after they know that
   they want to search in the index (I already called it a major UI
   mistake, didn't I?).

   A new synonym "--staged" for "--cached" may be able to alleviate
   the confusion somewhat, given especially that "git diff" already
   knows "--staged" as a synonym for "--cached".  I think a better
   end result will come if we taught "git grep --index" to actually
   search the patterns both in the index and in the working tree at
   the same time.  There is no logical reason from the end user's
   point of view that "git grep --index" (aka "git grep
   --staged-and-working-tree") needs to fail; if we make the
   "--mode2" to mean to work on both the index and the working tree
   for any Git command when it makes sense, things will be more
   consistent, and it certainly makes sense to ask "git grep" to
   work on both the index and the working tree.  We do allow "git
   grep -e pattern tree-ish-1 tree-ish-2" to search in multiple data
   sources already, so it can be seen as a logical extension.

 * "git diff --index [TREE-ISH]" has exactly the same issue as "git
   grep", and the same conclusion, i.e. it may be worthwhile to
   teach "git diff --index [TREE-ISH]" to give combined diff between
   the given tree-ish (defaulting to HEAD as usual), the index and
   the working tree.

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Felipe Contreras]

Junio C Hamano wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > Junio, can you make an exception and reply to this thread? The change
> > to move away from the term "the index" has been suggested many times
> > since many years ago, it is an extremely important change to users,
> > and all the Git developers agree it must be done.
> 
> "It must be done" is different from "any change is good, as long as
> it introduces more instances of word 'stage'". As we established, we
> do not seem to be able to do a sensible design discussion with you
> without wasting time for nothing, I won't directly comment on that
> patch series, at least for now.
> 
> However, since you asked, I would share a couple of comments
> regarding the index, cache and staging area.
> 
> (1) "Staging area".
> 
> The phrase "staging area" is not an everyday phrase or common CS
> lingo, and that unfortunately makes it a suboptimal choice of words
> especially to those of us, to whom a large portion of their exposure
> to the English language is through the command words we use when we
> talk to our computers.

That's because Git is the only command tool that has such a concept.

> I personally do not mind explaining the index is "like a staging
> area, where an army piles up ammunition to a temporary dump before
> starting a major campaign." to native speakers, though ;-).

If you agree that explaining to users "the index is like a staging area", then
why just not call it the staging area?

Moreover, a staging area is not just a temporary dump, it is used in
preparation for something specific, and you might need to remove certain
weapons in place of better ones suited for the mission, that's why the word
"staging" is used.

> The index can also be thought of "like the buffer cache, where new
> contents of files are kept before they are committed to disk
> platter."

A buffer and a cache are two very different things used for two very different
purposes, and the term cache doesn't apply to "the index".

> At least, non-native speaker with CS background would understand that, much
> better than "the index" (no, I am not saying that we should call it "the
> cache"; I am just saying "the index" is not a good word, but we may need to
> find a better word than "the staging area").

All right, so that's progress; you do accept "the index" is not a good term.
Now, if you don't think "staging area" is a good term, do you have any that is
better?

This has been discussed for several years, and nobody has come up with a better
term, in fact, the vast majority of people prefer the term "staging area", and
it is already used in online documentation, including the ProGit book. It seems
inside and outside the Git project, the term has already been chosen.

Do you honestly think somebody is just suddenly going to come up with a better
term? How long do we have to wait before we decide X is the best term we could
come up with? One year? Two years? Ten years? Or do you just want to wait until
we have the "perfect" term, which might be never.

> The noun phrase "staging area" and the verb "to stage" are good
> (especially when we do not worry too much about us foreigners), but
> we need to make sure "stage" is not mistaken as a noun when used in
> a context that talks about the index as a whole, to avoid confusion
> with the use of the word "stage" long established since
> 
>     http://thread.gmane.org/gmane.comp.version-control.git/231/focus=286
> 
> to call "ours" stage#2, etc.

Lets assume that "staging area" is not the best option, even though after
years of discussion nobody has come up with a better one. How would a different
term solve the problem you state above? If we use the term "commit draft", we
still could have people saying "draft # 2". So is there any term that would
avoid this problem, and is it really important to worry about such a marginal
problem?

Regardless of the term used, we can make sure it's not used in that context, so
I don't understand how that argument goes against "staging area". We can make
sure "staging area" is not used to denote the different "index" files.

Is this the *only* argument you have against the term "staging area"?

> (2) "cached" vs "index".
> 
> I think this is the more major issue between the two issues (the
> other one being "why do we force people to say 'index'?").  Some
> commands take "--cached", some others take "--index", some take
> both.  What these two mean are documented in gitcli manual page, but
> that is far from sufficient.  The users can get confused by this UI
> mistake in different ways.
> 
>  * We do need to have "git apply" that mimics "patch" (i.e. works
>    only to a working tree files, or even outside Git repository)
>    without any option, "git apply --mode1" that only applies the
>    change to the index, and "git apply --mode2" that applies the
>    change to both the index and the working tree. No renaming of
>    "the index" does not change this need to have three different
>    mode of operation.
> 
>    It was a major UI mistake to call one of the modes "--cached" and
>    another "--index", because there is no way, other than rote
>    learning, for people to choose the one between the two depending
>    that is right for the situation they face.
> 
>    If "--cached" were called "--index-only", it might have been a
>    lot more learnable (and then "--index" could be renamed to
>    "--index-and-working-tree" at the same time to reduce the
>    confusion further).  Alternatively, with the synonym "--staged"
>    for "--cached" already in place for "git diff", we could
>    introduce "--staged-and-working-tree" as a synonym for "--index"
>    to achieve the same effect (of course we need to find a way to
>    shorten "-and-working-tree" part in a sensible way).

Or we can do what I already did to solve the problem:

  git apply --stage --working-tree

>  * "git grep" barfs when given "--index", even though it does accept
>    "--cached" and searches the patterns in contents that are in the
>    index. This is technically correct, as the command does not
>    search both in the index and in the working tree, but again,
>    there is no way other than rote learning for users to tell that
>    "--cached" is the correct one to use, even after they know that
>    they want to search in the index (I already called it a major UI
>    mistake, didn't I?).
> 
>    A new synonym "--staged" for "--cached" may be able to alleviate
>    the confusion somewhat, given especially that "git diff" already
>    knows "--staged" as a synonym for "--cached".  I think a better
>    end result will come if we taught "git grep --index" to actually
>    search the patterns both in the index and in the working tree at
>    the same time.  There is no logical reason from the end user's
>    point of view that "git grep --index" (aka "git grep
>    --staged-and-working-tree") needs to fail; if we make the
>    "--mode2" to mean to work on both the index and the working tree
>    for any Git command when it makes sense, things will be more
>    consistent, and it certainly makes sense to ask "git grep" to
>    work on both the index and the working tree.  We do allow "git
>    grep -e pattern tree-ish-1 tree-ish-2" to search in multiple data
>    sources already, so it can be seen as a logical extension.

  git grep --staged --working-tree

>  * "git diff --index [TREE-ISH]" has exactly the same issue as "git
>    grep", and the same conclusion, i.e. it may be worthwhile to
>    teach "git diff --index [TREE-ISH]" to give combined diff between
>    the given tree-ish (defaulting to HEAD as usual), the index and
>    the working tree.

  git diff --staged --working-tree

-- 
Felipe Contreras

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Matthieu Moy]

I'm lacking time to read and answer in detail, sorry.

Junio C Hamano <gitster@pobox.com> writes:

> "It must be done" is different from "any change is good, as long as
> it introduces more instances of word 'stage'".

I agree. Something must be done, at least to remove the cache Vs index
confusion. I'm not sure exactly what's best, and we should agree where
to go before going there. The previous attempts to introduce more
"stage" in Git's command-line (e.g. the "git stage" alias) introduced
more confusion than anything else.

> The phrase "staging area" is not an everyday phrase or common CS
> lingo, and that unfortunately makes it a suboptimal choice of words
> especially to those of us, to whom a large portion of their exposure
> to the English language is through the command words we use when we
> talk to our computers.

I do not think being understandable immediately by non-native is so
important actually. To me as a french, "commit" makes no sense as an
english word to describe what "git commit" does, but it's OK as I never
really translate it. Even fr.po translates "a commit" by "un commit".

That said, having something that immediately makes sense to a non-native
is obviously a good point.

Another proposal which I liked BTW was to use the word "precommit".
Short, and easily understood as the place where the next commit is
prepared.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[John Szakmeister]

On Fri, Oct 18, 2013 at 5:46 AM, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> I'm lacking time to read and answer in detail, sorry.
>
> Junio C Hamano <gitster@pobox.com> writes:
>
>> "It must be done" is different from "any change is good, as long as
>> it introduces more instances of word 'stage'".
>
> I agree. Something must be done, at least to remove the cache Vs index
> confusion. I'm not sure exactly what's best, and we should agree where
> to go before going there. The previous attempts to introduce more
> "stage" in Git's command-line (e.g. the "git stage" alias) introduced
> more confusion than anything else.

I definitely agree about removing the cache vs. index confusion.  I'm
curious about the confusions surrounding this "git stage" alias.  Was
it simply an implementation issue, or was it an issue surrounding the
name?

FWIW, I've trained my employees to think of it as a staging area as
well.  At least in English, it seems to be the best understood analogy
to the index's purpose.

>> The phrase "staging area" is not an everyday phrase or common CS
>> lingo, and that unfortunately makes it a suboptimal choice of words
>> especially to those of us, to whom a large portion of their exposure
>> to the English language is through the command words we use when we
>> talk to our computers.
>
> I do not think being understandable immediately by non-native is so
> important actually. To me as a french, "commit" makes no sense as an
> english word to describe what "git commit" does, but it's OK as I never
> really translate it. Even fr.po translates "a commit" by "un commit".
>
> That said, having something that immediately makes sense to a non-native
> is obviously a good point.
>
> Another proposal which I liked BTW was to use the word "precommit".
> Short, and easily understood as the place where the next commit is
> prepared.

I'm not sure what concept "precommit" invokes, but it's certainly not
where the next commit is prepared.  Two thoughts come to mind: the
precommit hook, and "what is a pre-commit?"  How would you talk about
preparing for a commit?  Do you "precommit a file?"  "Add the file to
the precommit?"  I'm just curious.

Thanks!

-John

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Felipe Contreras]

On Fri, Oct 18, 2013 at 4:46 AM, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> I'm lacking time to read and answer in detail, sorry.
>
> Junio C Hamano <gitster@pobox.com> writes:
>
>> "It must be done" is different from "any change is good, as long as
>> it introduces more instances of word 'stage'".
>
> I agree. Something must be done, at least to remove the cache Vs index
> confusion. I'm not sure exactly what's best, and we should agree where
> to go before going there.

I thought we already agreed "staging area" is the best term. Some
people don't, but that's expected.

>> The phrase "staging area" is not an everyday phrase or common CS
>> lingo, and that unfortunately makes it a suboptimal choice of words
>> especially to those of us, to whom a large portion of their exposure
>> to the English language is through the command words we use when we
>> talk to our computers.
>
> I do not think being understandable immediately by non-native is so
> important actually. To me as a french, "commit" makes no sense as an
> english word to describe what "git commit" does, but it's OK as I never
> really translate it. Even fr.po translates "a commit" by "un commit".

Indeed. Let's hope this red herring is not brought again.

> That said, having something that immediately makes sense to a non-native
> is obviously a good point.

Most non-native speakers, as most native speakers, already agreed the
term "staging area" is best.

> Another proposal which I liked BTW was to use the word "precommit".
> Short, and easily understood as the place where the next commit is
> prepared.

And that proposal has been argued against already[1][2].

To summarize:

1) It's not even an English word
2) Unlike "staging area", it's not widely used in external documentation already
3) There's no sensible verb: "to precommit"?

Moreover, in my mind a true precommit would have author, committer,
date; all the things you expect in a commit, except that it's not
permanent. A natural command that would derive from this concept is
'git commit --prepare', which would create an actual precommit.

But we are not looking to introduce yet another concept, we are
looking for a name of a concept we already have, and the majority of
users have already given it a name; the staging area.

[1] http://article.gmane.org/gmane.comp.version-control.git/197215
[2] http://article.gmane.org/gmane.comp.version-control.git/168201
-- 
Felipe Contreras

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Max Horn]

[-- Attachment #1: Type: text/plain, Size: 3641 bytes --]


On 17.10.2013, at 21:50, Junio C Hamano <gitster@pobox.com> wrote:

> Felipe Contreras <felipe.contreras@gmail.com> writes:

[...]

> 
> However, since you asked, I would share a couple of comments
> regarding the index, cache and staging area.
> 
> (1) "Staging area".
> 
> The phrase "staging area" is not an everyday phrase or common CS
> lingo, and that unfortunately makes it a suboptimal choice of words
> especially to those of us, to whom a large portion of their exposure
> to the English language is through the command words we use when we
> talk to our computers.

Interestingly, as a non-native speaker, I draw the exact reverse conclusion from this: While I had no idea what a "staging area" or "to stage" was (I did know the "stage" in a theater, though), I found this to not be a major problem: Using a dictionary and reading up on what it means in git made it clearly quickly enough.

To the contrary, the fact that the term was not yet overloaded with conflicting other meanings made it easier for me to attach the semantics git associates with it.

In contrast, "index" was exceedingly bad and confusing to me... I already had various notions of what an "index" is (e.g. the index of a book -- the same word actually exists in German; or more generally an index in computer science, as a kind of loopup table, etc.), and to this day, have a hard time consolidating this with the way git uses it. For me, it is yet another, seeming completely unrelated, meaning of the word "index" I had to memorize. Hey, just take a look at Wiki page <http://en.wikipedia.org/wiki/Index> for the many dozens of meanings associated to this word. Ugh. And worst of it, I am actually not quite sure on which of the meanings listed there "the index" as used by git is based... I.e. I don't even see a helpful analogy that would make it easier to understand the choice of name. 

In summary: For me as a non-native speaker, "index" feels like about the worst possible choice (well, you could have called it the "file" or "thing", that might have been worse ;-). While staging area turned out to be surprisingly good, *precisely* because I was unfamiliar with it. 

So, while "staging area" might not be perfect, it seems good enough to me. If this matter had indeed been discussed here for years, and no better suggestions has come up, then perhaps it is time to end the search for the (possibly non-existent) perfect solution, and instead do the pragmatic?


> The index can also be thought of "like the buffer cache, where new
> contents of files are kept before they are committed to disk
> platter."  At least, non-native speaker with CS background would
> understand that, much better than "the index" (no, I am not saying
> that we should call it "the cache"; I am just saying "the index" is
> not a good word, but we may need to find a better word than "the
> staging area").

Huh? As a non-native speaker with CS background, this actually leaves me more confused than I was before. I think about "the staging area", and I don't see how this is anything like an "index" (in any of the meaning I see on <http://en.wikipedia.org/wiki/Index>). I can vaguely recognize a faint similarity to a "cache", and yet more relation to a "buffer", but in the end, none of these strike me as particularly illustrative.

For that matter, I never really understood of why I had to do "git diff --cached", I simply learned it by rote. 

On the other hand, I feel that after understanding what the staging area is, then writing "git diff --staged" is very logical and simple to memorize.




Cheers,
Max

[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 235 bytes --]

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Karsten Blees]

Am 15.10.2013 00:29, schrieb Felipe Contreras:
> tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we should move
> away from the name "the index".
> 
> It has been discussed many times in the past that 'index' is not an
> appropriate description for what the high-level user does with it, and
> it has been agreed that 'staging area' is the best term.
> 

I haven't followed the previous discussion, but if a final conclusion towards 'staging area' has already been reached, it should probably be revised.

> The term 'staging area' is more intuitive for newcomers which are more
> familiar with English than with Git, and it seems to be a
> straightforward mental notion for people with different mother tongues.
> 
> In fact it is so intuitive that it's used already in a lot online
> documentation, and the people that do teach Git professionally use this
> term, because it's easier for many kinds of audiences to grasp.
> 

Such online documentation often portraits the 'staging area' as some supposedly 'unique' git feature, which I find _very_ confusing. In fact, every major SCM has a staging area. E.g. you first need to "svn/hg/bzr/p4 add/remove/rename/move" a file, which is somehow recorded in the working copy. These recorded changes will then be picked up by a subsequent "svn/hg/bzr/p4 commit/submit".

Additionally, all those systems support selectively committing individual files (by specifying the files on the commit command line or selecting them in a GUI).

So git's 'unique staging area' boils down to this:

1.) Recording individual files to commit in advance (instead of specifying them at commit time). Which isn't that hard to grasp.

2.) Recording individual diff hunks or even lines to commit. Which is an advanced feature that requires even more advanced commands to be useful (i.e. stash save --keep-index; make; test; commit; stash pop). It is also entirely irrelevant to binary files (i.e. for non-technical users that use git to track documents and stuff).

> index: an 'index' is a guide of pointers to something else; a book
> index has a list of entries so the reader can locate information
> easily without having to go through the whole book. Git porcelain is
> not using the staging area to find out entries quicker; it's not an
> index.
> 

The 'staging area' is a sorted list of most recently checked out files, and its primary purpose is to quickly detect changes in the working copy (i.e. its an index).

Of the 28 builtin main porcelain commands, 18 read the index (read_index), and 11 of those also check the state of the working copy (ie_match_stat). Incidentally, the latter include _all_ commands that update the so-called 'staging area'.

Subversion until recently kept the checked out files scattered in **/.svn/text-base directories, and many operations were terribly slow due to this. Subversion 1.7 introduced a new working copy format, based on a database in the root .svn directory (i.e. an index), leading to tremendous performance improvements.

The git index is a major feature that facilitates the incredible performance we're so much addicted to...why be shy about it and call it something else?

> stage: a 'stage' is a special area designated for convenience in order
> for some activity to take place; an orator would prepare a stage in
> order for her speak to be successful, otherwise many people might not
> be able to hear, or see her. Git porcelain is using the staging area
> precisely as a special area to be separated from the working directory
> for convenience.
> 

I'm not a native speaker, but in my limited understanding, 'staging' in computer jargon is the process of preparing data for a production system (i.e. until the 'stage' or 'state' of the data is ready for production). It has nothing to do with the 'stage' in a theater. I've never heard the term 'staging' beeing used for source code or software (that would be 'integration'). I've also never heard 'staging' for moving data back from a production system to some work- or development area.

In any sense, 'staging' is a unidirectional process (even in a theater). If I think of the index as a staging area, it covers just a single use case: preparing new commits. With this world view, it is completely counter-intuitive that e.g. changing branches overwrites my staging area.

IMO, it is ok to use 'like a staging area' when we talk about using the index to prepare new commits. However, its not ok to use 'staging area' as a general synonym for the index.

Just my 2 cents
Karsten

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Felipe Contreras]

Karsten Blees wrote:
> Am 15.10.2013 00:29, schrieb Felipe Contreras:
> > tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we should move
> > away from the name "the index".
> > 
> > It has been discussed many times in the past that 'index' is not an
> > appropriate description for what the high-level user does with it, and
> > it has been agreed that 'staging area' is the best term.
> 
> I haven't followed the previous discussion, but if a final conclusion towards
> 'staging area' has already been reached, it should probably be revised.
> 
> > The term 'staging area' is more intuitive for newcomers which are more
> > familiar with English than with Git, and it seems to be a
> > straightforward mental notion for people with different mother tongues.
> > 
> > In fact it is so intuitive that it's used already in a lot online
> > documentation, and the people that do teach Git professionally use this
> > term, because it's easier for many kinds of audiences to grasp.
> 
> Such online documentation often portraits the 'staging area' as some
> supposedly 'unique' git feature, which I find _very_ confusing. In fact,
> every major SCM has a staging area. E.g. you first need to "svn/hg/bzr/p4
> add/remove/rename/move" a file, which is somehow recorded in the working
> copy. These recorded changes will then be picked up by a subsequent
> "svn/hg/bzr/p4 commit/submit".

That is not a staging area.

  % hg init test
  % cd test
  % echo Hello > README
  % hg add README
  % echo Bye > README
  % hg commit -m Init
  % hg log -p -r -1
  changeset:   0:ba28df72474c
  tag:         tip
  user:        Felipe Contreras <felipe.contreras@gmail.com>
  date:        Fri Oct 18 19:43:42 2013 -0500
  summary:     Init

  diff -r 000000000000 -r ba28df72474c README
  --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
  +++ b/README	Fri Oct 18 19:43:42 2013 -0500
  @@ -0,0 +1,1 @@
  +Bye


What exactly got staged?

To me the best way to think about the staging area is like a commit draft. No
other VCS has anything like that. And what is the point about this argument?

> > index: an 'index' is a guide of pointers to something else; a book
> > index has a list of entries so the reader can locate information
> > easily without having to go through the whole book. Git porcelain is
> > not using the staging area to find out entries quicker; it's not an
> > index.
> 
> The 'staging area' is a sorted list of most recently checked out files, and
> its primary purpose is to quickly detect changes in the working copy (i.e.
> its an index).

That is not it's primary purpose.

> Of the 28 builtin main porcelain commands, 18 read the index (read_index),
> and 11 of those also check the state of the working copy (ie_match_stat).
> Incidentally, the latter include _all_ commands that update the so-called
> 'staging area'.
> 
> Subversion until recently kept the checked out files scattered in
> **/.svn/text-base directories, and many operations were terribly slow due to
> this. Subversion 1.7 introduced a new working copy format, based on a
> database in the root .svn directory (i.e. an index), leading to tremendous
> performance improvements.
> 
> The git index is a major feature that facilitates the incredible performance
> we're so much addicted to...why be shy about it and call it something else?

Tell me which subversion command adds and removes information from their
working copy metadata, which is not a used as a staging area, commit draft, or
even an index.

Moreover, we are not discussing about Git's index file, that low level concept
will stay the same, we are talking about the high level concept.

> > stage: a 'stage' is a special area designated for convenience in order
> > for some activity to take place; an orator would prepare a stage in
> > order for her speak to be successful, otherwise many people might not
> > be able to hear, or see her. Git porcelain is using the staging area
> > precisely as a special area to be separated from the working directory
> > for convenience.
> 
> I'm not a native speaker, but in my limited understanding, 'staging' in
> computer jargon is the process of preparing data for a production system
> (i.e. until the 'stage' or 'state' of the data is ready for production). It
> has nothing to do with the 'stage' in a theater.

It is the same. A stage in the theater is also used for preparing a production.

> I've never heard the term 'staging' beeing used for source code or software
> (that would be 'integration'). I've also never heard 'staging' for moving
> data back from a production system to some work- or development area.

Then why are people using it in external documentation? Why is ProGit already using it?

But more importantly: do you have a better name?

> In any sense, 'staging' is a unidirectional process (even in a theater).

It is not. Props and utilites are added and removed from the stage.

> If I think of the index as a staging area, it covers just a single use case:
> preparing new commits.

That is its main purpose.

> With this world view, it is completely counter-intuitive that e.g. changing
> branches overwrites my staging area.

Why would it do that? It's preparing the next commit, on top of which branch is
not defined yet.

> IMO, it is ok to use 'like a staging area' when we talk about using the index
> to prepare new commits.

Which is how it is being proposed; changing the name of the high-level concept.

> However, its not ok to use 'staging area' as a general synonym for the index.

Nobody is proposing that; the low-level "index file" stays the same.

-- 
Felipe Contreras

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Philip Oakley]

From: "Karsten Blees" <karsten.blees@gmail.com>
> Am 15.10.2013 00:29, schrieb Felipe Contreras:
>> tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we
>> should move
>> away from the name "the index".
>>
>> It has been discussed many times in the past that 'index' is not an
>> appropriate description for what the high-level user does with it,
>> and
>> it has been agreed that 'staging area' is the best term.
>>
>
> I haven't followed the previous discussion, but if a final conclusion
> towards 'staging area' has already been reached, it should probably be
> revised.

Do you mean that how that conclusion was reached should be summarised,
or that you don't think it's an appropriate summary of the broader
weltanschauung?

>
>> The term 'staging area' is more intuitive for newcomers which are
>> more
>> familiar with English than with Git, and it seems to be a
>> straightforward mental notion for people with different mother
>> tongues.
>>
>> In fact it is so intuitive that it's used already in a lot online
>> documentation, and the people that do teach Git professionally use
>> this
>> term, because it's easier for many kinds of audiences to grasp.
>>
>
> Such online documentation often portraits the 'staging area' as some
> supposedly 'unique' git feature, which I find _very_ confusing. In
> fact, every major SCM has a staging area. E.g. you first need to
> "svn/hg/bzr/p4 add/remove/rename/move" a file, which is somehow
> recorded in the working copy. These recorded changes will then be
> picked up by a subsequent "svn/hg/bzr/p4 commit/submit".
>
> Additionally, all those systems support selectively committing
> individual files (by specifying the files on the commit command line
> or selecting them in a GUI).
>
> So git's 'unique staging area' boils down to this:
>
> 1.) Recording individual files to commit in advance (instead of
> specifying them at commit time). Which isn't that hard to grasp.

For many, that separation of preparation(s), from the final action, is
brand new and difficult to appreciate - it's special to computer systems
(where copying is 100% reliable, essentially instantaneous, and in Git's
case, 100% verifiable via crypto checksums).

>
> 2.) Recording individual diff hunks or even lines to commit. Which is
> an advanced feature that requires even more advanced commands to be
> useful (i.e. stash save --keep-index; make; test; commit; stash pop).
> It is also entirely irrelevant to binary files (i.e. for non-technical
> users that use git to track documents and stuff).
>
>> index: an 'index' is a guide of pointers to something else; a book
>> index has a list of entries so the reader can locate information
>> easily without having to go through the whole book. Git porcelain is
>> not using the staging area to find out entries quicker; it's not an
>> index.
>>
>
> The 'staging area' is a sorted list of most recently checked out
> files, and its primary purpose is to quickly detect changes in the
> working copy (i.e. its an index).
>

There is a big (human) problem here. We (humans) are able to believe
contradictory things ("He ain't heavy, he's my brother" to quote a
song). The Index (file) isn't a staging area, but we are happy to flip
flop between the two ideas depending on context - others can feel
confused.

In one sense the "Index" is an implementation detail of the concept of a
packing area where a shipment (commit) is prepared, which is most
commonly called the staging are in populist discussions (which I believe 
is the summary I mentioned above)

> Of the 28 builtin main porcelain commands, 18 read the index
> (read_index), and 11 of those also check the state of the working copy
> (ie_match_stat). Incidentally, the latter include _all_ commands that
> update the so-called 'staging area'.
>
> Subversion until recently kept the checked out files scattered in
> **/.svn/text-base directories, and many operations were terribly slow
> due to this. Subversion 1.7 introduced a new working copy format,
> based on a database in the root .svn directory (i.e. an index),
> leading to tremendous performance improvements.
>
> The git index is a major feature that facilitates the incredible
> performance we're so much addicted to...why be shy about it and call
> it something else?
>
>> stage: a 'stage' is a special area designated for convenience in
>> order
>> for some activity to take place; an orator would prepare a stage in
>> order for her speak to be successful, otherwise many people might not
>> be able to hear, or see her. Git porcelain is using the staging area
>> precisely as a special area to be separated from the working
>> directory
>> for convenience.
>>
>
> I'm not a native speaker, but in my limited understanding, 'staging'
> in computer jargon is the process of preparing data for a production
> system (i.e. until the 'stage' or 'state' of the data is ready for
> production). It has nothing to do with the 'stage' in a theater. I've
> never heard the term 'staging' beeing used for source code or software
> (that would be 'integration'). I've also never heard 'staging' for
> moving data back from a production system to some work- or development
> area.

Even 'native' speakers don't have a single consistent term for the
concept. Terms are stolen from many varied industries and activities
that have to prepare and package items (Ships, Trains, Theaters)
(see http://en.wikipedia.org/wiki/Shipping_list, for a shortish list, 
which doesn't mention an Index)

>
> In any sense, 'staging' is a unidirectional process (even in a
> theater). If I think of the index as a staging area, it covers just a
> single use case: preparing new commits. With this world view, it is
> completely counter-intuitive that e.g. changing branches overwrites my
> staging area.
>
> IMO, it is ok to use 'like a staging area' when we talk about using
> the index to prepare new commits. However, its not ok to use 'staging
> area' as a general synonym for the index.

As alluded to above, the developer viewpoint includes a perception of
how we implement the preparation of commits, and how 'we' have come to
fix on the term 'index'.

In one sense even that is not the right term - If compared to a book /
pamphlet / monograph (being placed in a Library / repository)  it's more 
of a contents list (by chapter and verse / directory and file), with 
various bits of front matter such as author, publisher, previous 
editions, introductory preface, dates, contents list, and finally 
content. A book's 'index' is a supplementary mini grep of useful terms 
that the reader may wish to find.

All in all it's difficult to undo this Gordian knot of confusions.

>
> Just my 2 cents
> Karsten
>
The key is probably to separate the devlopers concerns over 
implementation details from the user's big picture view, in an arena 
that is short of well (commonly) understood terms.

Philip

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Karsten Blees]

Am 19.10.2013 16:08, schrieb Philip Oakley:
> From: "Karsten Blees" <karsten.blees@gmail.com>
>> Am 15.10.2013 00:29, schrieb Felipe Contreras:
>>> tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we
>>> should move
>>> away from the name "the index".
>>>
>>> It has been discussed many times in the past that 'index' is not an
>>> appropriate description for what the high-level user does with it,
>>> and
>>> it has been agreed that 'staging area' is the best term.
>>>
>>
>> I haven't followed the previous discussion, but if a final conclusion
>> towards 'staging area' has already been reached, it should probably be
>> revised.
> 
> Do you mean that how that conclusion was reached should be summarised,
> or that you don't think it's an appropriate summary of the broader
> weltanschauung?
> 

The latter. I don't know about 'broader', but I'll try to summarize _my_ world view:

(1) Audience matters

For actual users, we need an accurate model that supports a variety of use cases without falling apart. IMO, a working model is more important than simplicity. Finally, its more important to agree on the actual model than on a vague term that can mean many things (theater stage vs. loading dock...).

For potential users / decision makers, we need to describe git's features in unmistakable terms that don't need extra explanation. In this sense, the index / cache / staging area is not a feature in itself but facilitates a variaty of broader features:
- fine grained commit control (via index (add -i), but also commit -p, commit --amend, cherry-pick, rebase etc.)
- performance
- merging


(2) Index

An index, as in a library, maps almost perfectly to what the git index is _and_ what we do with it. No, I don't mean .so/.dll/.lib files, I'm talking about the real thing with shelves of books and a big box with index cards (aka the index).

The defining characteristic of a book (or publication in general) is its content, not its physical representation (paper). There are typically many indistinguishable copies of the same book. An author can continue working on the manuscript without affecting the copy at the library at all.

When a new or updated publication is submitted to the library, it is first added to the index and placed on a cart at the reception desk. Some time later, the librarian commits the content of the cart to the shelves. A user of the library will typically consult the index to lookup information or to check if his personal copy of a publication is up to date. The index can be thrown away and rebuilt from the content of the shelves. A big library may have a central repository and several local branches (aka field offices) that can be synchronized by comparing their indexes card by card.

Granted, a library is typically not versioned, and its unlikely that any one user will have checked out a full copy of the library's content. But otherwise, its pretty similar to git...


(3a) Staging area (logistics)

A staging area, as in (military) logistics / transportation, is about moving physical goods around. You move an item from your stock to the staging area, then onto the truck and finally deliver it to the customer.

The defining characteristic of a physical good is its physical existence. Each item is uniquely identifiable by a serial number. There may be many of the same kind, but there are no exact copies.

Problem #1: If an item in the staging area is broken, you fix it directly in the staging area, because that's where it _is_. Thus you also don't need to stage the item again. That's how conventional SCMs work: they track the identity (serial number, file name) of things.

Problem #2: The transportation model only supports additions. You cannot add an item to your staging area that, upon delivery, will magically remove itself from the possession of the customer. Let alone that you'd have to steal it first to be able to physically place it into your staging area.

This can be fixed by slightly modifying our mental model: instead of real things, lets think about "staging changes" (or deltas, or patches). Again, that's what conventional SCMs do and what git exactly does _not_ do.

Problem #3: In logistics, the state / inventory of the customer is irrelevant. If a customer orders an item he already has, its his problem. There's no need for core commands like status, diff or reset, and there's no way to explain what they do with a staging area model. What if a customer buys at another shop without telling us, effectively changing his inventory (git reset --soft)? This shouldn't affect our staging area at all, right? But with git it does...ooops.

(3b) Staging area (other meanings)

I don't see how a stage (as in a theater) is in any way related to the git index.

Data staging (as in loading a datawarehouse or web-server) fits to some extent, as its also about copying information, not moving physical things.

[...]
>>
>> 1.) Recording individual files to commit in advance (instead of
>> specifying them at commit time). Which isn't that hard to grasp.
> 
> For many, that separation of preparation(s), from the final action, is
> brand new and difficult to appreciate - it's special to computer systems
> (where copying is 100% reliable, essentially instantaneous, and in Git's
> case, 100% verifiable via crypto checksums).
> 

I'll try to remember that next time I write a shopping list... :-)

[...]
> Even 'native' speakers don't have a single consistent term for the
> concept. Terms are stolen from many varied industries and activities
> that have to prepare and package items (Ships, Trains, Theaters)
> (see http://en.wikipedia.org/wiki/Shipping_list, for a shortish list, which doesn't mention an Index)

All true, but we don't need to steal terms from unrelated fields if information science provides us with the terms we need.

[...]
> 
> In one sense even that is not the right term - If compared to a book /
> pamphlet / monograph (being placed in a Library / repository)  it's more of a contents list (by chapter and verse / directory and file), with various bits of front matter such as author, publisher, previous editions, introductory preface, dates, contents list, and finally content. A book's 'index' is a supplementary mini grep of useful terms that the reader may wish to find.
> 

Yes, a book's index is not the right meaning, as is stock market index or index finger. However, a library index seems to fit quite well.

By the same logic, I could argue that a file in git is not used as a tool to shape metal, therefore its not a file. Lets call it "costume", because a costume in a theater wraps an actor just like a file wraps content.</irony>

> All in all it's difficult to undo this Gordian knot of confusions.
> 
>>
>> Just my 2 cents
>> Karsten
>>
> The key is probably to separate the devlopers concerns over implementation details from the user's big picture view, in an arena that is short of well (commonly) understood terms.
> 

Yes, see my point about audience. Its probably also helpful to distinguish between unbiased SCM newbies and "braindamaged" VSS/CVS/SVN folks like me :-)

> Philip
> 

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Andreas Krey]

On Thu, 24 Oct 2013 02:57:15 +0000, Karsten Blees wrote:
...
> The latter. I don't know about 'broader', but I'll try to summarize _my_ world view:
> 
> (1) Audience matters
> 
> For actual users, we need an accurate model that supports a variety of use cases without falling apart. IMO, a working model is more important than simplicity. Finally, its more important to agree on the actual model than on a vague term that can mean many things (theater stage vs. loading dock...).

Terms almost invariable mean multiple things in different contexts,
and assume new meaning in new fields.

> For potential users / decision makers, we need to describe git's features in unmistakable terms that don't need extra explanation. In this sense, the index / cache / staging area is not a feature in itself but facilitates a variaty of broader features:
> - fine grained commit control (via index (add -i), but also commit -p, commit --amend, cherry-pick, rebase etc.)

The audience will have a hard time understanding what these features
actually do (and how they interact) if we hide the underlying model from
them - they then need to build that model themselves.

And no decision-maker will make the effort to understand either the
operations you mention or the concept of the staging area, unless they
are also users.

...
> An index, as in a library, maps almost perfectly to what the git index is _and_ what we do with it.

No, it doesn't. The git index actually contains the content of the added
files, not just an identity reference. (Unless, maybe, you consider file
sha1s as a reference and not actual content.) The point is that the
index doesn't just contain a mapping from file names to some objects,
but de facto a tree - that will form the next commit.

...
> (3a) Staging area (logistics)
> 
> A staging area, as in (military) logistics / transportation, is about moving physical goods around. You move an item from your stock to the staging area, then onto the truck and finally deliver it to the customer.
> 
> The defining characteristic of a physical good is its physical existence. Each item is uniquely identifiable by a serial number.

Please show me the serial numbers on bullets.

> Problem #1: If an item in the staging area is broken, you fix it directly in the staging area, because that's where it _is_.

That may be true in a physical world, and may not be - you can as well
replace them instead of repairing them in place.

The real problem: You can find some reason why any possible existing
name for this concept isn't correct.

...
> I don't see how a stage (as in a theater) is in any way related to the git index.

It's because the name 'stage (noun)' goes with the verb 'stage'. You
stage a play, or you stage content to be committed. From that, you
may almost call the index just 'stage'.

Andreas

-- 
"Totally trivial. Famous last words."
From: Linus Torvalds <torvalds@*.org>
Date: Fri, 22 Jan 2010 07:29:21 -0800

Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

[Felipe Contreras]

Karsten Blees wrote:
> (2) Index
> 
> An index, as in a library, maps almost perfectly to what the git index is
> _and_ what we do with it.

Not really. An index in the context of a library, and in any other context, is
a tool that indicates where something is, in order to find it quickly.

That is not how the Git index is used, nor what it is.

> (3b) Staging area (other meanings)
> 
> I don't see how a stage (as in a theater) is in any way related to the git
> index.
> 
> Data staging (as in loading a datawarehouse or web-server) fits to some
> extent, as its also about copying information, not moving physical things.

A stage in theater, and in any other context, is a special place, a standing
place, I don't see what is so different from the git staging area.

> > Even 'native' speakers don't have a single consistent term for the
> > concept. Terms are stolen from many varied industries and activities
> > that have to prepare and package items (Ships, Trains, Theaters)
> > (see http://en.wikipedia.org/wiki/Shipping_list, for a shortish list, which doesn't mention an Index)
> 
> All true, but we don't need to steal terms from unrelated fields if
> information science provides us with the terms we need.

But it doesn't.

-- 
Felipe Contreras

[PATCH v2 10/14] apply: add --work, --no-work options

[Felipe Contreras]

'git apply', 'git apply --index', 'git apply --cached' do different
things, but what they do is not precisely clear, specially since no
other commands has similar distinctions.

With --no-work (--work being the default), it's clear what the option
would do; modify, or not, the working directory.

So, --work (the default), doesn't cause any changes, and --no-work
enables the current --cache if used with --index.

Eventually --work might replace --cache, if these options are
standarized in the whole git toolset.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-apply.txt | 6 +++++-
 builtin/apply.c             | 5 +++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 8c047ef..95f5485 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -16,7 +16,7 @@ SYNOPSIS
 	  [--ignore-space-change | --ignore-whitespace ]
 	  [--whitespace=(nowarn|warn|fix|error|error-all)]
 	  [--exclude=<path>] [--include=<path>] [--directory=<root>]
-	  [--verbose] [<patch>...]
+	  [--verbose] [--no-work] [<patch>...]
 
 DESCRIPTION
 -----------
@@ -75,6 +75,10 @@ OPTIONS
 	cached data, apply the patch, and store the result in the index
 	without using the working tree. This implies `--index`.
 
+--[no-]work::
+	Apply a patch with or without touching the working tree, essentially
+	`--no-work` plus `--index` are the equivalent of `--cached`.
+
 -3::
 --3way::
 	When the patch does not apply cleanly, fall back on 3-way merge if
diff --git a/builtin/apply.c b/builtin/apply.c
index 42b5a4b..a3dd89d 100644
--- a/builtin/apply.c
+++ b/builtin/apply.c
@@ -4350,6 +4350,7 @@ int cmd_apply(int argc, const char **argv, const char *prefix_)
 	int errs = 0;
 	int is_not_gitdir = !startup_info->have_repository;
 	int force_apply = 0;
+	int work = 1;
 
 	const char *whitespace_option = NULL;
 
@@ -4381,6 +4382,8 @@ int cmd_apply(int argc, const char **argv, const char *prefix_)
 			N_("make sure the patch is applicable to the current index")),
 		OPT_BOOLEAN(0, "cached", &cached,
 			N_("apply a patch without touching the working tree")),
+		OPT_BOOLEAN(0, "work", &work,
+			N_("modify the working tree")),
 		OPT_BOOLEAN(0, "apply", &force_apply,
 			N_("also apply the patch (use with --stat/--summary/--check)")),
 		OPT_BOOL('3', "3way", &threeway,
@@ -4433,6 +4436,8 @@ int cmd_apply(int argc, const char **argv, const char *prefix_)
 	argc = parse_options(argc, argv, prefix, builtin_apply_options,
 			apply_usage, 0);
 
+	if (check_index && !work)
+		cached = 1;
 	if (apply_with_reject && threeway)
 		die("--reject and --3way cannot be used together.");
 	if (cached && threeway)
-- 
1.8.4-fc

[PATCH v2 01/14] Add proper 'stage' command

[Felipe Contreras]

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-stage.txt            | 45 +++++++++++++++++++++++++----
 Makefile                               |  2 +-
 builtin.h                              |  1 +
 builtin/stage.c                        | 52 ++++++++++++++++++++++++++++++++++
 contrib/completion/git-completion.bash | 24 +++++++++++++++-
 git.c                                  |  2 +-
 6 files changed, 118 insertions(+), 8 deletions(-)
 create mode 100644 builtin/stage.c

diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt
index ba3fe0d..318bf45 100644
--- a/Documentation/git-stage.txt
+++ b/Documentation/git-stage.txt
@@ -3,20 +3,55 @@ git-stage(1)
 
 NAME
 ----
-git-stage - Add file contents to the staging area
+git-stage - manage the staging area
 
 
 SYNOPSIS
 --------
 [verse]
-'git stage' args...
-
+'git stage' [options] [--] [<paths>...]
+'git stage add' [options] [--] [<paths>...]
+'git stage reset' [-q|--patch] [--] [<paths>...]
+'git stage diff' [options] [<commit>] [--] [<paths>...]
+'git stage rm' [options] [--] [<paths>...]
+'git stage apply' [options] [--] [<paths>...]
 
 DESCRIPTION
 -----------
 
-This is a synonym for linkgit:git-add[1].  Please refer to the
-documentation of that command.
+
+COMMANDS
+--------
+
+With no arguments, it's a synonym for linkgit:git-add[1].
+
+'add'::
+
+Adds file contents to the staging area. See linkgit:git-add[1].
+
+'reset'::
+
+Resets the staging area. See linkgit:git-reset[1].
+
+'diff'::
+
+View the changes you staged for the next commit. See linkgit:git-diff[1] --staged.
+
+'rm'::
+
+Remove files from the staging area only. See linkgit:git-rm[1] --staged.
+
+'apply'::
+
+Apply a patch to the staging area. See linkgit:git-rm[1] --staged.
+
+SEE ALSO
+--------
+linkgit:git-add[1]
+linkgit:git-reset[1]
+linkgit:git-diff[1]
+linkgit:git-rm[1]
+linkgit:git-apply[1]
 
 GIT
 ---
diff --git a/Makefile b/Makefile
index 3588ca1..1f7ddf3 100644
--- a/Makefile
+++ b/Makefile
@@ -598,7 +598,6 @@ BUILT_INS += git-merge-subtree$X
 BUILT_INS += git-peek-remote$X
 BUILT_INS += git-repo-config$X
 BUILT_INS += git-show$X
-BUILT_INS += git-stage$X
 BUILT_INS += git-status$X
 BUILT_INS += git-whatchanged$X
 
@@ -982,6 +981,7 @@ BUILTIN_OBJS += builtin/send-pack.o
 BUILTIN_OBJS += builtin/shortlog.o
 BUILTIN_OBJS += builtin/show-branch.o
 BUILTIN_OBJS += builtin/show-ref.o
+BUILTIN_OBJS += builtin/stage.o
 BUILTIN_OBJS += builtin/stripspace.o
 BUILTIN_OBJS += builtin/symbolic-ref.o
 BUILTIN_OBJS += builtin/tag.o
diff --git a/builtin.h b/builtin.h
index 8afa2de..baf3a0f 100644
--- a/builtin.h
+++ b/builtin.h
@@ -113,6 +113,7 @@ extern int cmd_send_pack(int argc, const char **argv, const char *prefix);
 extern int cmd_shortlog(int argc, const char **argv, const char *prefix);
 extern int cmd_show(int argc, const char **argv, const char *prefix);
 extern int cmd_show_branch(int argc, const char **argv, const char *prefix);
+extern int cmd_stage(int argc, const char **argv, const char *prefix);
 extern int cmd_status(int argc, const char **argv, const char *prefix);
 extern int cmd_stripspace(int argc, const char **argv, const char *prefix);
 extern int cmd_symbolic_ref(int argc, const char **argv, const char *prefix);
diff --git a/builtin/stage.c b/builtin/stage.c
new file mode 100644
index 0000000..3023d17
--- /dev/null
+++ b/builtin/stage.c
@@ -0,0 +1,52 @@
+/*
+ * 'git stage' builtin command
+ *
+ * Copyright (C) 2013 Felipe Contreras
+ */
+
+#include "builtin.h"
+#include "parse-options.h"
+
+static const char *const stage_usage[] = {
+	N_("git stage [options] [--] <paths>..."),
+	N_("git stage add [options] [--] <paths>..."),
+	N_("git stage reset [-q|--patch] [--] <paths>..."),
+	N_("git stage diff [options] [<commit]> [--] <paths>..."),
+	N_("git stage rm [options] [--] <paths>..."),
+	NULL
+};
+
+int cmd_stage(int argc, const char **argv, const char *prefix)
+{
+	struct option options[] = { OPT_END() };
+
+	argc = parse_options(argc, argv, prefix, options, stage_usage,
+			PARSE_OPT_KEEP_ARGV0 | PARSE_OPT_KEEP_UNKNOWN | PARSE_OPT_KEEP_DASHDASH);
+
+	if (argc > 1) {
+		if (!strcmp(argv[1], "add"))
+			return cmd_add(argc - 1, argv + 1, prefix);
+		if (!strcmp(argv[1], "reset"))
+			return cmd_reset(argc - 1, argv + 1, prefix);
+		if (!strcmp(argv[1], "diff")) {
+			argv[0] = "diff";
+			argv[1] = "--staged";
+
+			return cmd_diff(argc, argv, prefix);
+		}
+		if (!strcmp(argv[1], "rm")) {
+			argv[0] = "rm";
+			argv[1] = "--cached";
+
+			return cmd_rm(argc, argv, prefix);
+		}
+		if (!strcmp(argv[1], "apply")) {
+			argv[0] = "apply";
+			argv[1] = "--cached";
+
+			return cmd_apply(argc, argv, prefix);
+		}
+	}
+
+	return cmd_add(argc, argv, prefix);
+}
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 5da920e..8cf26e2 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1691,7 +1691,29 @@ _git_send_email ()
 
 _git_stage ()
 {
-	_git_add
+	__git_has_doubledash && return
+
+	local subcommands="add reset diff rm apply"
+	local subcommand="$(__git_find_on_cmdline "$subcommands")"
+	if [ -z "$subcommand" ]; then
+		__gitcomp "$subcommands"
+		return
+	fi
+
+	case "$subcommand" in
+	add)
+		_git_add;;
+	reset)
+		_git_reset;;
+	diff)
+		_git_diff;;
+	rm)
+		_git_rm;;
+	apply)
+		_git_apply;;
+	*)
+		_git_add;
+	esac
 }
 
 __git_config_get_set_variables ()
diff --git a/git.c b/git.c
index 2025f77..0e639aa 100644
--- a/git.c
+++ b/git.c
@@ -409,7 +409,7 @@ static void handle_internal_command(int argc, const char **argv)
 		{ "show", cmd_show, RUN_SETUP },
 		{ "show-branch", cmd_show_branch, RUN_SETUP },
 		{ "show-ref", cmd_show_ref, RUN_SETUP },
-		{ "stage", cmd_add, RUN_SETUP | NEED_WORK_TREE },
+		{ "stage", cmd_stage, RUN_SETUP | NEED_WORK_TREE },
 		{ "status", cmd_status, RUN_SETUP | NEED_WORK_TREE },
 		{ "stripspace", cmd_stripspace },
 		{ "symbolic-ref", cmd_symbolic_ref, RUN_SETUP },
-- 
1.8.4-fc

Re: [PATCH v2 01/14] Add proper 'stage' command

[Eric Sunshine]

On Mon, Oct 14, 2013 at 6:29 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> diff --git a/builtin/stage.c b/builtin/stage.c
> new file mode 100644
> index 0000000..3023d17
> --- /dev/null
> +++ b/builtin/stage.c
> @@ -0,0 +1,52 @@
> +/*
> + * 'git stage' builtin command
> + *
> + * Copyright (C) 2013 Felipe Contreras
> + */
> +
> +#include "builtin.h"
> +#include "parse-options.h"
> +
> +static const char *const stage_usage[] = {
> +       N_("git stage [options] [--] <paths>..."),
> +       N_("git stage add [options] [--] <paths>..."),
> +       N_("git stage reset [-q|--patch] [--] <paths>..."),
> +       N_("git stage diff [options] [<commit]> [--] <paths>..."),
> +       N_("git stage rm [options] [--] <paths>..."),
> +       NULL
> +};

Sent the wrong set of patches? The interdiff in the cover letter
showed usage for "git stage apply", but it's not here in the actual
patch.

Re: [PATCH v2 01/14] Add proper 'stage' command

[Felipe Contreras]

On Mon, Oct 14, 2013 at 6:06 PM, Eric Sunshine <sunshine@sunshineco.com> wrote:
> On Mon, Oct 14, 2013 at 6:29 PM, Felipe Contreras
> <felipe.contreras@gmail.com> wrote:
>> diff --git a/builtin/stage.c b/builtin/stage.c
>> new file mode 100644
>> index 0000000..3023d17
>> --- /dev/null
>> +++ b/builtin/stage.c
>> @@ -0,0 +1,52 @@
>> +/*
>> + * 'git stage' builtin command
>> + *
>> + * Copyright (C) 2013 Felipe Contreras
>> + */
>> +
>> +#include "builtin.h"
>> +#include "parse-options.h"
>> +
>> +static const char *const stage_usage[] = {
>> +       N_("git stage [options] [--] <paths>..."),
>> +       N_("git stage add [options] [--] <paths>..."),
>> +       N_("git stage reset [-q|--patch] [--] <paths>..."),
>> +       N_("git stage diff [options] [<commit]> [--] <paths>..."),
>> +       N_("git stage rm [options] [--] <paths>..."),
>> +       NULL
>> +};
>
> Sent the wrong set of patches? The interdiff in the cover letter
> showed usage for "git stage apply", but it's not here in the actual
> patch.

No, it's the right series, but apparently I added the change to the
wrong commit: stage: add edit command. I've fixed that and will send
it on the next reroll (if there's any).

-- 
Felipe Contreras

[PATCH v2 09/14] apply: add --stage option

[Felipe Contreras]

Synonym for --index.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-apply.txt | 5 ++++-
 builtin/apply.c             | 2 ++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index f605327..8c047ef 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -9,7 +9,7 @@ git-apply - Apply a patch to files and/or to the index
 SYNOPSIS
 --------
 [verse]
-'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--3way]
+'git apply' [--stat] [--numstat] [--summary] [--check] [--index|--stage] [--3way]
 	  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
 	  [--allow-binary-replacement | --binary] [--reject] [-z]
 	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
@@ -67,6 +67,9 @@ OPTIONS
 	up-to-date, it is flagged as an error.  This flag also
 	causes the index file to be updated.
 
+--stage::
+	Synonym for --index.
+
 --cached::
 	Apply a patch without touching the working tree. Instead take the
 	cached data, apply the patch, and store the result in the index
diff --git a/builtin/apply.c b/builtin/apply.c
index 50912c9..42b5a4b 100644
--- a/builtin/apply.c
+++ b/builtin/apply.c
@@ -4377,6 +4377,8 @@ int cmd_apply(int argc, const char **argv, const char *prefix_)
 			N_("instead of applying the patch, see if the patch is applicable")),
 		OPT_BOOLEAN(0, "index", &check_index,
 			N_("make sure the patch is applicable to the current index")),
+		OPT_BOOLEAN(0, "stage", &check_index,
+			N_("make sure the patch is applicable to the current index")),
 		OPT_BOOLEAN(0, "cached", &cached,
 			N_("apply a patch without touching the working tree")),
 		OPT_BOOLEAN(0, "apply", &force_apply,
-- 
1.8.4-fc

[PATCH v2 03/14] diff: document --staged

[Felipe Contreras]

Synonym for --cached.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-diff.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 78d6d50..646e5cd 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git diff' [options] [<commit>] [--] [<path>...]
-'git diff' [options] --cached [<commit>] [--] [<path>...]
+'git diff' [options] [--cached|--staged] [<commit>] [--] [<path>...]
 'git diff' [options] <commit> <commit> [--] [<path>...]
 'git diff' [options] <blob> <blob>
 'git diff' [options] [--no-index] [--] <path> <path>
@@ -33,7 +33,7 @@ If exactly two paths are given and at least one points outside
 the current repository, 'git diff' will compare the two files /
 directories. This behavior can be forced by --no-index.
 
-'git diff' [--options] --cached [<commit>] [--] [<path>...]::
+'git diff' [--options] [--cached|--staged] [<commit>] [--] [<path>...]::
 
 	This form is to view the changes you staged for the next
 	commit relative to the named <commit>.  Typically you
-- 
1.8.4-fc

[PATCH v2 05/14] rm: add --staged option

[Felipe Contreras]

Synonym for --cached.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-rm.txt | 5 ++++-
 builtin/rm.c             | 1 +
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt
index 1d876c2..156b40d 100644
--- a/Documentation/git-rm.txt
+++ b/Documentation/git-rm.txt
@@ -8,7 +8,7 @@ git-rm - Remove files from the working tree and from the index
 SYNOPSIS
 --------
 [verse]
-'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>...
+'git rm' [-f | --force] [-n] [-r] [--cached | --staged] [--ignore-unmatch] [--quiet] [--] <file>...
 
 DESCRIPTION
 -----------
@@ -60,6 +60,9 @@ OPTIONS
 	Working tree files, whether modified or not, will be
 	left alone.
 
+--staged::
+	Synonym for --cached.
+
 --ignore-unmatch::
 	Exit with a zero status even if no files matched.
 
diff --git a/builtin/rm.c b/builtin/rm.c
index 0df0b4d..919911f 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -268,6 +268,7 @@ static struct option builtin_rm_options[] = {
 	OPT__DRY_RUN(&show_only, N_("dry run")),
 	OPT__QUIET(&quiet, N_("do not list removed files")),
 	OPT_BOOLEAN( 0 , "cached",         &index_only, N_("only remove from the index")),
+	OPT_BOOLEAN( 0 , "staged",         &index_only, N_("only remove from the index")),
 	OPT__FORCE(&force, N_("override the up-to-date check")),
 	OPT_BOOLEAN('r', NULL,             &recursive,  N_("allow recursive removal")),
 	OPT_BOOLEAN( 0 , "ignore-unmatch", &ignore_unmatch,
-- 
1.8.4-fc

[PATCH v2 02/14] stage: add edit command

[Felipe Contreras]

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-stage.txt            |  5 +++
 builtin/stage.c                        | 75 ++++++++++++++++++++++++++++++++++
 contrib/completion/git-completion.bash |  4 +-
 3 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt
index 318bf45..3e52a66 100644
--- a/Documentation/git-stage.txt
+++ b/Documentation/git-stage.txt
@@ -15,6 +15,7 @@ SYNOPSIS
 'git stage diff' [options] [<commit>] [--] [<paths>...]
 'git stage rm' [options] [--] [<paths>...]
 'git stage apply' [options] [--] [<paths>...]
+'git stage edit'
 
 DESCRIPTION
 -----------
@@ -45,6 +46,10 @@ Remove files from the staging area only. See linkgit:git-rm[1] --staged.
 
 Apply a patch to the staging area. See linkgit:git-rm[1] --staged.
 
+'edit'::
+
+Manually edit the staging area (as a diff).
+
 SEE ALSO
 --------
 linkgit:git-add[1]
diff --git a/builtin/stage.c b/builtin/stage.c
index 3023d17..f537c1d 100644
--- a/builtin/stage.c
+++ b/builtin/stage.c
@@ -6,16 +6,88 @@
 
 #include "builtin.h"
 #include "parse-options.h"
+#include "diff.h"
+#include "diffcore.h"
+#include "revision.h"
 
 static const char *const stage_usage[] = {
 	N_("git stage [options] [--] <paths>..."),
 	N_("git stage add [options] [--] <paths>..."),
+	N_("git stage apply [options] [<patch>...]"),
 	N_("git stage reset [-q|--patch] [--] <paths>..."),
 	N_("git stage diff [options] [<commit]> [--] <paths>..."),
 	N_("git stage rm [options] [--] <paths>..."),
 	NULL
 };
 
+static int do_reset(const char *prefix)
+{
+	const char *argv[] = { "reset", "--quiet", NULL };
+	return cmd_reset(2, argv, prefix);
+}
+
+static int do_apply(const char *file, const char *prefix)
+{
+	const char *argv[] = { "apply", "--recount", "--cached", file, NULL };
+	return cmd_apply(4, argv, prefix);
+}
+
+static int edit(int argc, const char **argv, const char *prefix)
+{
+	char *file = git_pathdup("STAGE_EDIT.patch");
+	int out;
+	struct rev_info rev;
+	int ret = 0;
+	struct stat st;
+
+	read_cache();
+
+	init_revisions(&rev, prefix);
+	rev.diffopt.context = 7;
+
+	argc = setup_revisions(argc, argv, &rev, NULL);
+	add_head_to_pending(&rev);
+	if (!rev.pending.nr) {
+		struct tree *tree;
+		tree = lookup_tree(EMPTY_TREE_SHA1_BIN);
+		add_pending_object(&rev, &tree->object, "HEAD");
+	}
+
+	rev.diffopt.output_format = DIFF_FORMAT_PATCH;
+	rev.diffopt.use_color = 0;
+	DIFF_OPT_SET(&rev.diffopt, IGNORE_DIRTY_SUBMODULES);
+
+	out = open(file, O_CREAT | O_WRONLY, 0666);
+	if (out < 0)
+		die(_("Could not open '%s' for writing."), file);
+	rev.diffopt.file = xfdopen(out, "w");
+	rev.diffopt.close_file = 1;
+
+	if (run_diff_index(&rev, 1))
+		die(_("Could not write patch"));
+	if (launch_editor(file, NULL, NULL))
+		exit(1);
+
+	if (stat(file, &st))
+		die_errno(_("Could not stat '%s'"), file);
+
+	ret = do_reset(prefix);
+	if (ret)
+		goto leave;
+
+	if (!st.st_size)
+		goto leave;
+
+	ret = do_apply(file, prefix);
+	if (ret)
+		goto leave;
+
+leave:
+	unlink(file);
+	free(file);
+	return ret;
+}
+
 int cmd_stage(int argc, const char **argv, const char *prefix)
 {
 	struct option options[] = { OPT_END() };
@@ -46,6 +118,9 @@ int cmd_stage(int argc, const char **argv, const char *prefix)
 
 			return cmd_apply(argc, argv, prefix);
 		}
+		if (!strcmp(argv[1], "edit")) {
+			return edit(argc - 1, argv + 1, prefix);
+		}
 	}
 
 	return cmd_add(argc, argv, prefix);
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 8cf26e2..2b81e78 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1693,7 +1693,7 @@ _git_stage ()
 {
 	__git_has_doubledash && return
 
-	local subcommands="add reset diff rm apply"
+	local subcommands="add reset diff rm apply edit"
 	local subcommand="$(__git_find_on_cmdline "$subcommands")"
 	if [ -z "$subcommand" ]; then
 		__gitcomp "$subcommands"
@@ -1711,6 +1711,8 @@ _git_stage ()
 		_git_rm;;
 	apply)
 		_git_apply;;
+	edit)
+		;;
 	*)
 		_git_add;
 	esac
-- 
1.8.4-fc

[PATCH v2 13/14] reset: allow --keep with --stage

[Felipe Contreras]

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-reset.txt |  2 +-
 builtin/reset.c             | 13 ++++++++++---
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 5cd75a8..a1419c9 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 'git reset' [-q] [<tree-ish>] [--] <paths>...
 'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...]
 'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>]
-'git reset' [--stage | --work] [-q] [<commit>]
+'git reset' [--stage | --work | --keep] [-q] [<commit>]
 
 DESCRIPTION
 -----------
diff --git a/builtin/reset.c b/builtin/reset.c
index fbc1abc..dde03a7 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -23,7 +23,7 @@
 
 static const char * const git_reset_usage[] = {
 	N_("git reset [--mixed | --soft | --hard | --merge | --keep] [-q] [<commit>]"),
-	N_("git reset [--stage | --work] [-q] [<commit>]"),
+	N_("git reset [--stage | --work | --keep] [-q] [<commit>]"),
 	N_("git reset [-q] <tree-ish> [--] <paths>..."),
 	N_("git reset --patch [<tree-ish>] [--] [<paths>...]"),
 	NULL
@@ -295,8 +295,15 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 	}
 
 	if (stage >= 0 || working_tree >= 0) {
-		if (reset_type != NONE)
+		int keep = 0;
+
+		if (reset_type == KEEP) {
+			if (working_tree == 1)
+				die(_("--keep is incompatible with --work"));
+			keep = 1;
+		} else if (reset_type != NONE) {
 			die(_("--{stage,work} are incompatible with --{hard,mixed,soft,merge}"));
+		}
 
 		if (working_tree == 1) {
 			if (stage == 0)
@@ -304,7 +311,7 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 			reset_type = HARD;
 		} else {
 			if (stage == 1)
-				reset_type = NONE;
+				reset_type = keep ? KEEP : NONE;
 			else
 				reset_type = SOFT;
 		}
-- 
1.8.4-fc

[PATCH v2 12/14] reset: add --stage and --work options

[Felipe Contreras]

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-reset.txt |  8 ++++++++
 builtin/reset.c             | 20 ++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index f445cb3..5cd75a8 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -11,6 +11,7 @@ SYNOPSIS
 'git reset' [-q] [<tree-ish>] [--] <paths>...
 'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...]
 'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>]
+'git reset' [--stage | --work] [-q] [<commit>]
 
 DESCRIPTION
 -----------
@@ -81,6 +82,13 @@ but carries forward unmerged index entries.
 	different between <commit> and HEAD.
 	If a file that is different between <commit> and HEAD has local changes,
 	reset is aborted.
+
+--stage::
+	Reset the index, basically `--mixed`. `--no-stage` is the equivalent of
+	`--soft`.
+
+--work::
+	Resets the working tree, basically `--hard`.
 --
 
 If you want to undo a commit other than the latest on a branch,
diff --git a/builtin/reset.c b/builtin/reset.c
index afa6e02..fbc1abc 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -23,6 +23,7 @@
 
 static const char * const git_reset_usage[] = {
 	N_("git reset [--mixed | --soft | --hard | --merge | --keep] [-q] [<commit>]"),
+	N_("git reset [--stage | --work] [-q] [<commit>]"),
 	N_("git reset [-q] <tree-ish> [--] <paths>..."),
 	N_("git reset --patch [<tree-ish>] [--] [<paths>...]"),
 	NULL
@@ -243,6 +244,7 @@ static int update_refs(const char *rev, const unsigned char *sha1)
 int cmd_reset(int argc, const char **argv, const char *prefix)
 {
 	int reset_type = NONE, update_ref_status = 0, quiet = 0;
+	int stage = -1, working_tree = -1;
 	int patch_mode = 0, unborn;
 	const char *rev;
 	unsigned char sha1[20];
@@ -258,6 +260,8 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 				N_("reset HEAD, index and working tree"), MERGE),
 		OPT_SET_INT(0, "keep", &reset_type,
 				N_("reset HEAD but keep local changes"), KEEP),
+		OPT_BOOL(0, "stage", &stage, N_("reset index")),
+		OPT_BOOL(0, "work", &working_tree, N_("reset working tree")),
 		OPT_BOOLEAN('p', "patch", &patch_mode, N_("select hunks interactively")),
 		OPT_END()
 	};
@@ -290,6 +294,22 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 		hashcpy(sha1, tree->object.sha1);
 	}
 
+	if (stage >= 0 || working_tree >= 0) {
+		if (reset_type != NONE)
+			die(_("--{stage,work} are incompatible with --{hard,mixed,soft,merge}"));
+
+		if (working_tree == 1) {
+			if (stage == 0)
+				die(_("--no-stage doesn't make sense with --work"));
+			reset_type = HARD;
+		} else {
+			if (stage == 1)
+				reset_type = NONE;
+			else
+				reset_type = SOFT;
+		}
+	}
+
 	if (patch_mode) {
 		if (reset_type != NONE)
 			die(_("--patch is incompatible with --{hard,mixed,soft}"));
-- 
1.8.4-fc

[PATCH v2 08/14] submodule: add --staged options

[Felipe Contreras]

Synonym for --cached.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-submodule.txt |  8 ++++++--
 git-submodule.sh                | 10 +++++-----
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index bfef8a0..904e007 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -11,13 +11,13 @@ SYNOPSIS
 [verse]
 'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
 	      [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]
-'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
+'git submodule' [--quiet] status [--cached|--staged] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
 	      [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]
 	      [--merge] [--recursive] [--] [<path>...]
-'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
+'git submodule' [--quiet] summary [--cached|--staged|--files] [(-n|--summary-limit) <n>]
 	      [commit] [--] [<path>...]
 'git submodule' [--quiet] foreach [--recursive] <command>
 'git submodule' [--quiet] sync [--] [<path>...]
@@ -248,6 +248,10 @@ OPTIONS
 	commands typically use the commit found in the submodule HEAD, but
 	with this option, the commit stored in the index is used instead.
 
+
+--staged::
+	Synonym for `--cached`.
+
 --files::
 	This option is only valid for the summary command. This command
 	compares the commit in the index with that in the submodule HEAD
diff --git a/git-submodule.sh b/git-submodule.sh
index 2979197..823b783 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -6,11 +6,11 @@
 
 dashless=$(basename "$0" | sed -e 's/-/ /')
 USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>]
-   or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...]
+   or: $dashless [--quiet] status [--cached|--staged] [--recursive] [--] [<path>...]
    or: $dashless [--quiet] init [--] [<path>...]
    or: $dashless [--quiet] deinit [-f|--force] [--] <path>...
    or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...]
-   or: $dashless [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]
+   or: $dashless [--quiet] summary [--cached|--staged|--files] [--summary-limit <n>] [commit] [--] [<path>...]
    or: $dashless [--quiet] foreach [--recursive] <command>
    or: $dashless [--quiet] sync [--recursive] [--] [<path>...]"
 OPTIONS_SPEC=
@@ -972,7 +972,7 @@ cmd_summary() {
 	while test $# -ne 0
 	do
 		case "$1" in
-		--cached)
+		--cached|--staged)
 			cached="$1"
 			;;
 		--files)
@@ -1181,7 +1181,7 @@ cmd_status()
 		-q|--quiet)
 			GIT_QUIET=1
 			;;
-		--cached)
+		--cached|--staged)
 			cached=1
 			;;
 		--recursive)
@@ -1348,7 +1348,7 @@ do
 		esac
 		branch="$2"; shift
 		;;
-	--cached)
+	--cached|--staged)
 		cached="$1"
 		;;
 	--)
-- 
1.8.4-fc

[PATCH v2 11/14] completion: update --staged options

[Felipe Contreras]

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 contrib/completion/git-completion.bash | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 2b81e78..1dde51f 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -881,7 +881,7 @@ _git_apply ()
 		__gitcomp "
 			--stat --numstat --summary --check --index
 			--cached --index-info --reverse --reject --unidiff-zero
-			--apply --no-add --exclude=
+			--apply --no-add --exclude= --staged
 			--ignore-whitespace --ignore-space-change
 			--whitespace= --inaccurate-eof --verbose
 			"
@@ -1294,7 +1294,7 @@ _git_grep ()
 	case "$cur" in
 	--*)
 		__gitcomp "
-			--cached
+			--cached --staged
 			--text --ignore-case --word-regexp --invert-match
 			--full-name --line-number
 			--extended-regexp --basic-regexp --fixed-strings
@@ -2253,7 +2253,7 @@ _git_rm ()
 {
 	case "$cur" in
 	--*)
-		__gitcomp "--cached --dry-run --ignore-unmatch --quiet"
+		__gitcomp "--cached --staged --dry-run --ignore-unmatch --quiet"
 		return
 		;;
 	esac
@@ -2320,7 +2320,7 @@ _git_show_branch ()
 
 _git_stash ()
 {
-	local save_opts='--keep-index --no-keep-index --quiet --patch'
+	local save_opts='--keep-index --no-keep-index --stage --no-stage --quiet --patch'
 	local subcommands='save list show apply clear drop pop create branch'
 	local subcommand="$(__git_find_on_cmdline "$subcommands")"
 	if [ -z "$subcommand" ]; then
@@ -2340,7 +2340,7 @@ _git_stash ()
 			__gitcomp "$save_opts"
 			;;
 		apply,--*|pop,--*)
-			__gitcomp "--index --quiet"
+			__gitcomp "--index --stage --quiet"
 			;;
 		show,--*|drop,--*|branch,--*)
 			;;
-- 
1.8.4-fc

[PATCH v2 06/14] stash: add --stage option to save

[Felipe Contreras]

--no-stage is synonym for --keep-index.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-stash.txt | 6 +++---
 git-stash.sh                | 8 +++++++-
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index db7e803..21a01c2 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -13,7 +13,7 @@ SYNOPSIS
 'git stash' drop [-q|--quiet] [<stash>]
 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
 'git stash' branch <branchname> [<stash>]
-'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]
+'git stash' [save [-p|--patch] [-k|--[no-]keep-index|--[no-]stage] [-q|--quiet]
 	     [-u|--include-untracked] [-a|--all] [<message>]]
 'git stash' clear
 'git stash' create [<message>]
@@ -44,7 +44,7 @@ is also possible).
 OPTIONS
 -------
 
-save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
+save [-p|--patch] [--[no-]keep-index|--[no-]stage] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
 
 	Save your local modifications to a new 'stash', and run `git reset
 	--hard` to revert them.  The <message> part is optional and gives
@@ -54,7 +54,7 @@ save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--
 	subcommand from making an unwanted stash.
 +
 If the `--keep-index` option is used, all changes already added to the
-index are left intact.
+index are left intact. Same with `--no-stage`, which is a synonym.
 +
 If the `--include-untracked` option is used, all untracked files are also
 stashed and then cleaned up with `git clean`, leaving the working directory
diff --git a/git-stash.sh b/git-stash.sh
index 1e541a2..47220d0 100755
--- a/git-stash.sh
+++ b/git-stash.sh
@@ -7,7 +7,7 @@ USAGE="list [<options>]
    or: $dashless drop [-q|--quiet] [<stash>]
    or: $dashless ( pop | apply ) [--index] [-q|--quiet] [<stash>]
    or: $dashless branch <branchname> [<stash>]
-   or: $dashless [save [--patch] [-k|--[no-]keep-index] [-q|--quiet]
+   or: $dashless [save [--patch] [-k|--[no-]keep-index|--[no-]stage] [-q|--quiet]
 		       [-u|--include-untracked] [-a|--all] [<message>]]
    or: $dashless clear"
 
@@ -204,6 +204,12 @@ save_stash () {
 		--no-keep-index)
 			keep_index=n
 			;;
+		--stage)
+			keep_index=n
+			;;
+		--no-stage)
+			keep_index=t
+			;;
 		-p|--patch)
 			patch_mode=t
 			# only default to keep if we don't already have an override
-- 
1.8.4-fc