Officially start moving to the term 'staging area'

Officially start moving to the term 'staging area'

[Felipe Contreras]

Hi,

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

-- 
Felipe Contreras

[PATCH 0/2] stage: proper 'stage' command

[Felipe Contreras]

Hi,

The first patch adds subcommands for the 'git stage' command; add, reset, diff,
rm, apply. By default the add command is used, so 'git stage $file' remains the
same.

The second patch adds the incredibly useful 'git stage edit' command.

Felipe Contreras (2):
  Add proper 'stage' command
  stage: add edit command

 Documentation/git-stage.txt            |  50 +++++++++++--
 Makefile                               |   2 +-
 builtin.h                              |   1 +
 builtin/stage.c                        | 126 +++++++++++++++++++++++++++++++++
 contrib/completion/git-completion.bash |  26 ++++++-
 git.c                                  |   2 +-
 6 files changed, 199 insertions(+), 8 deletions(-)
 create mode 100644 builtin/stage.c

-- 
1.8.4-fc

[PATCH 1/2] 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

[PATCH 2/2] stage: add edit command

[Felipe Contreras]

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-stage.txt            |  5 +++
 builtin/stage.c                        | 74 ++++++++++++++++++++++++++++++++++
 contrib/completion/git-completion.bash |  4 +-
 3 files changed, 82 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..d3c58d5 100644
--- a/builtin/stage.c
+++ b/builtin/stage.c
@@ -6,6 +6,9 @@
 
 #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>..."),
@@ -16,6 +19,74 @@ static const char *const stage_usage[] = {
 	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 +117,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 0/9] Add --stage and --work options

[Felipe Contreras]

Hi,

Some commands (git diff) already have the --staged alias, this patch series
document them, and do the same for the rest.

Also, add a --work (and --no-work) option, so that in addition to --stage, we
can replace --cached in 'git apply'.

The old options remain unchanged.

Felipe Contreras (9):
  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

 Documentation/git-apply.txt            | 11 +++++++++--
 Documentation/git-diff.txt             |  4 ++--
 Documentation/git-grep.txt             |  5 ++++-
 Documentation/git-rm.txt               |  5 ++++-
 Documentation/git-stash.txt            | 14 +++++++-------
 Documentation/git-submodule.txt        |  8 ++++++--
 builtin/apply.c                        |  7 +++++++
 builtin/grep.c                         |  2 ++
 builtin/rm.c                           |  1 +
 contrib/completion/git-completion.bash | 10 +++++-----
 git-stash.sh                           | 12 +++++++++---
 git-submodule.sh                       | 10 +++++-----
 12 files changed, 61 insertions(+), 28 deletions(-)

-- 
1.8.4-fc

[PATCH 1/9] 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 2/9] 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 3/9] 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 4/9] 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..75b4cc6 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 snynonym.
 +
 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

[PATCH 5/9] 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 75b4cc6..b4066fd 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 6/9] 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 7/9] 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..ce44327 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--3way]
 	  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
 	  [--allow-binary-replacement | --binary] [--reject] [-z]
-	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
+	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached|--staged]
 	  [--ignore-space-change | --ignore-whitespace ]
 	  [--whitespace=(nowarn|warn|fix|error|error-all)]
 	  [--exclude=<path>] [--include=<path>] [--directory=<root>]
@@ -67,6 +67,9 @@ OPTIONS
 	up-to-date, it is flagged as an error.  This flag also
 	causes the index file to be updated.
 
+--staged::
+	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 8/9] 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 ce44327..6167061 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 9/9] 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 5da920e..4adc4ed 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
@@ -2229,7 +2229,7 @@ _git_rm ()
 {
 	case "$cur" in
 	--*)
-		__gitcomp "--cached --dry-run --ignore-unmatch --quiet"
+		__gitcomp "--cached --staged --dry-run --ignore-unmatch --quiet"
 		return
 		;;
 	esac
@@ -2296,7 +2296,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
@@ -2316,7 +2316,7 @@ _git_stash ()
 			__gitcomp "$save_opts"
 			;;
 		apply,--*|pop,--*)
-			__gitcomp "--index --quiet"
+			__gitcomp "--index --stage --quiet"
 			;;
 		show,--*|drop,--*|branch,--*)
 			;;
-- 
1.8.4-fc

[PATCH 0/3] reset: refactor into --stage and --work

[Felipe Contreras]

Hi,

This patch series is not really necessary for the whole --stage series, but it
makes sense while we are at it.

Felipe Contreras (3):
  reset: add --stage and --work options
  reset: allow --keep with --stage
  completion: update 'git reset' new stage options

 Documentation/git-reset.txt            |  8 ++++++++
 builtin/reset.c                        | 27 +++++++++++++++++++++++++++
 contrib/completion/git-completion.bash |  3 ++-
 3 files changed, 37 insertions(+), 1 deletion(-)

-- 
1.8.4-fc

[PATCH 1/3] 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 2/3] 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 3/3] 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 4adc4ed..24b2c22 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -2207,7 +2207,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

Re: [PATCH 2/2] stage: add edit command

[Matthieu Moy]

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

> +'edit'::
> +
> +Manually edit the staging area (as a diff).
> +

That sounds interesting. It reminds me "git add --edit", but they are
different ('stage edit' edits the patch with HEAD, 'add --edit' edits
the patch with the worktree).

Can we find a consistent user-interface where "git add --edit" and "git
stage edit" have a closer syntax? Maybe "git stage edit --work" as a
synonym for "git add --edit"?

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

Re: Officially start moving to the term 'staging area'

[Junio C Hamano]

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

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

"add" is the verb, not "index" (which is a noun that refers
to the thing that keeps track of what will be written as a tree to
be committed next).

And it will stay that way.

IIRC, when this was discussed, many non-native speakers had trouble
with the verb "to stage", not just from i18n/l10n point of view.

Re: [PATCH 1/2] Add proper 'stage' command

[Matthieu Moy]

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

> +COMMANDS
> +--------
> +
> +With no arguments, it's a synonym for linkgit:git-add[1].

This would not be very useful since "git add" errors out when called
without arguments ;-).

The accurate description of your code would be closer to "When the first
argument is not a subcommand, it's a synonym for linkgit:git-add[1].".
I'm not sure I like it, as it creates ambiguities (e.g. need to spell
"git stage -- diff" to add a file called "diff". Not a strong objection
though, as we already have refs Vs filename ambiguities in many places.

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

Re: [PATCH 4/9] stash: add --stage option to save

[Matthieu Moy]

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

> +index are left intact. Same with `--no-stage`, which is a snynonym.

s/snynonym/synonym/

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

Re: [PATCH 2/2] stage: add edit command

[Felipe Contreras]

Matthieu Moy wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > +'edit'::
> > +
> > +Manually edit the staging area (as a diff).
> > +
> 
> That sounds interesting. It reminds me "git add --edit", but they are
> different ('stage edit' edits the patch with HEAD, 'add --edit' edits
> the patch with the worktree).

That's not the only difference; 'add --edit' is incremental.

> Can we find a consistent user-interface where "git add --edit" and "git
> stage edit" have a closer syntax? Maybe "git stage edit --work" as a
> synonym for "git add --edit"?

Well, the action is adding changes to the staging area. To me, I'm not editing
the stage, I'm editing the change I'm adding to the stage, so 'git stage
--edit' is perfectly fine.

-- 
Felipe Contreras

Re: [PATCH 1/2] Add proper 'stage' command

[Felipe Contreras]

Matthieu Moy wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > +COMMANDS
> > +--------
> > +
> > +With no arguments, it's a synonym for linkgit:git-add[1].
> 
> This would not be very useful since "git add" errors out when called
> without arguments ;-).

Right.

> The accurate description of your code would be closer to "When the first
> argument is not a subcommand, it's a synonym for linkgit:git-add[1].".
> I'm not sure I like it, as it creates ambiguities (e.g. need to spell
> "git stage -- diff" to add a file called "diff". Not a strong objection
> though, as we already have refs Vs filename ambiguities in many places.

Yes, I thought really hard about this, but I think it's the best alternative.
In adition, we could stat to see if there's a file with the same name as the
assumed subcommand, and warn about the ambiguity, and the recommended way to
add the file.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Matthieu Moy]

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

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

Thanks for working on this. No time for a really detailed review, but a
few remarks.

> The term 'staging area' is more intuitive [...]
>
> The first step in moving Git towards this term, is first to add --stage
> options for every command that uses --index or --cache.

These explanations make sense. I think it would be better to put part of
it in commit messages, so that future contributors can "git blame" the
doc/implem of these --stage and find them (i.e. avoid the
misunderstanding that occured with "git stage" command which was
proposed for removal).

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

Same: putting this in the commit message would cast in stone that we
want to obsolete the old ones.

(But that was nice to have this cover-letter)

> Moreover, the --stage and --work

--work alone sounds weird. At least to me, it does not immediately imply
"working tree". It is tempting to call the option --work-tree, but git
already has a global option with that name (git --work-tree=foo bar).

Perhaps --worktree to limit the confusion?

> 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:

I didn't understand the table, but yes, the --soft, --mixed, and --hard
is terrible, I need to read the doc whenever I do something non-trivial
with reset :-(.

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

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

Matthieu Moy wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > 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.
> 
> Thanks for working on this. No time for a really detailed review, but a
> few remarks.
> 
> > The term 'staging area' is more intuitive [...]
> >
> > The first step in moving Git towards this term, is first to add --stage
> > options for every command that uses --index or --cache.
> 
> These explanations make sense. I think it would be better to put part of
> it in commit messages, so that future contributors can "git blame" the
> doc/implem of these --stage and find them (i.e. avoid the
> misunderstanding that occured with "git stage" command which was
> proposed for removal).

Yes, but which commit? All of them? Perhaps it would make sense to add a link
to the cover e-mail, or add an explanation in Documentation/gitstagingarea.txt
or something.

> > Moreover, the --stage and --work
> 
> --work alone sounds weird. At least to me, it does not immediately imply
> "working tree". It is tempting to call the option --work-tree, but git
> already has a global option with that name (git --work-tree=foo bar).

Yes, --work sounds weird, but so does --cherry. I thought about --wt, but I
felt --work was more understandable, and --work-tree doesn't really give much
more value, except more characters to type =/

> > 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:
> 
> I didn't understand the table, but yes, the --soft, --mixed, and --hard
> is terrible, I need to read the doc whenever I do something non-trivial
> with reset :-(.

Me too, I always got 'git reset --hard', now I get 'git reset', but that's
about it, for the rest I have to read the documentation. Also, 'git stage
reset' makes it even easier.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Matthieu Moy]

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

> Matthieu Moy wrote:
>> These explanations make sense. I think it would be better to put part of
>> it in commit messages, so that future contributors can "git blame" the
>> doc/implem of these --stage and find them (i.e. avoid the
>> misunderstanding that occured with "git stage" command which was
>> proposed for removal).
>
> Yes, but which commit? All of them? Perhaps it would make sense to add a link
> to the cover e-mail, or add an explanation in Documentation/gitstagingarea.txt
> or something.

Putting the explanation about --stage in the first commit about it, and
then saying something like "continue the work on --stage" in the next
messages would make sense to me.

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

Re: Officially start moving to the term 'staging area'

[Matthieu Moy]

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

> add an explanation in Documentation/gitstagingarea.txt
> or something.

There's Documentation/gitcli.txt, that will need updating anyway (at the
bottom, it talks about --cached and --index).

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

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Thu, Aug 29, 2013 at 1:37 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> 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.
>
> "add" is the verb,

Add changes to what? The user needs to know that.

> not "index" (which is a noun that refers
> to the thing that keeps track of what will be written as a tree to
> be committed next).

How Git creates trees is irrelevant to the high-level user, all that
is relevant is what happens from the users's point of view, and from
the user's point of view he is adding changes to an area that contains
the changes that will be part of the next commit.

*Everyone* has agreed that the best name for that is the "staging area".

> And it will stay that way.

We'll see about that. If it stays that way, it's because you are not
listening to what *everyone*, including users, developers, and
teachers of Git, are saying.

> IIRC, when this was discussed, many non-native speakers had trouble
> with the verb "to stage", not just from i18n/l10n point of view.

Well, you recall incorrectly.

There was *A SINGLE* non-native speaker that complained, about
"stage", not "staging area", Ævar Arnfjörð Bjarmason, and he even said
he had already translated index/cache to "the commit area"[1].

Again, *everyone* has agreed that index needs to be renamed, and
"staging area" is the best option.

Do I really need to go through all the discussions and list each and
every person that participated in them, and show to you how everyone
agreed? Can't you just go and read them again? There was a single
person that didn't like the term "staging area", but he accepted that
index is definitely not the right term (Drew Northup).

Here are the threads once again:

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

[1] http://article.gmane.org/gmane.comp.version-control.git/197217

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[René Scharfe]

Am 29.08.2013 20:57, schrieb Felipe Contreras:
> Matthieu Moy wrote:
>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>> Moreover, the --stage and --work
>>
>> --work alone sounds weird. At least to me, it does not immediately imply
>> "working tree". It is tempting to call the option --work-tree, but git
>> already has a global option with that name (git --work-tree=foo bar).
>
> Yes, --work sounds weird, but so does --cherry. I thought about --wt, but I
> felt --work was more understandable, and --work-tree doesn't really give much
> more value, except more characters to type =/

If you have a --work-tree option then parseopt accepts --work as well, 
unless it's ambiguous, i.e. another option starts with --work, too.  So 
you can have a descriptive, extra-long option and type just a few 
characters at the same time.

René

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Thu, Aug 29, 2013 at 3:03 PM, René Scharfe <l.s.r@web.de> wrote:
> Am 29.08.2013 20:57, schrieb Felipe Contreras:
>>
>> Matthieu Moy wrote:
>>
>>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>>>
>>>> Moreover, the --stage and --work
>>>
>>>
>>> --work alone sounds weird. At least to me, it does not immediately imply
>>> "working tree". It is tempting to call the option --work-tree, but git
>>> already has a global option with that name (git --work-tree=foo bar).
>>
>>
>> Yes, --work sounds weird, but so does --cherry. I thought about --wt, but
>> I
>> felt --work was more understandable, and --work-tree doesn't really give
>> much
>> more value, except more characters to type =/
>
>
> If you have a --work-tree option then parseopt accepts --work as well,
> unless it's ambiguous, i.e. another option starts with --work, too.  So you
> can have a descriptive, extra-long option and type just a few characters at
> the same time.

Right, but what do we use in the documentation? Writing --work-tree in
the 'git reset' table for example would be rather ugly. I'm fine with
--work-tree, but I think it would be weird to have short-hands in the
documentation, although not entirely bad.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Matthieu Moy]

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

> Matthieu Moy wrote:
>
>> --work alone sounds weird. At least to me, it does not immediately imply
>> "working tree". It is tempting to call the option --work-tree, but git
>> already has a global option with that name (git --work-tree=foo bar).
>
> Yes, --work sounds weird, but so does --cherry. I thought about --wt, but I
> felt --work was more understandable, and --work-tree doesn't really give much
> more value,

I think it does: I understand --work as "the verb to work", so 
"git reset --work" sounds like "tell 'git reset' to work", while
"git reset --work-tree" sounds like "tell git to reset the work tree".

> except more characters to type =/

Then, we can have --work-tree and a short version -w.

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

Re: Officially start moving to the term 'staging area'

[Drew Northup]

On Thu, Aug 29, 2013 at 2:37 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> 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.
>
> "add" is the verb, not "index" (which is a noun that refers
> to the thing that keeps track of what will be written as a tree to
> be committed next).
>
> And it will stay that way.
>
> IIRC, when this was discussed, many non-native speakers had trouble
> with the verb "to stage", not just from i18n/l10n point of view.

I agree with Junio. This effort is better spent making the
documentation clearer and more succinct. The reality is that a user
needs to build a model in their mind of what they are doing which maps
enough (completely is not required) to what is actually going on to
get work done. If the documentation or the instruction is getting in
the way of that in the name of simplifying the presentation then the
presentation is wrong.

We add content snapshots to the index of content (creating
"temporary"--they will be garbage collected eventually if they become
orphans--objects into the store at the same time). We build commits
from those snapshots (in whole or in part, typically only using the
most recent snapshots of new things added to the index) and save those
in the object store with the content and tree objects. Sometimes we
create tag objects to record something special about commits, trees,
and content blobs.

That's the real model (with some rough edges). Explaining what that
has to do with distributed version control is the hard part.

-- 
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Thu, Aug 29, 2013 at 4:55 PM, Drew Northup <n1xim.email@gmail.com> wrote:
> On Thu, Aug 29, 2013 at 2:37 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>
>>> 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.
>>
>> "add" is the verb, not "index" (which is a noun that refers
>> to the thing that keeps track of what will be written as a tree to
>> be committed next).
>>
>> And it will stay that way.
>>
>> IIRC, when this was discussed, many non-native speakers had trouble
>> with the verb "to stage", not just from i18n/l10n point of view.
>
> I agree with Junio.

All right, you are the only person (presumably other than Junio) that
thinks "index" is the right name for what high-level users should be
familiar with.

> This effort is better spent making the
> documentation clearer and more succinct. The reality is that a user
> needs to build a model in their mind of what they are doing which maps
> enough (completely is not required) to what is actually going on to
> get work done. If the documentation or the instruction is getting in
> the way of that in the name of simplifying the presentation then the
> presentation is wrong.
>
> We add content snapshots to the index of content (creating
> "temporary"--they will be garbage collected eventually if they become
> orphans--objects into the store at the same time). We build commits
> from those snapshots (in whole or in part, typically only using the
> most recent snapshots of new things added to the index) and save those
> in the object store with the content and tree objects. Sometimes we
> create tag objects to record something special about commits, trees,
> and content blobs.
>
> That's the real model (with some rough edges). Explaining what that
> has to do with distributed version control is the hard part.

The user doesn't need to know the format of the index, or the packs,
in fact, they don't even need to know the index or packs even exist.

All the user needs to know about this is that there's an area where
contents of the next commit are being prepared, and "staging area" is
the best name for that mental area. How that area is actually
implemented (the index) is not relevant to the user.

Everyone agrees on that, except you, and possibly Junio.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Piotr Krukowiecki]

Drew Northup <n1xim.email@gmail.com> napisał:
>I agree with Junio. This effort is better spent making the
>documentation clearer and more succinct. The reality is that a user
>needs to build a model in their mind of what they are doing which maps
>enough (completely is not required) to what is actually going on to
>get work done. If the documentation or the instruction is getting in
>the way of that in the name of simplifying the presentation then the
>presentation is wrong.

Why do you think the "stage"  model do not map enough? 


>We add content snapshots to the index of content (creating
>"temporary"--they will be garbage collected eventually if they become
>orphans--objects into the store at the same time). We build commits
>from those snapshots (in whole or in part, typically only using the
>most recent snapshots of new things added to the index) and save those
>in the object store with the content and tree objects. Sometimes we
>create tag objects to record something special about commits, trees,
>and content blobs.

The above can be rewritten to use the 'staging area' concept just fine. And I don't think you should say to inexperienced users things like 'tree objects'.

A good exercise would be to take documentation of some command and show that it can or can't be rewritten to use the other term. 

Instead of 'indexing' or 'staging' content you could also use term 'mark'. You mark content to add, for removal, you can diff it or revert. 



>
>That's the real model (with some rough edges). Explaining what that
>has to do with distributed version control is the hard part.


-- 
Piotr Krukowiecki 

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Thu, Aug 29, 2013 at 2:57 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:

> Again, *everyone* has agreed that index needs to be renamed, and
> "staging area" is the best option.
>
> Do I really need to go through all the discussions and list each and
> every person that participated in them, and show to you how everyone
> agreed? Can't you just go and read them again? There was a single
> person that didn't like the term "staging area", but he accepted that
> index is definitely not the right term (Drew Northup).
>
> Here are the threads once again:
>
> 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

I take it you still haven't read those threads, and you don't plan to.
So I have to go through each and every comment and summarize what each
person concluded.

Hopefully you would come back to me before I waste my time, but it
seems there's no other way to make you see the reality of what was
actually already discussed and agreed.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Thu, Aug 29, 2013 at 2:57 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> On Thu, Aug 29, 2013 at 1:37 PM, Junio C Hamano <gitster@pobox.com> wrote:

>> IIRC, when this was discussed, many non-native speakers had trouble
>> with the verb "to stage", not just from i18n/l10n point of view.
>
> Well, you recall incorrectly.
>
> There was *A SINGLE* non-native speaker that complained, about
> "stage", not "staging area", Ævar Arnfjörð Bjarmason, and he even said
> he had already translated index/cache to "the commit area"[1].

Actually, not only did Ævar not have a problem with "staging area",
but he told you this argument about i18n/l10n didn't make sense at
all, and you agreed:

http://article.gmane.org/gmane.comp.version-control.git/197371

In fact, all non-native speakers said they liked the term "staging
area", like everybody else.

So please enlighten us, which non-native speakers had a problem from
the translation point of view, and why does it matter?

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Fri, Aug 30, 2013 at 2:11 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> On Thu, Aug 29, 2013 at 2:57 PM, Felipe Contreras
> <felipe.contreras@gmail.com> wrote:

>> Here are the threads once again:
>>
>> 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
>
> I take it you still haven't read those threads, and you don't plan to.
> So I have to go through each and every comment and summarize what each
> person concluded.
>
> Hopefully you would come back to me before I waste my time, but it
> seems there's no other way to make you see the reality of what was
> actually already discussed and agreed.

So here's the summary, as I said, *everybody* is in favor of "staging
area" or something other than "index", with the exception of Drew
Northup, I've put a summary of the conclusion of each person that
voiced an opinion on the matter, and I've CC'ed them here, so they can
reiterate their opinion, or clarify it.

Junio, do you accept that virtually *everyone* is in favor of "staging
area" now?

== Against ==

Drew Northup:
index is good

== For ==

Jay Soffian:
staging area is better

Pete Harlan:
Aghiles:
"staging area" is good for teaching

Piotr Krukowiecki:
"staging area" makes sense

Jonathan Nieder:
"staging area" is better than "index"

Jeff King:
"staging area" makes perfect sense

Miles Bader:
"staging area" is good

Phil Hord:
"staging area" is better than index/cache

Victor Engmark:
maybe "git bucket"

David (bouncingcats):
maybe "precommit"

Alexey Feldgendler:
"staging area" translates better into Russian (than precommit)

Alexei Sholik:
"staging area" is better

Zbigniew Jędrzejewski-Szmek:
"staging area" is better

Ævar Arnfjörð Bjarmason:
In Icelandic "index/stage" is translated to "the commit area"

Sebastien Douche:
"stage" is better than "cache"/"index"

Thiago Farina:
"precommit" is better

Mark Lodato:
"staging" is the most appropriate

Philip Oakley:
"staging area" is OK

Matthieu Moy:
something needs to be done

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Fri, Aug 30, 2013 at 3:40 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> On Fri, Aug 30, 2013 at 2:11 PM, Felipe Contreras
> <felipe.contreras@gmail.com> wrote:
>> On Thu, Aug 29, 2013 at 2:57 PM, Felipe Contreras
>> <felipe.contreras@gmail.com> wrote:
>
>>> Here are the threads once again:
>>>
>>> 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
>>
>> I take it you still haven't read those threads, and you don't plan to.
>> So I have to go through each and every comment and summarize what each
>> person concluded.
>>
>> Hopefully you would come back to me before I waste my time, but it
>> seems there's no other way to make you see the reality of what was
>> actually already discussed and agreed.
>
> So here's the summary, as I said, *everybody* is in favor of "staging
> area" or something other than "index", with the exception of Drew
> Northup, I've put a summary of the conclusion of each person that
> voiced an opinion on the matter, and I've CC'ed them here, so they can
> reiterate their opinion, or clarify it.
>
> Junio, do you accept that virtually *everyone* is in favor of "staging
> area" now?

To avoid bonces, please remove  victor.engmark@terreactive.ch and
alexeyf@opera.com from the CC list.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[René Scharfe]

Am 29.08.2013 22:36, schrieb Felipe Contreras:
> On Thu, Aug 29, 2013 at 3:03 PM, René Scharfe <l.s.r@web.de> wrote:
>> If you have a --work-tree option then parseopt accepts --work as well,
>> unless it's ambiguous, i.e. another option starts with --work, too.  So you
>> can have a descriptive, extra-long option and type just a few characters at
>> the same time.
>
> Right, but what do we use in the documentation? Writing --work-tree in
> the 'git reset' table for example would be rather ugly. I'm fine with
> --work-tree, but I think it would be weird to have short-hands in the
> documentation, although not entirely bad.

I don't see what's so ugly about it.

The git command itself has a --work-tree parameter for specifying the 
location of the checked-out files, however.  It could be confusing to 
have the same parameter do different things:

	$ git reset --work-tree=/some/where reset --work-tree

Perhaps a note in the documentation is enough to clear this up.


In general I think that the full long option should be mentioned in 
synopsis and description, while abbreviated parameters could be used in 
an example.  The ability to understand unambiguous shortened options is 
a general feature and doesn't have to be explained in the manpage for a 
specific command.

NB: It would be nice to have more commands use parseopt, for that 
feature alone.

René

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Sat, Aug 31, 2013 at 2:46 AM, René Scharfe <l.s.r@web.de> wrote:
> Am 29.08.2013 22:36, schrieb Felipe Contreras:
>>
>> On Thu, Aug 29, 2013 at 3:03 PM, René Scharfe <l.s.r@web.de> wrote:
>>>
>>> If you have a --work-tree option then parseopt accepts --work as well,
>>> unless it's ambiguous, i.e. another option starts with --work, too.  So
>>> you
>>> can have a descriptive, extra-long option and type just a few characters
>>> at
>>> the same time.
>>
>>
>> Right, but what do we use in the documentation? Writing --work-tree in
>> the 'git reset' table for example would be rather ugly. I'm fine with
>> --work-tree, but I think it would be weird to have short-hands in the
>> documentation, although not entirely bad.
>
> I don't see what's so ugly about it.

Maybe not so much.

> The git command itself has a --work-tree parameter for specifying the
> location of the checked-out files, however.  It could be confusing to have
> the same parameter do different things:
>
>         $ git reset --work-tree=/some/where reset --work-tree

I don't see what's confusing about that, one option is for git core,
the other is for the subcommand.

> In general I think that the full long option should be mentioned in synopsis
> and description, while abbreviated parameters could be used in an example.
> The ability to understand unambiguous shortened options is a general feature
> and doesn't have to be explained in the manpage for a specific command.
>
> NB: It would be nice to have more commands use parseopt, for that feature
> alone.

Indeed.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[David Aguilar]

On Sat, Aug 31, 2013 at 12:46 AM, René Scharfe <l.s.r@web.de> wrote:
> Am 29.08.2013 22:36, schrieb Felipe Contreras:
>>
>> On Thu, Aug 29, 2013 at 3:03 PM, René Scharfe <l.s.r@web.de> wrote:
>>>
>>> If you have a --work-tree option then parseopt accepts --work as well,
>>> unless it's ambiguous, i.e. another option starts with --work, too.  So
>>> you
>>> can have a descriptive, extra-long option and type just a few characters
>>> at
>>> the same time.
>>
>>
>> Right, but what do we use in the documentation? Writing --work-tree in
>> the 'git reset' table for example would be rather ugly. I'm fine with
>> --work-tree, but I think it would be weird to have short-hands in the
>> documentation, although not entirely bad.
>
>
> I don't see what's so ugly about it.
>
> The git command itself has a --work-tree parameter for specifying the
> location of the checked-out files, however.  It could be confusing to have
> the same parameter do different things:
>
>         $ git reset --work-tree=/some/where reset --work-tree
>
> Perhaps a note in the documentation is enough to clear this up.

I agree that this is confusing for people not deeply versed in Git jargon.
We also know that no one reads documentation.

Maybe a better word can be found?  How about "git reset --files"?
-- 
David

Re: Officially start moving to the term 'staging area'

[Drew Northup]

On Fri, Aug 30, 2013 at 1:16 AM, Piotr Krukowiecki
<piotr.krukowiecki@gmail.com> wrote:
> Drew Northup <n1xim.email@gmail.com> napisał:
>>I agree with Junio. This effort is better spent making the
>>documentation clearer and more succinct. The reality is that a user
>>needs to build a model in their mind of what they are doing which maps
>>enough (completely is not required) to what is actually going on to
>>get work done. If the documentation or the instruction is getting in
>>the way of that in the name of simplifying the presentation then the
>>presentation is wrong.
>
> Why do you think the "stage"  model do not map enough?

When I try to explain how to use git to complete VCS newbies in
general they find the "snapshot" model more mentally sensible than the
"staging area" model. (In other words, the user doesn't care how, if,
or where the program is maintaining state.) The "snapshot" model does
not require knowledge of the index and does not get in the way of
later on learning more advanced concepts which benefit from the index
being explained as what it is--explanations which quite frequently
bring up the "staging area" model (but in that case as a portion of
the index used to store snapshot state information).

>>We add content snapshots to the index of content (creating
>>"temporary"--they will be garbage collected eventually if they become
>>orphans--objects into the store at the same time). We build commits
>>from those snapshots (in whole or in part, typically only using the
>>most recent snapshots of new things added to the index) and save those
>>in the object store with the content and tree objects. Sometimes we
>>create tag objects to record something special about commits, trees,
>>and content blobs.
>
> The above can be rewritten to use the 'staging area' concept just
> fine. And I don't think you should say to inexperienced users things
> like 'tree objects'.

At what time did I say specifically what I tell newbies? I did not do
so. Please refrain from making that sort of assumption. In any case,
no, you cannot rewrite that to use "staging area" in place of "index"
without introducing a different mental model and new concept into the
text (a model which happens to be incomplete, but not incorrect). That
minimalist summary was written for the technically-minded people here
on this list debating the issue of communications with the users--the
bane of all programmers' lives.

> A good exercise would be to take documentation of some command
> and show that it can or can't be rewritten to use the other term.

That may be a good exercise in matters of philosophy, but you will
find few outside of the world of programming who would agree with that
characterization of the optimization of technical writing. (In the
English language in particular it is folly due to the extreme
variation of available terms and metaphors with nearly identical
denotations and greatly varying connotations.)

> Instead of 'indexing' or 'staging' content you could also use term 'mark'.
> You mark content to add, for removal, you can diff it or revert.

So far as I am concerned the introduction of a specific "staging area"
(as if it has a distinct physical presence) is superfluous to that.

>>That's the real model (with some rough edges). Explaining what that
>>has to do with distributed version control is the hard part.

Again, let us keep our argument focused on communications with users.
Renaming core objects is just going to sow confusion without fixing
the user communication issue. That's what I meant the first time I
wrote what I quote directly above and I'm sticking to it.

-- 
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Officially start moving to the term 'staging area'

[Drew Northup]

On Thu, Aug 29, 2013 at 6:10 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> On Thu, Aug 29, 2013 at 4:55 PM, Drew Northup <n1xim.email@gmail.com> wrote:
>> On Thu, Aug 29, 2013 at 2:37 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>>
>>>> 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.
>>>
>>> "add" is the verb, not "index" (which is a noun that refers
>>> to the thing that keeps track of what will be written as a tree to
>>> be committed next).
>>>
>>> And it will stay that way.

>> I agree with Junio.
>
> All right, you are the only person (presumably other than Junio) that
> thinks "index" is the right name for what high-level users should be
> familiar with.

If that were true it would never have gotten that name. "Add" is the
verb, as we are adding a snapshot. New users don't care how that works
for the most part. Just telling them "it keeps track of it itself" is
usually good enough. If the user is asking for more detail at that
point it is probably because he isn't as much interested in how to use
it as he is in how it works. At that point we're better off just
giving him the actual explanation instead of getting caught up in the
staging area vs index fight (which seems odd to me as the index
contains the entries which act as a "staging area"--a superset /
subset relation).

>> We add content snapshots to the index of content (creating
>> "temporary"--they will be garbage collected eventually if they become
>> orphans--objects into the store at the same time). We build commits
>> from those snapshots (in whole or in part, typically only using the
>> most recent snapshots of new things added to the index) and save those
>> in the object store with the content and tree objects. Sometimes we
>> create tag objects to record something special about commits, trees,
>> and content blobs.
>>
>> That's the real model (with some rough edges). Explaining what that
>> has to do with distributed version control is the hard part.
>
> The user doesn't need to know the format of the index, or the packs,
> in fact, they don't even need to know the index or packs even exist.

I never implied that the end user does need to know these things.
(Note the use of "We"--as in "we who are having this conversation.")

> All the user needs to know about this is that there's an area where
> contents of the next commit are being prepared, and "staging area" is
> the best name for that mental area. How that area is actually
> implemented (the index) is not relevant to the user.

Part of what I am arguing is that the mental area doesn't need to
exist at all. The "staging area" is a part of the index. It is not the
whole thing. There is no one-off complete replacement of one with the
other. Most new users won't care about either, just that it happens
somehow and that git keeps track of that state itself. We need not
change any core items to achieve that.

> Everyone agrees on that, except you, and possibly Junio.

We don't have enough information to say that. Seriously, this is
nowhere near as certain as climate change.

-- 
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Officially start moving to the term 'staging area'

[William Swanson]

On Thu, Aug 29, 2013 at 11:01 AM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> 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 realize Git is not a democracy, but if the vote of a humble user
counts for anything, I agree that "index" is a terrible name.

I was very excited when Felipe first started this thread, since I
thought Git might finally fix one of it's biggest long-standing
usability problems. Calling this thing the "index" is like calling an
important variable "someValue." While the name may be technically
correct, it's way too generic to be useful. A name like "staging area"
may not capture the whole idea, but at least it provides a good clue
about what it does and how you might use it.

If we change this, I'm pretty sure most of the Internet will rejoice.
Only a few old-timers will be grumpy, but that's just because they
don't like change in general. I have never met anybody (outside this
thread) who thought the current name was a good idea.

-William

Re: Officially start moving to the term 'staging area'

[Piotr Krukowiecki]

Just wanted to point to a Dr. Dobb's article from Monday:
http://www.drdobbs.com/tools/getting-started-with-git-the-fundamental/240160261?pgno=2

The author does not use the use the word "index" at all. Instead he
writes in following way:

---------------------------------------------------------------------------------------
Staging Changes

One of Git's best features is that it offers a staging process. You
can stage the modified files that you want to commit. Other version
control systems await your one command before your files are changed
in the repository — generally the remote repository for the entire
team. When you commit files in Git, files are held in a staging area.
You will later commit all the files from the staging area to the
larger repository.

So, let's say you wanted to make a change involving files A and B. You
changed file A. You then remembered something unrelated to do with
file Z and you modified that. Then you went back to your initial
change, modifying file B. Git allows you to add files A and B to
staging, while leaving file Z "unstaged." Then you can push only the
staged files to your repository. But you don't! You realize you need
to make a change to file C as well. You "add" it. Now files A,B, and C
are staged, and Z is still unstaged. You commit the staged changes
only.

[...]
---------------------------------------------------------------------------------------


Sorry for not responding to your comments Drew, no time at the moment.

-- 
Piotr Krukowiecki

Re: Officially start moving to the term 'staging area'

[Drew Northup]

On Wed, Sep 4, 2013 at 3:13 AM, Piotr Krukowiecki
<piotr.krukowiecki@gmail.com> wrote:
> Just wanted to point to a Dr. Dobb's article from Monday:
> http://www.drdobbs.com/tools/getting-started-with-git-the-fundamental/240160261?pgno=2
>
> The author does not use the use the word "index" at all. Instead he
> writes in following way:
>
> ---------------------------------------------------------------------------------------
<DR DOBBS QUOTE>
> ---------------------------------------------------------------------------------------
>
>
> Sorry for not responding to your comments Drew, no time at the moment.

NP. What he writes [in that quote at least] is entirely reasonable. In
fact, oddly enough (as I presume you meant it as a refutation), it can
be seen to support my argument: don't mess with the core code much (if
at all) but fix the documentation. That's all that I've been arguing
since day one. We don't need to make big huge changes in every part of
the Git metaphor set to better explain what is going on to newbies and
casual users. (Aside from the fact that there's a huge body of
existing documentation, tools, and usage patterns that depends on the
currently predominant model.)

I still argue that for a not insignificant group of users--people who
are happy with the current paradigm and therefore aren't making a lot
of noise--the current core metaphor is actually useful despite the
name being more than just a tad bit unfortunate. Alas, for dealing
with some of the advanced usage explanations it can be argued that the
"staging area" metaphor (it implies _completed_ bundles ready to
package into commits and ship--I envision shipping trailers being
filled with _immutable_ boxes and attached to trucks) is actually
harmful, but we can talk about that if there's a need.

-- 
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Officially start moving to the term 'staging area'

[Ping Yin]

On Wed, Sep 4, 2013 at 2:08 PM, William Swanson <swansontec@gmail.com> wrote:
> On Thu, Aug 29, 2013 at 11:01 AM, Felipe Contreras
> <felipe.contreras@gmail.com> wrote:
>> 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 realize Git is not a democracy, but if the vote of a humble user
> counts for anything, I agree that "index" is a terrible name.

+1 for staging area

>
> I was very excited when Felipe first started this thread, since I
> thought Git might finally fix one of it's biggest long-standing
> usability problems.

the same feeling.

Re: Officially start moving to the term 'staging area'

[Hilco Wijbenga]

On 6 September 2013 08:45, Ping Yin <pkufranky@gmail.com> wrote:
> On Wed, Sep 4, 2013 at 2:08 PM, William Swanson <swansontec@gmail.com> wrote:
>> On Thu, Aug 29, 2013 at 11:01 AM, Felipe Contreras
>> <felipe.contreras@gmail.com> wrote:
>>> 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 realize Git is not a democracy, but if the vote of a humble user
>> counts for anything, I agree that "index" is a terrible name.
>
> +1 for staging area

As yet another "just a user", I'd like to add my enthusiastic support
for "to stage" and "staging area".

I'm guessing that a lot of Git devs/long time users are simply so used
to its interface that they may not see its sharp corners any more. :-)
That's quite natural and bound to happen to anyone who works with a
particular tool for a long time. Still, (e.g.) "git add -A" removing
files (as useful as that is) is just weird. And, in general, the user
should not need to know how Git is implemented.

>> I was very excited when Felipe first started this thread, since I
>> thought Git might finally fix one of it's biggest long-standing
>> usability problems.
>
> the same feeling.

Ditto. :-)

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Wed, Sep 4, 2013 at 2:13 AM, Piotr Krukowiecki
<piotr.krukowiecki@gmail.com> wrote:
> Just wanted to point to a Dr. Dobb's article from Monday:
> http://www.drdobbs.com/tools/getting-started-with-git-the-fundamental/240160261?pgno=2
>
> The author does not use the use the word "index" at all. Instead he
> writes in following way:

Same goes for the ProGit book, which is quite famous:
http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository
http://git-scm.com/book/en/Git-Tools-Interactive-Staging

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Wed, Sep 4, 2013 at 8:36 AM, Drew Northup <n1xim.email@gmail.com> wrote:
> On Wed, Sep 4, 2013 at 3:13 AM, Piotr Krukowiecki
> <piotr.krukowiecki@gmail.com> wrote:
>> Just wanted to point to a Dr. Dobb's article from Monday:
>> http://www.drdobbs.com/tools/getting-started-with-git-the-fundamental/240160261?pgno=2
>>
>> The author does not use the use the word "index" at all. Instead he
>> writes in following way:
>>
>> ---------------------------------------------------------------------------------------
> <DR DOBBS QUOTE>
>> ---------------------------------------------------------------------------------------
>>
>>
>> Sorry for not responding to your comments Drew, no time at the moment.
>
> NP. What he writes [in that quote at least] is entirely reasonable. In
> fact, oddly enough (as I presume you meant it as a refutation), it can
> be seen to support my argument: don't mess with the core code much (if
> at all) but fix the documentation. That's all that I've been arguing
> since day one. We don't need to make big huge changes in every part of
> the Git metaphor set to better explain what is going on to newbies and
> casual users.

But he is using the term "staging area", forget about my patches to
the code, are you agreeing we should fix the documentation to use the
term "staging area" as Dr. Dobb did?

> (Aside from the fact that there's a huge body of
> existing documentation, tools, and usage patterns that depends on the
> currently predominant model.)

Most of the online documentation doesn't use the term "index", they
use "staging area", as the link just described above.

> I still argue that for a not insignificant group of users--people who
> are happy with the current paradigm and therefore aren't making a lot
> of noise--the current core metaphor is actually useful despite the
> name being more than just a tad bit unfortunate. Alas, for dealing
> with some of the advanced usage explanations it can be argued that the
> "staging area" metaphor (it implies _completed_ bundles ready to
> package into commits and ship--I envision shipping trailers being
> filled with _immutable_ boxes and attached to trucks) is actually
> harmful, but we can talk about that if there's a need.

Nobody thinks of the staging area that way, just you.

The staging area is an area that contains the preparation for the next
commit to be made. There's no ships, or trailers, or bundles.
Everybody understands that, and find the term "staging area" fit for
that description. Except you.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Tue, Sep 3, 2013 at 11:23 PM, Drew Northup <n1xim.email@gmail.com> wrote:
> On Fri, Aug 30, 2013 at 1:16 AM, Piotr Krukowiecki
> <piotr.krukowiecki@gmail.com> wrote:
>> Drew Northup <n1xim.email@gmail.com> napisał:
>>>I agree with Junio. This effort is better spent making the
>>>documentation clearer and more succinct. The reality is that a user
>>>needs to build a model in their mind of what they are doing which maps
>>>enough (completely is not required) to what is actually going on to
>>>get work done. If the documentation or the instruction is getting in
>>>the way of that in the name of simplifying the presentation then the
>>>presentation is wrong.
>>
>> Why do you think the "stage"  model do not map enough?
>
> When I try to explain how to use git to complete VCS newbies in
> general they find the "snapshot" model more mentally sensible than the
> "staging area" model. (In other words, the user doesn't care how, if,
> or where the program is maintaining state.)

The snapshot concept is totally orthogonal from the staging area
concept. Git works in snapshots, which are frozen images of how the
content tree was at a certain point in time; IOW; a commit.

_How_ that snapshot is created is an entirely different topic, and the
staging area is a tool to create the desired snapshots. The user might
decide to never use that tool (i.e. always run git commit -a), but the
concept of snapshots remain. So, clearly, one concept has absolutely
nothing to do with the other.

>>>We add content snapshots to the index of content (creating
>>>"temporary"--they will be garbage collected eventually if they become
>>>orphans--objects into the store at the same time). We build commits
>>>from those snapshots (in whole or in part, typically only using the
>>>most recent snapshots of new things added to the index) and save those
>>>in the object store with the content and tree objects. Sometimes we
>>>create tag objects to record something special about commits, trees,
>>>and content blobs.
>>
>> The above can be rewritten to use the 'staging area' concept just
>> fine. And I don't think you should say to inexperienced users things
>> like 'tree objects'.
>
> At what time did I say specifically what I tell newbies? I did not do
> so. Please refrain from making that sort of assumption. In any case,
> no, you cannot rewrite that to use "staging area" in place of "index"
> without introducing a different mental model and new concept into the
> text (a model which happens to be incomplete, but not incorrect). That
> minimalist summary was written for the technically-minded people here
> on this list debating the issue of communications with the users--the
> bane of all programmers' lives.

You are mixing useful mental models for the majority of Git users, and
technical implementation details.

You say what you wrote is for technically-minded people, and those
people are not relevant for this discussion, because we are not
talking about the implementation details, we are talking about the
vast majority of Git users, so stop with the red herrings.

The "mental model" of staging area is an area that is used for
preparation for something, and that's *exactly* what the vast majority
of users think of the index as a high-level concept.

> Again, let us keep our argument focused on communications with users.
> Renaming core objects is just going to sow confusion without fixing
> the user communication issue. That's what I meant the first time I
> wrote what I quote directly above and I'm sticking to it.

The vast majority of Git users have absolutely no clue about what's
the index. That's why online documentation uses the term "staging
area", so in fact we would be reducing confusion, by a lot.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Tue, Sep 3, 2013 at 11:45 PM, Drew Northup <n1xim.email@gmail.com> wrote:
> On Thu, Aug 29, 2013 at 6:10 PM, Felipe Contreras
> <felipe.contreras@gmail.com> wrote:
>> On Thu, Aug 29, 2013 at 4:55 PM, Drew Northup <n1xim.email@gmail.com> wrote:
>>> On Thu, Aug 29, 2013 at 2:37 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>>>
>>>>> 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.
>>>>
>>>> "add" is the verb, not "index" (which is a noun that refers
>>>> to the thing that keeps track of what will be written as a tree to
>>>> be committed next).
>>>>
>>>> And it will stay that way.
>
>>> I agree with Junio.
>>
>> All right, you are the only person (presumably other than Junio) that
>> thinks "index" is the right name for what high-level users should be
>> familiar with.
>
> If that were true it would never have gotten that name.

This is fallacious on so many levels. First, there's the concept of
legacy; what the developers of today think, is different than what the
developers of the past did, there might be more, there might be less,
there might be different people, or they might have changed their
mind, so what old developers thought doesn't reflect what the
developers today think. Second, there's this thing called "idea", and
nobody is born with all the ideas in the world and history; ideas
present themselves, and if nobody chose the new term, it might have
been because they simply didn't think about it. Third, they might have
not thought enough about the name in the first place, they thought
"index" was good enough, and could be fixed later if need be. Fourth,
only the developers were involved in picking the name, not users, so
what the vast majority of users thought didn't factor into the name.

So yeah, you are totally wrong.

> "Add" is the verb, as we are adding a snapshot.

Add a snapshot to where? To the repository? To a temporary stash? To
an online location.

The concept of "adding a snapshot" is meaningless.

> New users don't care how that works
> for the most part. Just telling them "it keeps track of it itself" is
> usually good enough.

Everything in a computer "keeps track of it itself", that's what a Von
Neumann computer does, because it has memory. When you type a
character it's kept in track, when you save a file it's kept in track.

Knowing that something "is kept in track" is not useful at all.

> If the user is asking for more detail at that
> point it is probably because he isn't as much interested in how to use
> it as he is in how it works.

Wrong. The user might be interested in knowing what the hell you are
talking about.

Adding what to what, and for what purpose.

> At that point we're better off just
> giving him the actual explanation instead of getting caught up in the
> staging area vs index fight (which seems odd to me as the index
> contains the entries which act as a "staging area"--a superset /
> subset relation).

Wrong. An index has absolutely nothing to do with a staging area. I
already explained multiple times the difference; an index is
information used to quickly find things, a staging area is used to put
things in preparation of something.

Even we are to use the index, the user needs to know what is being
indexed to what, for example, in a book index, words are being indexed
to their page numbers. It turns out we can't do that, because
technically Git does not have an index, but rather a manifest, or a
registry, or more generally, working tree metadata.

But that is not relevant, because we don't need to explain what each
every field in .git/index is, and it's binary format is, all we need
to do is explain what it's used for; it's used to prepare the contents
of the next commit, in other words; it's used as a staging area.

So when you "add to the staging area" you know what you add, to what,
and for what purpose.

>>> We add content snapshots to the index of content (creating
>>> "temporary"--they will be garbage collected eventually if they become
>>> orphans--objects into the store at the same time). We build commits
>>> from those snapshots (in whole or in part, typically only using the
>>> most recent snapshots of new things added to the index) and save those
>>> in the object store with the content and tree objects. Sometimes we
>>> create tag objects to record something special about commits, trees,
>>> and content blobs.
>>>
>>> That's the real model (with some rough edges). Explaining what that
>>> has to do with distributed version control is the hard part.
>>
>> The user doesn't need to know the format of the index, or the packs,
>> in fact, they don't even need to know the index or packs even exist.
>
> I never implied that the end user does need to know these things.
> (Note the use of "We"--as in "we who are having this conversation.")

We who are having this conversation are irrelevant. Stop with the red herrings.

We are talking about the vast majority of users and what's best for *them*.

>> All the user needs to know about this is that there's an area where
>> contents of the next commit are being prepared, and "staging area" is
>> the best name for that mental area. How that area is actually
>> implemented (the index) is not relevant to the user.
>
> Part of what I am arguing is that the mental area doesn't need to
> exist at all. The "staging area" is a part of the index.

Again, the term "index" and the term "staging area" in the English
language have absolutely nothing to do one with the other.

>> Everyone agrees on that, except you, and possibly Junio.
>
> We don't have enough information to say that. Seriously, this is
> nowhere near as certain as climate change.

Show me a single person except you and Junio that doesn't like the
term "staging area". Until you do, the claim remains; virtually
everyone agrees.

-- 
Felipe Contreras

Re: Officially start moving to the term 'staging area'

[Philip Oakley]

From: "Felipe Contreras" <felipe.contreras@gmail.com>
Sent: Sunday, September 08, 2013 2:33 AM
[snip...]
> The snapshot concept is totally orthogonal from the staging area
> concept. Git works in snapshots, which are frozen images of how the
> content tree was at a certain point in time; IOW; a commit.

(I feel that) In most peoples minds the need for a staging area, and the 
use of snapshots, are related. Part of that relationship, often not 
noticed by those folks, is that they are 'orthogonal' to *each other*. 
Thus orthogonality means both un-related, and related at the same time 
(aren't we humans peculiar!). They are cleaved to each other.

When trying to explain staging/index I tend to use the analogy of an old 
style office (I am almost that old) where one has an In tray and an Out 
tray on one's desk (and one parked WIP for lunch time desk tidy), and 
the staging area is the basket at the end marked 'For Filing'. When the 
'For Filing' basket is ready, one called the filing clerk to dictate the 
cover note and away it went, commited to some remote filing repository. 
Oh how things have changed ;-)

>
> _How_ that snapshot is created is an entirely different topic, and the
> staging area is a tool to create the desired snapshots. The user might
> decide to never use that tool (i.e. always run git commit -a), but the
> concept of snapshots remain. So, clearly, one concept has absolutely
> nothing to do with the other.
>

The point would be that we allow a particular snapshot to be selected, 
and that the git commit -a is but one (common) method. Commit -a is like 
jumping in the car for a quick trip to the shops, while the selective 
staging of content is like packing for a holiday.

Re: Officially start moving to the term 'staging area'

[Felipe Contreras]

On Sun, Sep 8, 2013 at 2:49 AM, Philip Oakley <philipoakley@iee.org> wrote:
> From: "Felipe Contreras" <felipe.contreras@gmail.com>
> Sent: Sunday, September 08, 2013 2:33 AM
> [snip...]
>
>> The snapshot concept is totally orthogonal from the staging area
>> concept. Git works in snapshots, which are frozen images of how the
>> content tree was at a certain point in time; IOW; a commit.
>
>
> (I feel that) In most peoples minds the need for a staging area, and the use
> of snapshots, are related. Part of that relationship, often not noticed by
> those folks, is that they are 'orthogonal' to *each other*. Thus
> orthogonality means both un-related, and related at the same time (aren't we
> humans peculiar!). They are cleaved to each other.

Not really. You can argue that a movie is a sequence of snapshots, 24
of them per second, but most people don't think of it that way. You
can also argue that every change you do on a file is a snapshot, but
again, people don't think of it that way. Yes, you can argue that the
index is a snapshot, but it doesn't help to think of it that way. And
if you try to argue that way, then every waking moment is a snapshot,
what is NOT a snapshot?

The useful concept of snapshot is a moment in time stored for
posterity, in that sense a photo is a snapshot, a backup is a
snapshot, and a commit is a snapshot, but the staging area is not,
because it will be gone.

In fact, I just thought of another concept; a draft.

> When trying to explain staging/index I tend to use the analogy of an old
> style office (I am almost that old) where one has an In tray and an Out tray
> on one's desk (and one parked WIP for lunch time desk tidy), and the staging
> area is the basket at the end marked 'For Filing'. When the 'For Filing'
> basket is ready, one called the filing clerk to dictate the cover note and
> away it went, commited to some remote filing repository. Oh how things have
> changed ;-)

But that doesn't work well. You didn't add and remove things for the
'For Filing' as you worked, did you? Even if it did work, I don't
think it would be particularly useful to most people today.

I think a much more fitting analogy is a mail draft; you add and
remove things, change them, review, you can take as much time as you
want, and at the end of the day you can discard the whole thing.
Nothing gets done until you press 'send', which is analogous to
'commit'.

>> _How_ that snapshot is created is an entirely different topic, and the
>> staging area is a tool to create the desired snapshots. The user might
>> decide to never use that tool (i.e. always run git commit -a), but the
>> concept of snapshots remain. So, clearly, one concept has absolutely
>> nothing to do with the other.
>>
>
> The point would be that we allow a particular snapshot to be selected, and
> that the git commit -a is but one (common) method. Commit -a is like jumping
> in the car for a quick trip to the shops, while the selective staging of
> content is like packing for a holiday.

I still don't see it. When you do 'git commit' you don't have an array
of snapshots to choose from, you just have one, and it's not
particularly static, as you can add and remove things from it, so it's
not really a snapshot of your working directory even, because you can
add things that where never there.

And then if the staging area is a snapshot, then what is a commit?
Another snapshot? Then what is the difference between the two? One is
permanent and the other temporary? Well, then saying "snapshot"
wouldn't be enough to describe the staging area, you would need to say
"preliminary snapshot", which doesn't really make sense, as those are
called previews, not snapshots. But why bother with "snapshot", we can
use "preliminary commit". But again, it sounds weird using the word
commit to something that can and is meant to change, unlike git
commits, and incidentally, unlike snapshots.

-- 
Felipe Contreras

Re: [PATCH 1/3] reset: add --stage and --work options

[Felipe Contreras]

On Sun, Sep 8, 2013 at 5:05 PM, Ramkumar Ramachandra <artagnon@gmail.com> wrote:
> Felipe Contreras wrote:
>>
>> @@ -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;
>> +               }
>> +       }
>> +
>
>
> Not making sense at this point. Why does --stage set a reset_type?

Yeah, we would need another patch to cleanup the variable names, but
for now it's better to minimize the changes.

Either way it doesn't matter because Junio is determined to stand
alone versus the rest of the world in this issue.

-- 
Felipe Contreras

Re: [PATCH 1/3] reset: add --stage and --work options

[Ramkumar Ramachandra]

Felipe Contreras wrote:
> Either way it doesn't matter because Junio is determined to stand
> alone versus the rest of the world in this issue.

Which is why he's the maintainer. Send in incremental updates, and he
should be fine.

Re: [PATCH 1/3] reset: add --stage and --work options

[Felipe Contreras]

On Sun, Sep 8, 2013 at 7:15 PM, Ramkumar Ramachandra <artagnon@gmail.com> wrote:
> Felipe Contreras wrote:
>> Either way it doesn't matter because Junio is determined to stand
>> alone versus the rest of the world in this issue.
>
> Which is why he's the maintainer. Send in incremental updates, and he
> should be fine.

I mean he is against the whole "index" -> "staging area" concept
against everybody else, so adding --stage options is out of the
question for him. So he is ignoring the whole patch series.

-- 
Felipe Contreras