{"thread":{"id":"35142","subject":"[PATCH v2 14/14] completion: update 'git reset' new stage options","startedAt":"2013-10-14T22:29:15Z","lastAt":"2013-10-24T23:19:48Z","messageCount":30,"participants":["Felipe Contreras","Eric Sunshine","Junio C Hamano","Matthieu Moy","John Szakmeister","Max Horn","Karsten Blees","Philip Oakley","Andreas Krey"],"isPatch":true,"patchVersion":2,"patchTotal":14},"messages":[{"id":"228954","messageId":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":null,"subject":"[PATCH v2 14/14] completion: update 'git reset' new stage options","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:15Z","receivedAt":"2013-10-14T22:29:15Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras \n---\n contrib/completion/git-completion.bash | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 1dde51f..082f207 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -2231,7 +2231,8 @@ _git_reset ()\n \n \tcase \"$cur\" in\n \t--*)\n-\t\t__gitcomp \"--merge --mixed --hard --soft --patch\"\n+\t\t__gitcomp \"--merge --mixed --hard --soft --patch --keep --merge\n+\t\t\t--stage --no-stage --work --no-work\"\n \t\treturn\n \t\t;;\n \tesac\n-- \n1.8.4-fc\n"},{"id":"228957","messageId":"1381789769-9893-2-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 04/14] grep: add --staged option","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:16Z","receivedAt":"2013-10-14T22:29:16Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Synonym for --cached.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/git-grep.txt | 5 ++++-\n builtin/grep.c | 2 ++\n 2 files changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 8497aa4..9f7899c 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -25,7 +25,7 @@ SYNOPSIS\n \t [-W | --function-context]\n \t [-f ] [-e] \n \t [--and|--or|--not|(|)|-e ...]\n-\t [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | ...]\n+\t [ [--[no-]exclude-standard] [--cached | --staged | --no-index | --untracked] | ...]\n \t [--] [...]\n \n DESCRIPTION\n@@ -60,6 +60,9 @@ OPTIONS\n \tInstead of searching tracked files in the working tree, search\n \tblobs registered in the index file.\n \n+--staged::\n+\tSynonym for `--cached`.\n+\n --no-index::\n \tSearch files in the current directory that is not managed by Git.\n \ndiff --git a/builtin/grep.c b/builtin/grep.c\nindex d3b3b1d..b953911 100644\n--- a/builtin/grep.c\n+++ b/builtin/grep.c\n@@ -640,6 +640,8 @@ int cmd_grep(int argc, const char **argv, const char *prefix)\n \tstruct option options[] = {\n \t\tOPT_BOOLEAN(0, \"cached\", &cached,\n \t\t\tN_(\"search in index instead of in the work tree\")),\n+\t\tOPT_BOOLEAN(0, \"staged\", &cached,\n+\t\t\tN_(\"search in index instead of in the work tree\")),\n \t\tOPT_NEGBIT(0, \"no-index\", &use_index,\n \t\t\t N_(\"find in contents not managed by git\"), 1),\n \t\tOPT_BOOLEAN(0, \"untracked\", &untracked,\n-- \n1.8.4-fc\n"},{"id":"228956","messageId":"1381789769-9893-3-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 07/14] stash: add --stage to pop and apply","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:17Z","receivedAt":"2013-10-14T22:29:17Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Synonym of --index.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/git-stash.txt | 8 ++++----\n git-stash.sh | 4 ++--\n 2 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 21a01c2..5fdaa35 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n 'git stash' list []\n 'git stash' show []\n 'git stash' drop [-q|--quiet] []\n-'git stash' ( pop | apply ) [--index] [-q|--quiet] []\n+'git stash' ( pop | apply ) [--index|--stage] [-q|--quiet] []\n 'git stash' branch []\n 'git stash' [save [-p|--patch] [-k|--[no-]keep-index|--[no-]stage] [-q|--quiet]\n \t [-u|--include-untracked] [-a|--all] []]\n@@ -96,7 +96,7 @@ show []::\n \tit will accept any format known to 'git diff' (e.g., `git stash show\n \t-p stash@{1}` to view the second most recent stash in patch form).\n \n-pop [--index] [-q|--quiet] []::\n+pop [--index|--stage] [-q|--quiet] []::\n \n \tRemove a single stashed state from the stash list and apply it\n \ton top of the current working tree state, i.e., do the inverse\n@@ -110,12 +110,12 @@ and call `git stash drop` manually afterwards.\n If the `--index` option is used, then tries to reinstate not only the working\n tree's changes, but also the index's ones. However, this can fail, when you\n have conflicts (which are stored in the index, where you therefore can no\n-longer apply the changes as they were originally).\n+longer apply the changes as they were originally). `--stage` is a synonym.\n +\n When no `` is given, `stash@{0}` is assumed, otherwise `` must\n be a reference of the form `stash@{}`.\n \n-apply [--index] [-q|--quiet] []::\n+apply [--index|--stage] [-q|--quiet] []::\n \n \tLike `pop`, but do not remove the state from the stash list. Unlike `pop`,\n \t`` may be any commit that looks like a commit created by\ndiff --git a/git-stash.sh b/git-stash.sh\nindex 47220d0..e2eb8dc 100755\n--- a/git-stash.sh\n+++ b/git-stash.sh\n@@ -5,7 +5,7 @@ dashless=$(basename \"$0\" | sed -e 's/-/ /')\n USAGE=\"list []\n or: $dashless show []\n or: $dashless drop [-q|--quiet] []\n- or: $dashless ( pop | apply ) [--index] [-q|--quiet] []\n+ or: $dashless ( pop | apply ) [--index|--stage] [-q|--quiet] []\n or: $dashless branch []\n or: $dashless [save [--patch] [-k|--[no-]keep-index|--[no-]stage] [-q|--quiet]\n \t\t [-u|--include-untracked] [-a|--all] []]\n@@ -373,7 +373,7 @@ parse_flags_and_rev()\n \t\t\t-q|--quiet)\n \t\t\t\tGIT_QUIET=-t\n \t\t\t;;\n-\t\t\t--index)\n+\t\t\t--index|--stage)\n \t\t\t\tINDEX_OPTION=--index\n \t\t\t;;\n \t\t\t-*)\n-- \n1.8.4-fc\n"},{"id":"228955","messageId":"1381789769-9893-4-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:18Z","receivedAt":"2013-10-14T22:29:18Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we should move\naway from the name \"the index\".\n\nIt has been discussed many times in the past that 'index' is not an\nappropriate description for what the high-level user does with it, and\nit has been agreed that 'staging area' is the best term.\n\nThe term 'staging area' is more intuitive for newcomers which are more\nfamiliar with English than with Git, and it seems to be a\nstraightforward mental notion for people with different mother tongues.\n\nIn fact it is so intuitive that it's used already in a lot online\ndocumentation, and the people that do teach Git professionally use this\nterm, because it's easier for many kinds of audiences to grasp.\n\nThe meaning of the words 'cache' and 'index' doesn't represent correctly\nthe mental model of the high-level user:\n\ncache: a 'cache' is a place for easier access; a squirrel caches nuts\nso it doesn't have to go looking for them in the future when it might\nbe much more difficult. Git porcelain is not using the staging area\nfor easier future access; it's not a cache.\n\nindex: an 'index' is a guide of pointers to something else; a book\nindex has a list of entries so the reader can locate information\neasily without having to go through the whole book. Git porcelain is\nnot using the staging area to find out entries quicker; it's not an\nindex.\n\nstage: a 'stage' is a special area designated for convenience in order\nfor some activity to take place; an orator would prepare a stage in\norder for her speak to be successful, otherwise many people might not\nbe able to hear, or see her. Git porcelain is using the staging area\nprecisely as a special area to be separated from the working directory\nfor convenience.\n\nThe term 'stage' is a good noun itself, but also 'staging area', it\nhas a good verb; 'to stage', and a nice past-participle; 'staged'.\n\nThe first step in moving Git towards this term, is first to add --stage\noptions for every command that uses --index or --cache. However, there's\na problem with the 'git apply' command, because it treats --index and\n--cache differently. Different solutions were proposed, including a\nspecial --stage-only option, however, I think the best solution is a\n--[no-]work option to specify if the working directory should be touched\nor not, so --index becomes --staged, and --cached becomes --staged\n--no-work.\n\nIn addition, the 'git stage' command can be extended so the staging area\ncan be brought closer to the user, like other important Git concepts,\nlike 'git branch, 'git tag', and 'git remote'. For example, the command\n'git stage edit' (which allows the user to edit directly the diff from\nHEAD to the staging area) can have a home, where previously there was no\nplace. It would become natural then to do 'git stage diff', and then\n'git stage edit' (to edit the previous diff).\n\nAfter adding the new --stage options and making sure no functionality is\nlost, they can become the recommended ones in the documentation,\neventually, the old ones get deprecated, and eventually obsoleted.\n\nAlso, the documentation would need to be updated to replace many\ninstances of 'the index', with 'the staging area' in porcelain commands.\n\nMoreover, the --stage and --work options also make sense for 'git\nreset', and after these options are added, the complicated table to\nexplain the different behaviors between --soft, --mixed, and --hard\nbecomes so simple it's not needed any more:\n\n working stage HEAD target working stage HEAD\n ----------------------------------------------------\n A B C D --no-stage A B D\n\t\t\t\t--stage A D D\n\t\t\t\t--work D D D\n\n working stage HEAD target working stage HEAD\n ----------------------------------------------------\n A B C C --no-stage A B C\n\t\t\t\t--stage A C C\n\t\t\t\t--work C C C\n\n working stage HEAD target working stage HEAD\n ----------------------------------------------------\n B B C D --no-stage B B D\n\t\t\t\t--stage B D D\n\t\t\t\t--work D D D\n\n working stage HEAD target working stage HEAD\n ----------------------------------------------------\n B B C C --no-stage B B C\n\t\t\t\t--stage B C C\n\t\t\t\t--work C C C\n\n working stage HEAD target working stage HEAD\n ----------------------------------------------------\n B C C D --no-stage B C D\n\t\t\t\t--stage B D D\n\t\t\t\t--work D D D\n\n working stage HEAD target working stage HEAD\n ----------------------------------------------------\n B C C C --no-stage B C C\n\t\t\t\t--stage B C C\n\t\t\t\t--work C C C\n\nIt might be possible to do 'git reset --no-stage --work', to reset the\nworking directory, but leave the staging area alone.\n\nFor more reference about the previous discussions:\n\nhttp://thread.gmane.org/gmane.comp.version-control.git/197111\nhttp://thread.gmane.org/gmane.comp.version-control.git/166675\nhttp://thread.gmane.org/gmane.comp.version-control.git/115666\n\nChanges since v1:\n\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex 6167061..95f5485 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -9,10 +9,10 @@ git-apply - Apply a patch to files and/or to the index\n SYNOPSIS\n --------\n [verse]\n-'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--3way]\n+'git apply' [--stat] [--numstat] [--summary] [--check] [--index|--stage] [--3way]\n \t [--apply] [--no-add] [--build-fake-ancestor=] [-R | --reverse]\n \t [--allow-binary-replacement | --binary] [--reject] [-z]\n-\t [-p] [-C] [--inaccurate-eof] [--recount] [--cached|--staged]\n+\t [-p] [-C] [--inaccurate-eof] [--recount] [--cached]\n \t [--ignore-space-change | --ignore-whitespace ]\n \t [--whitespace=(nowarn|warn|fix|error|error-all)]\n \t [--exclude=] [--include=] [--directory=]\n@@ -67,7 +67,7 @@ OPTIONS\n \tup-to-date, it is flagged as an error. This flag also\n \tcauses the index file to be updated.\n \n---staged::\n+--stage::\n \tSynonym for --index.\n \n --cached::\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex b4066fd..5fdaa35 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -54,7 +54,7 @@ save [-p|--patch] [--[no-]keep-index|--[no-]stage] [-u|--include-untracked] [-a|\n \tsubcommand from making an unwanted stash.\n +\n If the `--keep-index` option is used, all changes already added to the\n-index are left intact. Same with `--no-stage`, which is a snynonym.\n+index are left intact. Same with `--no-stage`, which is a synonym.\n +\n If the `--include-untracked` option is used, all untracked files are also\n stashed and then cleaned up with `git clean`, leaving the working directory\ndiff --git a/builtin/stage.c b/builtin/stage.c\nindex d3c58d5..f537c1d 100644\n--- a/builtin/stage.c\n+++ b/builtin/stage.c\n@@ -13,6 +13,7 @@\n static const char *const stage_usage[] = {\n \tN_(\"git stage [options] [--] ...\"),\n \tN_(\"git stage add [options] [--] ...\"),\n+\tN_(\"git stage apply [options] [...]\"),\n \tN_(\"git stage reset [-q|--patch] [--] ...\"),\n \tN_(\"git stage diff [options] [ [--] ...\"),\n \tN_(\"git stage rm [options] [--] ...\"),\n\nFelipe Contreras (14):\n Add proper 'stage' command\n stage: add edit command\n diff: document --staged\n grep: add --staged option\n rm: add --staged option\n stash: add --stage option to save\n stash: add --stage to pop and apply\n submodule: add --staged options\n apply: add --stage option\n apply: add --work, --no-work options\n completion: update --staged options\n reset: add --stage and --work options\n reset: allow --keep with --stage\n completion: update 'git reset' new stage options\n\n Documentation/git-apply.txt | 11 ++-\n Documentation/git-diff.txt | 4 +-\n Documentation/git-grep.txt | 5 +-\n Documentation/git-reset.txt | 8 +++\n Documentation/git-rm.txt | 5 +-\n Documentation/git-stage.txt | 50 +++++++++++--\n Documentation/git-stash.txt | 14 ++--\n Documentation/git-submodule.txt | 8 ++-\n Makefile | 2 +-\n builtin.h | 1 +\n builtin/apply.c | 7 ++\n builtin/grep.c | 2 +\n builtin/reset.c | 27 +++++++\n builtin/rm.c | 1 +\n builtin/stage.c | 127 +++++++++++++++++++++++++++++++++\n contrib/completion/git-completion.bash | 39 ++++++++--\n git-stash.sh | 12 +++-\n git-submodule.sh | 10 +--\n git.c | 2 +-\n 19 files changed, 298 insertions(+), 37 deletions(-)\n create mode 100644 builtin/stage.c\n\n-- \n1.8.4-fc\n"},{"id":"228958","messageId":"1381789769-9893-5-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 10/14] apply: add --work, --no-work options","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:19Z","receivedAt":"2013-10-14T22:29:19Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"'git apply', 'git apply --index', 'git apply --cached' do different\nthings, but what they do is not precisely clear, specially since no\nother commands has similar distinctions.\n\nWith --no-work (--work being the default), it's clear what the option\nwould do; modify, or not, the working directory.\n\nSo, --work (the default), doesn't cause any changes, and --no-work\nenables the current --cache if used with --index.\n\nEventually --work might replace --cache, if these options are\nstandarized in the whole git toolset.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/git-apply.txt | 6 +++++-\n builtin/apply.c | 5 +++++\n 2 files changed, 10 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex 8c047ef..95f5485 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -16,7 +16,7 @@ SYNOPSIS\n \t [--ignore-space-change | --ignore-whitespace ]\n \t [--whitespace=(nowarn|warn|fix|error|error-all)]\n \t [--exclude=] [--include=] [--directory=]\n-\t [--verbose] [...]\n+\t [--verbose] [--no-work] [...]\n \n DESCRIPTION\n -----------\n@@ -75,6 +75,10 @@ OPTIONS\n \tcached data, apply the patch, and store the result in the index\n \twithout using the working tree. This implies `--index`.\n \n+--[no-]work::\n+\tApply a patch with or without touching the working tree, essentially\n+\t`--no-work` plus `--index` are the equivalent of `--cached`.\n+\n -3::\n --3way::\n \tWhen the patch does not apply cleanly, fall back on 3-way merge if\ndiff --git a/builtin/apply.c b/builtin/apply.c\nindex 42b5a4b..a3dd89d 100644\n--- a/builtin/apply.c\n+++ b/builtin/apply.c\n@@ -4350,6 +4350,7 @@ int cmd_apply(int argc, const char **argv, const char *prefix_)\n \tint errs = 0;\n \tint is_not_gitdir = !startup_info->have_repository;\n \tint force_apply = 0;\n+\tint work = 1;\n \n \tconst char *whitespace_option = NULL;\n \n@@ -4381,6 +4382,8 @@ int cmd_apply(int argc, const char **argv, const char *prefix_)\n \t\t\tN_(\"make sure the patch is applicable to the current index\")),\n \t\tOPT_BOOLEAN(0, \"cached\", &cached,\n \t\t\tN_(\"apply a patch without touching the working tree\")),\n+\t\tOPT_BOOLEAN(0, \"work\", &work,\n+\t\t\tN_(\"modify the working tree\")),\n \t\tOPT_BOOLEAN(0, \"apply\", &force_apply,\n \t\t\tN_(\"also apply the patch (use with --stat/--summary/--check)\")),\n \t\tOPT_BOOL('3', \"3way\", &threeway,\n@@ -4433,6 +4436,8 @@ int cmd_apply(int argc, const char **argv, const char *prefix_)\n \targc = parse_options(argc, argv, prefix, builtin_apply_options,\n \t\t\tapply_usage, 0);\n \n+\tif (check_index && !work)\n+\t\tcached = 1;\n \tif (apply_with_reject && threeway)\n \t\tdie(\"--reject and --3way cannot be used together.\");\n \tif (cached && threeway)\n-- \n1.8.4-fc\n"},{"id":"228959","messageId":"1381789769-9893-6-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 01/14] Add proper 'stage' command","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:20Z","receivedAt":"2013-10-14T22:29:20Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras \n---\n Documentation/git-stage.txt | 45 +++++++++++++++++++++++++----\n Makefile | 2 +-\n builtin.h | 1 +\n builtin/stage.c | 52 ++++++++++++++++++++++++++++++++++\n contrib/completion/git-completion.bash | 24 +++++++++++++++-\n git.c | 2 +-\n 6 files changed, 118 insertions(+), 8 deletions(-)\n create mode 100644 builtin/stage.c\n\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex ba3fe0d..318bf45 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -3,20 +3,55 @@ git-stage(1)\n \n NAME\n ----\n-git-stage - Add file contents to the staging area\n+git-stage - manage the staging area\n \n \n SYNOPSIS\n --------\n [verse]\n-'git stage' args...\n-\n+'git stage' [options] [--] [...]\n+'git stage add' [options] [--] [...]\n+'git stage reset' [-q|--patch] [--] [...]\n+'git stage diff' [options] [] [--] [...]\n+'git stage rm' [options] [--] [...]\n+'git stage apply' [options] [--] [...]\n \n DESCRIPTION\n -----------\n \n-This is a synonym for linkgit:git-add[1]. Please refer to the\n-documentation of that command.\n+\n+COMMANDS\n+--------\n+\n+With no arguments, it's a synonym for linkgit:git-add[1].\n+\n+'add'::\n+\n+Adds file contents to the staging area. See linkgit:git-add[1].\n+\n+'reset'::\n+\n+Resets the staging area. See linkgit:git-reset[1].\n+\n+'diff'::\n+\n+View the changes you staged for the next commit. See linkgit:git-diff[1] --staged.\n+\n+'rm'::\n+\n+Remove files from the staging area only. See linkgit:git-rm[1] --staged.\n+\n+'apply'::\n+\n+Apply a patch to the staging area. See linkgit:git-rm[1] --staged.\n+\n+SEE ALSO\n+--------\n+linkgit:git-add[1]\n+linkgit:git-reset[1]\n+linkgit:git-diff[1]\n+linkgit:git-rm[1]\n+linkgit:git-apply[1]\n \n GIT\n ---\ndiff --git a/Makefile b/Makefile\nindex 3588ca1..1f7ddf3 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -598,7 +598,6 @@ BUILT_INS += git-merge-subtree$X\n BUILT_INS += git-peek-remote$X\n BUILT_INS += git-repo-config$X\n BUILT_INS += git-show$X\n-BUILT_INS += git-stage$X\n BUILT_INS += git-status$X\n BUILT_INS += git-whatchanged$X\n \n@@ -982,6 +981,7 @@ BUILTIN_OBJS += builtin/send-pack.o\n BUILTIN_OBJS += builtin/shortlog.o\n BUILTIN_OBJS += builtin/show-branch.o\n BUILTIN_OBJS += builtin/show-ref.o\n+BUILTIN_OBJS += builtin/stage.o\n BUILTIN_OBJS += builtin/stripspace.o\n BUILTIN_OBJS += builtin/symbolic-ref.o\n BUILTIN_OBJS += builtin/tag.o\ndiff --git a/builtin.h b/builtin.h\nindex 8afa2de..baf3a0f 100644\n--- a/builtin.h\n+++ b/builtin.h\n@@ -113,6 +113,7 @@ extern int cmd_send_pack(int argc, const char **argv, const char *prefix);\n extern int cmd_shortlog(int argc, const char **argv, const char *prefix);\n extern int cmd_show(int argc, const char **argv, const char *prefix);\n extern int cmd_show_branch(int argc, const char **argv, const char *prefix);\n+extern int cmd_stage(int argc, const char **argv, const char *prefix);\n extern int cmd_status(int argc, const char **argv, const char *prefix);\n extern int cmd_stripspace(int argc, const char **argv, const char *prefix);\n extern int cmd_symbolic_ref(int argc, const char **argv, const char *prefix);\ndiff --git a/builtin/stage.c b/builtin/stage.c\nnew file mode 100644\nindex 0000000..3023d17\n--- /dev/null\n+++ b/builtin/stage.c\n@@ -0,0 +1,52 @@\n+/*\n+ * 'git stage' builtin command\n+ *\n+ * Copyright (C) 2013 Felipe Contreras\n+ */\n+\n+#include \"builtin.h\"\n+#include \"parse-options.h\"\n+\n+static const char *const stage_usage[] = {\n+\tN_(\"git stage [options] [--] ...\"),\n+\tN_(\"git stage add [options] [--] ...\"),\n+\tN_(\"git stage reset [-q|--patch] [--] ...\"),\n+\tN_(\"git stage diff [options] [ [--] ...\"),\n+\tN_(\"git stage rm [options] [--] ...\"),\n+\tNULL\n+};\n+\n+int cmd_stage(int argc, const char **argv, const char *prefix)\n+{\n+\tstruct option options[] = { OPT_END() };\n+\n+\targc = parse_options(argc, argv, prefix, options, stage_usage,\n+\t\t\tPARSE_OPT_KEEP_ARGV0 | PARSE_OPT_KEEP_UNKNOWN | PARSE_OPT_KEEP_DASHDASH);\n+\n+\tif (argc > 1) {\n+\t\tif (!strcmp(argv[1], \"add\"))\n+\t\t\treturn cmd_add(argc - 1, argv + 1, prefix);\n+\t\tif (!strcmp(argv[1], \"reset\"))\n+\t\t\treturn cmd_reset(argc - 1, argv + 1, prefix);\n+\t\tif (!strcmp(argv[1], \"diff\")) {\n+\t\t\targv[0] = \"diff\";\n+\t\t\targv[1] = \"--staged\";\n+\n+\t\t\treturn cmd_diff(argc, argv, prefix);\n+\t\t}\n+\t\tif (!strcmp(argv[1], \"rm\")) {\n+\t\t\targv[0] = \"rm\";\n+\t\t\targv[1] = \"--cached\";\n+\n+\t\t\treturn cmd_rm(argc, argv, prefix);\n+\t\t}\n+\t\tif (!strcmp(argv[1], \"apply\")) {\n+\t\t\targv[0] = \"apply\";\n+\t\t\targv[1] = \"--cached\";\n+\n+\t\t\treturn cmd_apply(argc, argv, prefix);\n+\t\t}\n+\t}\n+\n+\treturn cmd_add(argc, argv, prefix);\n+}\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 5da920e..8cf26e2 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -1691,7 +1691,29 @@ _git_send_email ()\n \n _git_stage ()\n {\n-\t_git_add\n+\t__git_has_doubledash && return\n+\n+\tlocal subcommands=\"add reset diff rm apply\"\n+\tlocal subcommand=\"$(__git_find_on_cmdline \"$subcommands\")\"\n+\tif [ -z \"$subcommand\" ]; then\n+\t\t__gitcomp \"$subcommands\"\n+\t\treturn\n+\tfi\n+\n+\tcase \"$subcommand\" in\n+\tadd)\n+\t\t_git_add;;\n+\treset)\n+\t\t_git_reset;;\n+\tdiff)\n+\t\t_git_diff;;\n+\trm)\n+\t\t_git_rm;;\n+\tapply)\n+\t\t_git_apply;;\n+\t*)\n+\t\t_git_add;\n+\tesac\n }\n \n __git_config_get_set_variables ()\ndiff --git a/git.c b/git.c\nindex 2025f77..0e639aa 100644\n--- a/git.c\n+++ b/git.c\n@@ -409,7 +409,7 @@ static void handle_internal_command(int argc, const char **argv)\n \t\t{ \"show\", cmd_show, RUN_SETUP },\n \t\t{ \"show-branch\", cmd_show_branch, RUN_SETUP },\n \t\t{ \"show-ref\", cmd_show_ref, RUN_SETUP },\n-\t\t{ \"stage\", cmd_add, RUN_SETUP | NEED_WORK_TREE },\n+\t\t{ \"stage\", cmd_stage, RUN_SETUP | NEED_WORK_TREE },\n \t\t{ \"status\", cmd_status, RUN_SETUP | NEED_WORK_TREE },\n \t\t{ \"stripspace\", cmd_stripspace },\n \t\t{ \"symbolic-ref\", cmd_symbolic_ref, RUN_SETUP },\n-- \n1.8.4-fc\n"},{"id":"228960","messageId":"1381789769-9893-7-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 09/14] apply: add --stage option","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:21Z","receivedAt":"2013-10-14T22:29:21Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Synonym for --index.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/git-apply.txt | 5 ++++-\n builtin/apply.c | 2 ++\n 2 files changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex f605327..8c047ef 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -9,7 +9,7 @@ git-apply - Apply a patch to files and/or to the index\n SYNOPSIS\n --------\n [verse]\n-'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--3way]\n+'git apply' [--stat] [--numstat] [--summary] [--check] [--index|--stage] [--3way]\n \t [--apply] [--no-add] [--build-fake-ancestor=] [-R | --reverse]\n \t [--allow-binary-replacement | --binary] [--reject] [-z]\n \t [-p] [-C] [--inaccurate-eof] [--recount] [--cached]\n@@ -67,6 +67,9 @@ OPTIONS\n \tup-to-date, it is flagged as an error. This flag also\n \tcauses the index file to be updated.\n \n+--stage::\n+\tSynonym for --index.\n+\n --cached::\n \tApply a patch without touching the working tree. Instead take the\n \tcached data, apply the patch, and store the result in the index\ndiff --git a/builtin/apply.c b/builtin/apply.c\nindex 50912c9..42b5a4b 100644\n--- a/builtin/apply.c\n+++ b/builtin/apply.c\n@@ -4377,6 +4377,8 @@ int cmd_apply(int argc, const char **argv, const char *prefix_)\n \t\t\tN_(\"instead of applying the patch, see if the patch is applicable\")),\n \t\tOPT_BOOLEAN(0, \"index\", &check_index,\n \t\t\tN_(\"make sure the patch is applicable to the current index\")),\n+\t\tOPT_BOOLEAN(0, \"stage\", &check_index,\n+\t\t\tN_(\"make sure the patch is applicable to the current index\")),\n \t\tOPT_BOOLEAN(0, \"cached\", &cached,\n \t\t\tN_(\"apply a patch without touching the working tree\")),\n \t\tOPT_BOOLEAN(0, \"apply\", &force_apply,\n-- \n1.8.4-fc\n"},{"id":"228962","messageId":"1381789769-9893-8-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 03/14] diff: document --staged","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:22Z","receivedAt":"2013-10-14T22:29:22Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Synonym for --cached.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/git-diff.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 78d6d50..646e5cd 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -10,7 +10,7 @@ SYNOPSIS\n --------\n [verse]\n 'git diff' [options] [] [--] [...]\n-'git diff' [options] --cached [] [--] [...]\n+'git diff' [options] [--cached|--staged] [] [--] [...]\n 'git diff' [options] [--] [...]\n 'git diff' [options] \n 'git diff' [options] [--no-index] [--] \n@@ -33,7 +33,7 @@ If exactly two paths are given and at least one points outside\n the current repository, 'git diff' will compare the two files /\n directories. This behavior can be forced by --no-index.\n \n-'git diff' [--options] --cached [] [--] [...]::\n+'git diff' [--options] [--cached|--staged] [] [--] [...]::\n \n \tThis form is to view the changes you staged for the next\n \tcommit relative to the named . Typically you\n-- \n1.8.4-fc\n"},{"id":"228963","messageId":"1381789769-9893-9-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 05/14] rm: add --staged option","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:23Z","receivedAt":"2013-10-14T22:29:23Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Synonym for --cached.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/git-rm.txt | 5 ++++-\n builtin/rm.c | 1 +\n 2 files changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt\nindex 1d876c2..156b40d 100644\n--- a/Documentation/git-rm.txt\n+++ b/Documentation/git-rm.txt\n@@ -8,7 +8,7 @@ git-rm - Remove files from the working tree and from the index\n SYNOPSIS\n --------\n [verse]\n-'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] ...\n+'git rm' [-f | --force] [-n] [-r] [--cached | --staged] [--ignore-unmatch] [--quiet] [--] ...\n \n DESCRIPTION\n -----------\n@@ -60,6 +60,9 @@ OPTIONS\n \tWorking tree files, whether modified or not, will be\n \tleft alone.\n \n+--staged::\n+\tSynonym for --cached.\n+\n --ignore-unmatch::\n \tExit with a zero status even if no files matched.\n \ndiff --git a/builtin/rm.c b/builtin/rm.c\nindex 0df0b4d..919911f 100644\n--- a/builtin/rm.c\n+++ b/builtin/rm.c\n@@ -268,6 +268,7 @@ static struct option builtin_rm_options[] = {\n \tOPT__DRY_RUN(&show_only, N_(\"dry run\")),\n \tOPT__QUIET(&quiet, N_(\"do not list removed files\")),\n \tOPT_BOOLEAN( 0 , \"cached\", &index_only, N_(\"only remove from the index\")),\n+\tOPT_BOOLEAN( 0 , \"staged\", &index_only, N_(\"only remove from the index\")),\n \tOPT__FORCE(&force, N_(\"override the up-to-date check\")),\n \tOPT_BOOLEAN('r', NULL, &recursive, N_(\"allow recursive removal\")),\n \tOPT_BOOLEAN( 0 , \"ignore-unmatch\", &ignore_unmatch,\n-- \n1.8.4-fc\n"},{"id":"228964","messageId":"1381789769-9893-10-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 02/14] stage: add edit command","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:24Z","receivedAt":"2013-10-14T22:29:24Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras \n---\n Documentation/git-stage.txt | 5 +++\n builtin/stage.c | 75 ++++++++++++++++++++++++++++++++++\n contrib/completion/git-completion.bash | 4 +-\n 3 files changed, 83 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex 318bf45..3e52a66 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -15,6 +15,7 @@ SYNOPSIS\n 'git stage diff' [options] [] [--] [...]\n 'git stage rm' [options] [--] [...]\n 'git stage apply' [options] [--] [...]\n+'git stage edit'\n \n DESCRIPTION\n -----------\n@@ -45,6 +46,10 @@ Remove files from the staging area only. See linkgit:git-rm[1] --staged.\n \n Apply a patch to the staging area. See linkgit:git-rm[1] --staged.\n \n+'edit'::\n+\n+Manually edit the staging area (as a diff).\n+\n SEE ALSO\n --------\n linkgit:git-add[1]\ndiff --git a/builtin/stage.c b/builtin/stage.c\nindex 3023d17..f537c1d 100644\n--- a/builtin/stage.c\n+++ b/builtin/stage.c\n@@ -6,16 +6,88 @@\n \n #include \"builtin.h\"\n #include \"parse-options.h\"\n+#include \"diff.h\"\n+#include \"diffcore.h\"\n+#include \"revision.h\"\n \n static const char *const stage_usage[] = {\n \tN_(\"git stage [options] [--] ...\"),\n \tN_(\"git stage add [options] [--] ...\"),\n+\tN_(\"git stage apply [options] [...]\"),\n \tN_(\"git stage reset [-q|--patch] [--] ...\"),\n \tN_(\"git stage diff [options] [ [--] ...\"),\n \tN_(\"git stage rm [options] [--] ...\"),\n \tNULL\n };\n \n+static int do_reset(const char *prefix)\n+{\n+\tconst char *argv[] = { \"reset\", \"--quiet\", NULL };\n+\treturn cmd_reset(2, argv, prefix);\n+}\n+\n+static int do_apply(const char *file, const char *prefix)\n+{\n+\tconst char *argv[] = { \"apply\", \"--recount\", \"--cached\", file, NULL };\n+\treturn cmd_apply(4, argv, prefix);\n+}\n+\n+static int edit(int argc, const char **argv, const char *prefix)\n+{\n+\tchar *file = git_pathdup(\"STAGE_EDIT.patch\");\n+\tint out;\n+\tstruct rev_info rev;\n+\tint ret = 0;\n+\tstruct stat st;\n+\n+\tread_cache();\n+\n+\tinit_revisions(&rev, prefix);\n+\trev.diffopt.context = 7;\n+\n+\targc = setup_revisions(argc, argv, &rev, NULL);\n+\tadd_head_to_pending(&rev);\n+\tif (!rev.pending.nr) {\n+\t\tstruct tree *tree;\n+\t\ttree = lookup_tree(EMPTY_TREE_SHA1_BIN);\n+\t\tadd_pending_object(&rev, &tree->object, \"HEAD\");\n+\t}\n+\n+\trev.diffopt.output_format = DIFF_FORMAT_PATCH;\n+\trev.diffopt.use_color = 0;\n+\tDIFF_OPT_SET(&rev.diffopt, IGNORE_DIRTY_SUBMODULES);\n+\n+\tout = open(file, O_CREAT | O_WRONLY, 0666);\n+\tif (out < 0)\n+\t\tdie(_(\"Could not open '%s' for writing.\"), file);\n+\trev.diffopt.file = xfdopen(out, \"w\");\n+\trev.diffopt.close_file = 1;\n+\n+\tif (run_diff_index(&rev, 1))\n+\t\tdie(_(\"Could not write patch\"));\n+\tif (launch_editor(file, NULL, NULL))\n+\t\texit(1);\n+\n+\tif (stat(file, &st))\n+\t\tdie_errno(_(\"Could not stat '%s'\"), file);\n+\n+\tret = do_reset(prefix);\n+\tif (ret)\n+\t\tgoto leave;\n+\n+\tif (!st.st_size)\n+\t\tgoto leave;\n+\n+\tret = do_apply(file, prefix);\n+\tif (ret)\n+\t\tgoto leave;\n+\n+leave:\n+\tunlink(file);\n+\tfree(file);\n+\treturn ret;\n+}\n+\n int cmd_stage(int argc, const char **argv, const char *prefix)\n {\n \tstruct option options[] = { OPT_END() };\n@@ -46,6 +118,9 @@ int cmd_stage(int argc, const char **argv, const char *prefix)\n \n \t\t\treturn cmd_apply(argc, argv, prefix);\n \t\t}\n+\t\tif (!strcmp(argv[1], \"edit\")) {\n+\t\t\treturn edit(argc - 1, argv + 1, prefix);\n+\t\t}\n \t}\n \n \treturn cmd_add(argc, argv, prefix);\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 8cf26e2..2b81e78 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -1693,7 +1693,7 @@ _git_stage ()\n {\n \t__git_has_doubledash && return\n \n-\tlocal subcommands=\"add reset diff rm apply\"\n+\tlocal subcommands=\"add reset diff rm apply edit\"\n \tlocal subcommand=\"$(__git_find_on_cmdline \"$subcommands\")\"\n \tif [ -z \"$subcommand\" ]; then\n \t\t__gitcomp \"$subcommands\"\n@@ -1711,6 +1711,8 @@ _git_stage ()\n \t\t_git_rm;;\n \tapply)\n \t\t_git_apply;;\n+\tedit)\n+\t\t;;\n \t*)\n \t\t_git_add;\n \tesac\n-- \n1.8.4-fc\n"},{"id":"228965","messageId":"1381789769-9893-11-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 13/14] reset: allow --keep with --stage","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:25Z","receivedAt":"2013-10-14T22:29:25Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras \n---\n Documentation/git-reset.txt | 2 +-\n builtin/reset.c | 13 ++++++++++---\n 2 files changed, 11 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex 5cd75a8..a1419c9 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n 'git reset' [-q] [] [--] ...\n 'git reset' (--patch | -p) [] [--] [...]\n 'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] []\n-'git reset' [--stage | --work] [-q] []\n+'git reset' [--stage | --work | --keep] [-q] []\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/reset.c b/builtin/reset.c\nindex fbc1abc..dde03a7 100644\n--- a/builtin/reset.c\n+++ b/builtin/reset.c\n@@ -23,7 +23,7 @@\n \n static const char * const git_reset_usage[] = {\n \tN_(\"git reset [--mixed | --soft | --hard | --merge | --keep] [-q] []\"),\n-\tN_(\"git reset [--stage | --work] [-q] []\"),\n+\tN_(\"git reset [--stage | --work | --keep] [-q] []\"),\n \tN_(\"git reset [-q] [--] ...\"),\n \tN_(\"git reset --patch [] [--] [...]\"),\n \tNULL\n@@ -295,8 +295,15 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t}\n \n \tif (stage >= 0 || working_tree >= 0) {\n-\t\tif (reset_type != NONE)\n+\t\tint keep = 0;\n+\n+\t\tif (reset_type == KEEP) {\n+\t\t\tif (working_tree == 1)\n+\t\t\t\tdie(_(\"--keep is incompatible with --work\"));\n+\t\t\tkeep = 1;\n+\t\t} else if (reset_type != NONE) {\n \t\t\tdie(_(\"--{stage,work} are incompatible with --{hard,mixed,soft,merge}\"));\n+\t\t}\n \n \t\tif (working_tree == 1) {\n \t\t\tif (stage == 0)\n@@ -304,7 +311,7 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\t\treset_type = HARD;\n \t\t} else {\n \t\t\tif (stage == 1)\n-\t\t\t\treset_type = NONE;\n+\t\t\t\treset_type = keep ? KEEP : NONE;\n \t\t\telse\n \t\t\t\treset_type = SOFT;\n \t\t}\n-- \n1.8.4-fc\n"},{"id":"228966","messageId":"1381789769-9893-12-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 12/14] reset: add --stage and --work options","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:26Z","receivedAt":"2013-10-14T22:29:26Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras \n---\n Documentation/git-reset.txt | 8 ++++++++\n builtin/reset.c | 20 ++++++++++++++++++++\n 2 files changed, 28 insertions(+)\n\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex f445cb3..5cd75a8 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -11,6 +11,7 @@ SYNOPSIS\n 'git reset' [-q] [] [--] ...\n 'git reset' (--patch | -p) [] [--] [...]\n 'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] []\n+'git reset' [--stage | --work] [-q] []\n \n DESCRIPTION\n -----------\n@@ -81,6 +82,13 @@ but carries forward unmerged index entries.\n \tdifferent between and HEAD.\n \tIf a file that is different between and HEAD has local changes,\n \treset is aborted.\n+\n+--stage::\n+\tReset the index, basically `--mixed`. `--no-stage` is the equivalent of\n+\t`--soft`.\n+\n+--work::\n+\tResets the working tree, basically `--hard`.\n --\n \n If you want to undo a commit other than the latest on a branch,\ndiff --git a/builtin/reset.c b/builtin/reset.c\nindex afa6e02..fbc1abc 100644\n--- a/builtin/reset.c\n+++ b/builtin/reset.c\n@@ -23,6 +23,7 @@\n \n static const char * const git_reset_usage[] = {\n \tN_(\"git reset [--mixed | --soft | --hard | --merge | --keep] [-q] []\"),\n+\tN_(\"git reset [--stage | --work] [-q] []\"),\n \tN_(\"git reset [-q] [--] ...\"),\n \tN_(\"git reset --patch [] [--] [...]\"),\n \tNULL\n@@ -243,6 +244,7 @@ static int update_refs(const char *rev, const unsigned char *sha1)\n int cmd_reset(int argc, const char **argv, const char *prefix)\n {\n \tint reset_type = NONE, update_ref_status = 0, quiet = 0;\n+\tint stage = -1, working_tree = -1;\n \tint patch_mode = 0, unborn;\n \tconst char *rev;\n \tunsigned char sha1[20];\n@@ -258,6 +260,8 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\t\t\tN_(\"reset HEAD, index and working tree\"), MERGE),\n \t\tOPT_SET_INT(0, \"keep\", &reset_type,\n \t\t\t\tN_(\"reset HEAD but keep local changes\"), KEEP),\n+\t\tOPT_BOOL(0, \"stage\", &stage, N_(\"reset index\")),\n+\t\tOPT_BOOL(0, \"work\", &working_tree, N_(\"reset working tree\")),\n \t\tOPT_BOOLEAN('p', \"patch\", &patch_mode, N_(\"select hunks interactively\")),\n \t\tOPT_END()\n \t};\n@@ -290,6 +294,22 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\thashcpy(sha1, tree->object.sha1);\n \t}\n \n+\tif (stage >= 0 || working_tree >= 0) {\n+\t\tif (reset_type != NONE)\n+\t\t\tdie(_(\"--{stage,work} are incompatible with --{hard,mixed,soft,merge}\"));\n+\n+\t\tif (working_tree == 1) {\n+\t\t\tif (stage == 0)\n+\t\t\t\tdie(_(\"--no-stage doesn't make sense with --work\"));\n+\t\t\treset_type = HARD;\n+\t\t} else {\n+\t\t\tif (stage == 1)\n+\t\t\t\treset_type = NONE;\n+\t\t\telse\n+\t\t\t\treset_type = SOFT;\n+\t\t}\n+\t}\n+\n \tif (patch_mode) {\n \t\tif (reset_type != NONE)\n \t\t\tdie(_(\"--patch is incompatible with --{hard,mixed,soft}\"));\n-- \n1.8.4-fc\n"},{"id":"228968","messageId":"1381789769-9893-13-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 08/14] submodule: add --staged options","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:27Z","receivedAt":"2013-10-14T22:29:27Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Synonym for --cached.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/git-submodule.txt | 8 ++++++--\n git-submodule.sh | 10 +++++-----\n 2 files changed, 11 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex bfef8a0..904e007 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -11,13 +11,13 @@ SYNOPSIS\n [verse]\n 'git submodule' [--quiet] add [-b ] [-f|--force] [--name ]\n \t [--reference ] [--depth ] [--] []\n-'git submodule' [--quiet] status [--cached] [--recursive] [--] [...]\n+'git submodule' [--quiet] status [--cached|--staged] [--recursive] [--] [...]\n 'git submodule' [--quiet] init [--] [...]\n 'git submodule' [--quiet] deinit [-f|--force] [--] ...\n 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]\n \t [-f|--force] [--rebase] [--reference ] [--depth ]\n \t [--merge] [--recursive] [--] [...]\n-'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) ]\n+'git submodule' [--quiet] summary [--cached|--staged|--files] [(-n|--summary-limit) ]\n \t [commit] [--] [...]\n 'git submodule' [--quiet] foreach [--recursive] \n 'git submodule' [--quiet] sync [--] [...]\n@@ -248,6 +248,10 @@ OPTIONS\n \tcommands typically use the commit found in the submodule HEAD, but\n \twith this option, the commit stored in the index is used instead.\n \n+\n+--staged::\n+\tSynonym for `--cached`.\n+\n --files::\n \tThis option is only valid for the summary command. This command\n \tcompares the commit in the index with that in the submodule HEAD\ndiff --git a/git-submodule.sh b/git-submodule.sh\nindex 2979197..823b783 100755\n--- a/git-submodule.sh\n+++ b/git-submodule.sh\n@@ -6,11 +6,11 @@\n \n dashless=$(basename \"$0\" | sed -e 's/-/ /')\n USAGE=\"[--quiet] add [-b ] [-f|--force] [--name ] [--reference ] [--] []\n- or: $dashless [--quiet] status [--cached] [--recursive] [--] [...]\n+ or: $dashless [--quiet] status [--cached|--staged] [--recursive] [--] [...]\n or: $dashless [--quiet] init [--] [...]\n or: $dashless [--quiet] deinit [-f|--force] [--] ...\n or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference ] [--merge] [--recursive] [--] [...]\n- or: $dashless [--quiet] summary [--cached|--files] [--summary-limit ] [commit] [--] [...]\n+ or: $dashless [--quiet] summary [--cached|--staged|--files] [--summary-limit ] [commit] [--] [...]\n or: $dashless [--quiet] foreach [--recursive] \n or: $dashless [--quiet] sync [--recursive] [--] [...]\"\n OPTIONS_SPEC=\n@@ -972,7 +972,7 @@ cmd_summary() {\n \twhile test $# -ne 0\n \tdo\n \t\tcase \"$1\" in\n-\t\t--cached)\n+\t\t--cached|--staged)\n \t\t\tcached=\"$1\"\n \t\t\t;;\n \t\t--files)\n@@ -1181,7 +1181,7 @@ cmd_status()\n \t\t-q|--quiet)\n \t\t\tGIT_QUIET=1\n \t\t\t;;\n-\t\t--cached)\n+\t\t--cached|--staged)\n \t\t\tcached=1\n \t\t\t;;\n \t\t--recursive)\n@@ -1348,7 +1348,7 @@ do\n \t\tesac\n \t\tbranch=\"$2\"; shift\n \t\t;;\n-\t--cached)\n+\t--cached|--staged)\n \t\tcached=\"$1\"\n \t\t;;\n \t--)\n-- \n1.8.4-fc\n"},{"id":"228967","messageId":"1381789769-9893-14-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 11/14] completion: update --staged options","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:28Z","receivedAt":"2013-10-14T22:29:28Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras \n---\n contrib/completion/git-completion.bash | 10 +++++-----\n 1 file changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 2b81e78..1dde51f 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -881,7 +881,7 @@ _git_apply ()\n \t\t__gitcomp \"\n \t\t\t--stat --numstat --summary --check --index\n \t\t\t--cached --index-info --reverse --reject --unidiff-zero\n-\t\t\t--apply --no-add --exclude=\n+\t\t\t--apply --no-add --exclude= --staged\n \t\t\t--ignore-whitespace --ignore-space-change\n \t\t\t--whitespace= --inaccurate-eof --verbose\n \t\t\t\"\n@@ -1294,7 +1294,7 @@ _git_grep ()\n \tcase \"$cur\" in\n \t--*)\n \t\t__gitcomp \"\n-\t\t\t--cached\n+\t\t\t--cached --staged\n \t\t\t--text --ignore-case --word-regexp --invert-match\n \t\t\t--full-name --line-number\n \t\t\t--extended-regexp --basic-regexp --fixed-strings\n@@ -2253,7 +2253,7 @@ _git_rm ()\n {\n \tcase \"$cur\" in\n \t--*)\n-\t\t__gitcomp \"--cached --dry-run --ignore-unmatch --quiet\"\n+\t\t__gitcomp \"--cached --staged --dry-run --ignore-unmatch --quiet\"\n \t\treturn\n \t\t;;\n \tesac\n@@ -2320,7 +2320,7 @@ _git_show_branch ()\n \n _git_stash ()\n {\n-\tlocal save_opts='--keep-index --no-keep-index --quiet --patch'\n+\tlocal save_opts='--keep-index --no-keep-index --stage --no-stage --quiet --patch'\n \tlocal subcommands='save list show apply clear drop pop create branch'\n \tlocal subcommand=\"$(__git_find_on_cmdline \"$subcommands\")\"\n \tif [ -z \"$subcommand\" ]; then\n@@ -2340,7 +2340,7 @@ _git_stash ()\n \t\t\t__gitcomp \"$save_opts\"\n \t\t\t;;\n \t\tapply,--*|pop,--*)\n-\t\t\t__gitcomp \"--index --quiet\"\n+\t\t\t__gitcomp \"--index --stage --quiet\"\n \t\t\t;;\n \t\tshow,--*|drop,--*|branch,--*)\n \t\t\t;;\n-- \n1.8.4-fc\n"},{"id":"228969","messageId":"1381789769-9893-15-git-send-email-felipe.contreras@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 06/14] stash: add --stage option to save","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:29:29Z","receivedAt":"2013-10-14T22:29:29Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"--no-stage is synonym for --keep-index.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/git-stash.txt | 6 +++---\n git-stash.sh | 8 +++++++-\n 2 files changed, 10 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex db7e803..21a01c2 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -13,7 +13,7 @@ SYNOPSIS\n 'git stash' drop [-q|--quiet] []\n 'git stash' ( pop | apply ) [--index] [-q|--quiet] []\n 'git stash' branch []\n-'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n+'git stash' [save [-p|--patch] [-k|--[no-]keep-index|--[no-]stage] [-q|--quiet]\n \t [-u|--include-untracked] [-a|--all] []]\n 'git stash' clear\n 'git stash' create []\n@@ -44,7 +44,7 @@ is also possible).\n OPTIONS\n -------\n \n-save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n+save [-p|--patch] [--[no-]keep-index|--[no-]stage] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n \n \tSave your local modifications to a new 'stash', and run `git reset\n \t--hard` to revert them. The part is optional and gives\n@@ -54,7 +54,7 @@ save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--\n \tsubcommand from making an unwanted stash.\n +\n If the `--keep-index` option is used, all changes already added to the\n-index are left intact.\n+index are left intact. Same with `--no-stage`, which is a synonym.\n +\n If the `--include-untracked` option is used, all untracked files are also\n stashed and then cleaned up with `git clean`, leaving the working directory\ndiff --git a/git-stash.sh b/git-stash.sh\nindex 1e541a2..47220d0 100755\n--- a/git-stash.sh\n+++ b/git-stash.sh\n@@ -7,7 +7,7 @@ USAGE=\"list []\n or: $dashless drop [-q|--quiet] []\n or: $dashless ( pop | apply ) [--index] [-q|--quiet] []\n or: $dashless branch []\n- or: $dashless [save [--patch] [-k|--[no-]keep-index] [-q|--quiet]\n+ or: $dashless [save [--patch] [-k|--[no-]keep-index|--[no-]stage] [-q|--quiet]\n \t\t [-u|--include-untracked] [-a|--all] []]\n or: $dashless clear\"\n \n@@ -204,6 +204,12 @@ save_stash () {\n \t\t--no-keep-index)\n \t\t\tkeep_index=n\n \t\t\t;;\n+\t\t--stage)\n+\t\t\tkeep_index=n\n+\t\t\t;;\n+\t\t--no-stage)\n+\t\t\tkeep_index=t\n+\t\t\t;;\n \t\t-p|--patch)\n \t\t\tpatch_mode=t\n \t\t\t# only default to keep if we don't already have an override\n-- \n1.8.4-fc\n"},{"id":"228972","messageId":"CAMP44s3u_SMyZOe5jxkvoGn5MBJ_g70iHRT5v_3u1rZwFoqiVA@mail.gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-4-git-send-email-felipe.contreras@gmail.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T22:51:12Z","receivedAt":"2013-10-14T22:51:12Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Mon, Oct 14, 2013 at 5:29 PM, Felipe Contreras\n wrote:\n> tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we should move\n> away from the name \"the index\".\n\nJunio, can you make an exception and reply to this thread? The change\nto move away from the term \"the index\" has been suggested many times\nsince many years ago, it is an extremely important change to users,\nand all the Git developers agree it must be done.\n\nVirtually everyone has agreed already that the term \"staging area\" is\nthe best option and this patch series is a good first step. Other than\nthe --work patches, this series could easily be merged to the 'pu'\nbranch. Yet not only is this series not there, but you haven't said\nwhat needs to be done to get there.\n\nIt has been more than a month that I demonstrated to you that virtual\nnobody has any problems with moving away from term \"the index\"[1][2],\nand yet you haven't even responded.\n\nI'm not even asking about this series, all I want to know is if any\nchange that tries to move away from the term \"the index\" towards\n\"staging area\" would ever be considered for inclusion. Yes or no.\n\nAll I want is a simple answer to a simple question. Is that too much to ask?\n\n[1] http://article.gmane.org/gmane.comp.version-control.git/233469\n[2] http://article.gmane.org/gmane.comp.version-control.git/233468\n\n-- \nFelipe Contreras\n"},{"id":"228973","messageId":"CAPig+cTu8k7c2JtxdYLqn+9s-rZ4C_Th3GNDBXABQVtz0hviaQ@mail.gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-6-git-send-email-felipe.contreras@gmail.com","subject":"Re: [PATCH v2 01/14] Add proper 'stage' command","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2013-10-14T23:06:37Z","receivedAt":"2013-10-14T23:06:37Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Oct 14, 2013 at 6:29 PM, Felipe Contreras\n wrote:\n> diff --git a/builtin/stage.c b/builtin/stage.c\n> new file mode 100644\n> index 0000000..3023d17\n> --- /dev/null\n> +++ b/builtin/stage.c\n> @@ -0,0 +1,52 @@\n> +/*\n> + * 'git stage' builtin command\n> + *\n> + * Copyright (C) 2013 Felipe Contreras\n> + */\n> +\n> +#include \"builtin.h\"\n> +#include \"parse-options.h\"\n> +\n> +static const char *const stage_usage[] = {\n> + N_(\"git stage [options] [--] ...\"),\n> + N_(\"git stage add [options] [--] ...\"),\n> + N_(\"git stage reset [-q|--patch] [--] ...\"),\n> + N_(\"git stage diff [options] [ [--] ...\"),\n> + N_(\"git stage rm [options] [--] ...\"),\n> + NULL\n> +};\n\nSent the wrong set of patches? The interdiff in the cover letter\nshowed usage for \"git stage apply\", but it's not here in the actual\npatch.\n"},{"id":"228974","messageId":"CAMP44s0qXui4DM6ejdwNYTR__q0zsish2+-JsphrmNT15zoeAg@mail.gmail.com","threadId":"35142","inReplyTo":"CAPig+cTu8k7c2JtxdYLqn+9s-rZ4C_Th3GNDBXABQVtz0hviaQ@mail.gmail.com","subject":"Re: [PATCH v2 01/14] Add proper 'stage' command","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-14T23:15:26Z","receivedAt":"2013-10-14T23:15:26Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Mon, Oct 14, 2013 at 6:06 PM, Eric Sunshine wrote:\n> On Mon, Oct 14, 2013 at 6:29 PM, Felipe Contreras\n> wrote:\n>> diff --git a/builtin/stage.c b/builtin/stage.c\n>> new file mode 100644\n>> index 0000000..3023d17\n>> --- /dev/null\n>> +++ b/builtin/stage.c\n>> @@ -0,0 +1,52 @@\n>> +/*\n>> + * 'git stage' builtin command\n>> + *\n>> + * Copyright (C) 2013 Felipe Contreras\n>> + */\n>> +\n>> +#include \"builtin.h\"\n>> +#include \"parse-options.h\"\n>> +\n>> +static const char *const stage_usage[] = {\n>> + N_(\"git stage [options] [--] ...\"),\n>> + N_(\"git stage add [options] [--] ...\"),\n>> + N_(\"git stage reset [-q|--patch] [--] ...\"),\n>> + N_(\"git stage diff [options] [ [--] ...\"),\n>> + N_(\"git stage rm [options] [--] ...\"),\n>> + NULL\n>> +};\n>\n> Sent the wrong set of patches? The interdiff in the cover letter\n> showed usage for \"git stage apply\", but it's not here in the actual\n> patch.\n\nNo, it's the right series, but apparently I added the change to the\nwrong commit: stage: add edit command. I've fixed that and will send\nit on the next reroll (if there's any).\n\n-- \nFelipe Contreras\n"},{"id":"229131","messageId":"xmqqwqlbznfp.fsf@gitster.dls.corp.google.com","threadId":"35142","inReplyTo":"CAMP44s3u_SMyZOe5jxkvoGn5MBJ_g70iHRT5v_3u1rZwFoqiVA@mail.gmail.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-10-17T19:50:50Z","receivedAt":"2013-10-17T19:50:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> Junio, can you make an exception and reply to this thread? The change\n> to move away from the term \"the index\" has been suggested many times\n> since many years ago, it is an extremely important change to users,\n> and all the Git developers agree it must be done.\n\n\"It must be done\" is different from \"any change is good, as long as\nit introduces more instances of word 'stage'\". As we established, we\ndo not seem to be able to do a sensible design discussion with you\nwithout wasting time for nothing, I won't directly comment on that\npatch series, at least for now.\n\nHowever, since you asked, I would share a couple of comments\nregarding the index, cache and staging area.\n\n(1) \"Staging area\".\n\nThe phrase \"staging area\" is not an everyday phrase or common CS\nlingo, and that unfortunately makes it a suboptimal choice of words\nespecially to those of us, to whom a large portion of their exposure\nto the English language is through the command words we use when we\ntalk to our computers.\n\nI personally do not mind explaining the index is \"like a staging\narea, where an army piles up ammunition to a temporary dump before\nstarting a major campaign.\" to native speakers, though ;-).\n\nThe index can also be thought of \"like the buffer cache, where new\ncontents of files are kept before they are committed to disk\nplatter.\" At least, non-native speaker with CS background would\nunderstand that, much better than \"the index\" (no, I am not saying\nthat we should call it \"the cache\"; I am just saying \"the index\" is\nnot a good word, but we may need to find a better word than \"the\nstaging area\").\n\nThe noun phrase \"staging area\" and the verb \"to stage\" are good\n(especially when we do not worry too much about us foreigners), but\nwe need to make sure \"stage\" is not mistaken as a noun when used in\na context that talks about the index as a whole, to avoid confusion\nwith the use of the word \"stage\" long established since\n\n http://thread.gmane.org/gmane.comp.version-control.git/231/focus=286\n\nto call \"ours\" stage#2, etc.\n\n\n(2) \"cached\" vs \"index\".\n\nI think this is the more major issue between the two issues (the\nother one being \"why do we force people to say 'index'?\"). Some\ncommands take \"--cached\", some others take \"--index\", some take\nboth. What these two mean are documented in gitcli manual page, but\nthat is far from sufficient. The users can get confused by this UI\nmistake in different ways.\n\n * We do need to have \"git apply\" that mimics \"patch\" (i.e. works\n only to a working tree files, or even outside Git repository)\n without any option, \"git apply --mode1\" that only applies the\n change to the index, and \"git apply --mode2\" that applies the\n change to both the index and the working tree. No renaming of\n \"the index\" does not change this need to have three different\n mode of operation.\n\n It was a major UI mistake to call one of the modes \"--cached\" and\n another \"--index\", because there is no way, other than rote\n learning, for people to choose the one between the two depending\n that is right for the situation they face.\n\n If \"--cached\" were called \"--index-only\", it might have been a\n lot more learnable (and then \"--index\" could be renamed to\n \"--index-and-working-tree\" at the same time to reduce the\n confusion further). Alternatively, with the synonym \"--staged\"\n for \"--cached\" already in place for \"git diff\", we could\n introduce \"--staged-and-working-tree\" as a synonym for \"--index\"\n to achieve the same effect (of course we need to find a way to\n shorten \"-and-working-tree\" part in a sensible way).\n\n * \"git grep\" barfs when given \"--index\", even though it does accept\n \"--cached\" and searches the patterns in contents that are in the\n index. This is technically correct, as the command does not\n search both in the index and in the working tree, but again,\n there is no way other than rote learning for users to tell that\n \"--cached\" is the correct one to use, even after they know that\n they want to search in the index (I already called it a major UI\n mistake, didn't I?).\n\n A new synonym \"--staged\" for \"--cached\" may be able to alleviate\n the confusion somewhat, given especially that \"git diff\" already\n knows \"--staged\" as a synonym for \"--cached\". I think a better\n end result will come if we taught \"git grep --index\" to actually\n search the patterns both in the index and in the working tree at\n the same time. There is no logical reason from the end user's\n point of view that \"git grep --index\" (aka \"git grep\n --staged-and-working-tree\") needs to fail; if we make the\n \"--mode2\" to mean to work on both the index and the working tree\n for any Git command when it makes sense, things will be more\n consistent, and it certainly makes sense to ask \"git grep\" to\n work on both the index and the working tree. We do allow \"git\n grep -e pattern tree-ish-1 tree-ish-2\" to search in multiple data\n sources already, so it can be seen as a logical extension.\n\n * \"git diff --index [TREE-ISH]\" has exactly the same issue as \"git\n grep\", and the same conclusion, i.e. it may be worthwhile to\n teach \"git diff --index [TREE-ISH]\" to give combined diff between\n the given tree-ish (defaulting to HEAD as usual), the index and\n the working tree.\n"},{"id":"229150","messageId":"52605b927fb30_448145fe747c@nysa.notmuch","threadId":"35142","inReplyTo":"xmqqwqlbznfp.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-17T21:50:10Z","receivedAt":"2013-10-17T21:50:10Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras writes:\n> \n> > Junio, can you make an exception and reply to this thread? The change\n> > to move away from the term \"the index\" has been suggested many times\n> > since many years ago, it is an extremely important change to users,\n> > and all the Git developers agree it must be done.\n> \n> \"It must be done\" is different from \"any change is good, as long as\n> it introduces more instances of word 'stage'\". As we established, we\n> do not seem to be able to do a sensible design discussion with you\n> without wasting time for nothing, I won't directly comment on that\n> patch series, at least for now.\n> \n> However, since you asked, I would share a couple of comments\n> regarding the index, cache and staging area.\n> \n> (1) \"Staging area\".\n> \n> The phrase \"staging area\" is not an everyday phrase or common CS\n> lingo, and that unfortunately makes it a suboptimal choice of words\n> especially to those of us, to whom a large portion of their exposure\n> to the English language is through the command words we use when we\n> talk to our computers.\n\nThat's because Git is the only command tool that has such a concept.\n\n> I personally do not mind explaining the index is \"like a staging\n> area, where an army piles up ammunition to a temporary dump before\n> starting a major campaign.\" to native speakers, though ;-).\n\nIf you agree that explaining to users \"the index is like a staging area\", then\nwhy just not call it the staging area?\n\nMoreover, a staging area is not just a temporary dump, it is used in\npreparation for something specific, and you might need to remove certain\nweapons in place of better ones suited for the mission, that's why the word\n\"staging\" is used.\n\n> The index can also be thought of \"like the buffer cache, where new\n> contents of files are kept before they are committed to disk\n> platter.\"\n\nA buffer and a cache are two very different things used for two very different\npurposes, and the term cache doesn't apply to \"the index\".\n\n> At least, non-native speaker with CS background would understand that, much\n> better than \"the index\" (no, I am not saying that we should call it \"the\n> cache\"; I am just saying \"the index\" is not a good word, but we may need to\n> find a better word than \"the staging area\").\n\nAll right, so that's progress; you do accept \"the index\" is not a good term.\nNow, if you don't think \"staging area\" is a good term, do you have any that is\nbetter?\n\nThis has been discussed for several years, and nobody has come up with a better\nterm, in fact, the vast majority of people prefer the term \"staging area\", and\nit is already used in online documentation, including the ProGit book. It seems\ninside and outside the Git project, the term has already been chosen.\n\nDo you honestly think somebody is just suddenly going to come up with a better\nterm? How long do we have to wait before we decide X is the best term we could\ncome up with? One year? Two years? Ten years? Or do you just want to wait until\nwe have the \"perfect\" term, which might be never.\n\n> The noun phrase \"staging area\" and the verb \"to stage\" are good\n> (especially when we do not worry too much about us foreigners), but\n> we need to make sure \"stage\" is not mistaken as a noun when used in\n> a context that talks about the index as a whole, to avoid confusion\n> with the use of the word \"stage\" long established since\n> \n> http://thread.gmane.org/gmane.comp.version-control.git/231/focus=286\n> \n> to call \"ours\" stage#2, etc.\n\nLets assume that \"staging area\" is not the best option, even though after\nyears of discussion nobody has come up with a better one. How would a different\nterm solve the problem you state above? If we use the term \"commit draft\", we\nstill could have people saying \"draft # 2\". So is there any term that would\navoid this problem, and is it really important to worry about such a marginal\nproblem?\n\nRegardless of the term used, we can make sure it's not used in that context, so\nI don't understand how that argument goes against \"staging area\". We can make\nsure \"staging area\" is not used to denote the different \"index\" files.\n\nIs this the *only* argument you have against the term \"staging area\"?\n\n> (2) \"cached\" vs \"index\".\n> \n> I think this is the more major issue between the two issues (the\n> other one being \"why do we force people to say 'index'?\"). Some\n> commands take \"--cached\", some others take \"--index\", some take\n> both. What these two mean are documented in gitcli manual page, but\n> that is far from sufficient. The users can get confused by this UI\n> mistake in different ways.\n> \n> * We do need to have \"git apply\" that mimics \"patch\" (i.e. works\n> only to a working tree files, or even outside Git repository)\n> without any option, \"git apply --mode1\" that only applies the\n> change to the index, and \"git apply --mode2\" that applies the\n> change to both the index and the working tree. No renaming of\n> \"the index\" does not change this need to have three different\n> mode of operation.\n> \n> It was a major UI mistake to call one of the modes \"--cached\" and\n> another \"--index\", because there is no way, other than rote\n> learning, for people to choose the one between the two depending\n> that is right for the situation they face.\n> \n> If \"--cached\" were called \"--index-only\", it might have been a\n> lot more learnable (and then \"--index\" could be renamed to\n> \"--index-and-working-tree\" at the same time to reduce the\n> confusion further). Alternatively, with the synonym \"--staged\"\n> for \"--cached\" already in place for \"git diff\", we could\n> introduce \"--staged-and-working-tree\" as a synonym for \"--index\"\n> to achieve the same effect (of course we need to find a way to\n> shorten \"-and-working-tree\" part in a sensible way).\n\nOr we can do what I already did to solve the problem:\n\n git apply --stage --working-tree\n\n> * \"git grep\" barfs when given \"--index\", even though it does accept\n> \"--cached\" and searches the patterns in contents that are in the\n> index. This is technically correct, as the command does not\n> search both in the index and in the working tree, but again,\n> there is no way other than rote learning for users to tell that\n> \"--cached\" is the correct one to use, even after they know that\n> they want to search in the index (I already called it a major UI\n> mistake, didn't I?).\n> \n> A new synonym \"--staged\" for \"--cached\" may be able to alleviate\n> the confusion somewhat, given especially that \"git diff\" already\n> knows \"--staged\" as a synonym for \"--cached\". I think a better\n> end result will come if we taught \"git grep --index\" to actually\n> search the patterns both in the index and in the working tree at\n> the same time. There is no logical reason from the end user's\n> point of view that \"git grep --index\" (aka \"git grep\n> --staged-and-working-tree\") needs to fail; if we make the\n> \"--mode2\" to mean to work on both the index and the working tree\n> for any Git command when it makes sense, things will be more\n> consistent, and it certainly makes sense to ask \"git grep\" to\n> work on both the index and the working tree. We do allow \"git\n> grep -e pattern tree-ish-1 tree-ish-2\" to search in multiple data\n> sources already, so it can be seen as a logical extension.\n\n git grep --staged --working-tree\n\n> * \"git diff --index [TREE-ISH]\" has exactly the same issue as \"git\n> grep\", and the same conclusion, i.e. it may be worthwhile to\n> teach \"git diff --index [TREE-ISH]\" to give combined diff between\n> the given tree-ish (defaulting to HEAD as usual), the index and\n> the working tree.\n\n git diff --staged --working-tree\n\n-- \nFelipe Contreras\n"},{"id":"229162","messageId":"vpqbo2m7vyz.fsf@anie.imag.fr","threadId":"35142","inReplyTo":"xmqqwqlbznfp.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2013-10-18T09:46:12Z","receivedAt":"2013-10-18T09:46:12Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"I'm lacking time to read and answer in detail, sorry.\n\nJunio C Hamano writes:\n\n> \"It must be done\" is different from \"any change is good, as long as\n> it introduces more instances of word 'stage'\".\n\nI agree. Something must be done, at least to remove the cache Vs index\nconfusion. I'm not sure exactly what's best, and we should agree where\nto go before going there. The previous attempts to introduce more\n\"stage\" in Git's command-line (e.g. the \"git stage\" alias) introduced\nmore confusion than anything else.\n\n> The phrase \"staging area\" is not an everyday phrase or common CS\n> lingo, and that unfortunately makes it a suboptimal choice of words\n> especially to those of us, to whom a large portion of their exposure\n> to the English language is through the command words we use when we\n> talk to our computers.\n\nI do not think being understandable immediately by non-native is so\nimportant actually. To me as a french, \"commit\" makes no sense as an\nenglish word to describe what \"git commit\" does, but it's OK as I never\nreally translate it. Even fr.po translates \"a commit\" by \"un commit\".\n\nThat said, having something that immediately makes sense to a non-native\nis obviously a good point.\n\nAnother proposal which I liked BTW was to use the word \"precommit\".\nShort, and easily understood as the place where the next commit is\nprepared.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"229163","messageId":"CAEBDL5UUyX5E6d3ewjZ_KxFuFZBqW=--kN81B1wXC2Re6KD2Bg@mail.gmail.com","threadId":"35142","inReplyTo":"vpqbo2m7vyz.fsf@anie.imag.fr","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"John Szakmeister","fromEmail":"john@szakmeister.net","sentAt":"2013-10-18T10:26:22Z","receivedAt":"2013-10-18T10:26:22Z","isPatch":true,"sender":{"key":"john@szakmeister.net","avatar":"https://avatars.githubusercontent.com/u/448087?v=4"},"body":"On Fri, Oct 18, 2013 at 5:46 AM, Matthieu Moy\n wrote:\n> I'm lacking time to read and answer in detail, sorry.\n>\n> Junio C Hamano writes:\n>\n>> \"It must be done\" is different from \"any change is good, as long as\n>> it introduces more instances of word 'stage'\".\n>\n> I agree. Something must be done, at least to remove the cache Vs index\n> confusion. I'm not sure exactly what's best, and we should agree where\n> to go before going there. The previous attempts to introduce more\n> \"stage\" in Git's command-line (e.g. the \"git stage\" alias) introduced\n> more confusion than anything else.\n\nI definitely agree about removing the cache vs. index confusion. I'm\ncurious about the confusions surrounding this \"git stage\" alias. Was\nit simply an implementation issue, or was it an issue surrounding the\nname?\n\nFWIW, I've trained my employees to think of it as a staging area as\nwell. At least in English, it seems to be the best understood analogy\nto the index's purpose.\n\n>> The phrase \"staging area\" is not an everyday phrase or common CS\n>> lingo, and that unfortunately makes it a suboptimal choice of words\n>> especially to those of us, to whom a large portion of their exposure\n>> to the English language is through the command words we use when we\n>> talk to our computers.\n>\n> I do not think being understandable immediately by non-native is so\n> important actually. To me as a french, \"commit\" makes no sense as an\n> english word to describe what \"git commit\" does, but it's OK as I never\n> really translate it. Even fr.po translates \"a commit\" by \"un commit\".\n>\n> That said, having something that immediately makes sense to a non-native\n> is obviously a good point.\n>\n> Another proposal which I liked BTW was to use the word \"precommit\".\n> Short, and easily understood as the place where the next commit is\n> prepared.\n\nI'm not sure what concept \"precommit\" invokes, but it's certainly not\nwhere the next commit is prepared. Two thoughts come to mind: the\nprecommit hook, and \"what is a pre-commit?\" How would you talk about\npreparing for a commit? Do you \"precommit a file?\" \"Add the file to\nthe precommit?\" I'm just curious.\n\nThanks!\n\n-John\n"},{"id":"229164","messageId":"CAMP44s0pA3hKRMbXDx0ddi4RdrUZyMY0yAd5GbQutMqRSj_4Rg@mail.gmail.com","threadId":"35142","inReplyTo":"vpqbo2m7vyz.fsf@anie.imag.fr","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-18T10:36:54Z","receivedAt":"2013-10-18T10:36:54Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Fri, Oct 18, 2013 at 4:46 AM, Matthieu Moy\n wrote:\n> I'm lacking time to read and answer in detail, sorry.\n>\n> Junio C Hamano writes:\n>\n>> \"It must be done\" is different from \"any change is good, as long as\n>> it introduces more instances of word 'stage'\".\n>\n> I agree. Something must be done, at least to remove the cache Vs index\n> confusion. I'm not sure exactly what's best, and we should agree where\n> to go before going there.\n\nI thought we already agreed \"staging area\" is the best term. Some\npeople don't, but that's expected.\n\n>> The phrase \"staging area\" is not an everyday phrase or common CS\n>> lingo, and that unfortunately makes it a suboptimal choice of words\n>> especially to those of us, to whom a large portion of their exposure\n>> to the English language is through the command words we use when we\n>> talk to our computers.\n>\n> I do not think being understandable immediately by non-native is so\n> important actually. To me as a french, \"commit\" makes no sense as an\n> english word to describe what \"git commit\" does, but it's OK as I never\n> really translate it. Even fr.po translates \"a commit\" by \"un commit\".\n\nIndeed. Let's hope this red herring is not brought again.\n\n> That said, having something that immediately makes sense to a non-native\n> is obviously a good point.\n\nMost non-native speakers, as most native speakers, already agreed the\nterm \"staging area\" is best.\n\n> Another proposal which I liked BTW was to use the word \"precommit\".\n> Short, and easily understood as the place where the next commit is\n> prepared.\n\nAnd that proposal has been argued against already[1][2].\n\nTo summarize:\n\n1) It's not even an English word\n2) Unlike \"staging area\", it's not widely used in external documentation already\n3) There's no sensible verb: \"to precommit\"?\n\nMoreover, in my mind a true precommit would have author, committer,\ndate; all the things you expect in a commit, except that it's not\npermanent. A natural command that would derive from this concept is\n'git commit --prepare', which would create an actual precommit.\n\nBut we are not looking to introduce yet another concept, we are\nlooking for a name of a concept we already have, and the majority of\nusers have already given it a name; the staging area.\n\n[1] http://article.gmane.org/gmane.comp.version-control.git/197215\n[2] http://article.gmane.org/gmane.comp.version-control.git/168201\n-- \nFelipe Contreras\n"},{"id":"229165","messageId":"C7A28BEB-5B2D-4D21-AC3D-CC5BACDF742D@quendi.de","threadId":"35142","inReplyTo":"xmqqwqlbznfp.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2013-10-18T11:38:09Z","receivedAt":"2013-10-18T11:38:09Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\nOn 17.10.2013, at 21:50, Junio C Hamano wrote:\n\n> Felipe Contreras writes:\n\n[...]\n\n> \n> However, since you asked, I would share a couple of comments\n> regarding the index, cache and staging area.\n> \n> (1) \"Staging area\".\n> \n> The phrase \"staging area\" is not an everyday phrase or common CS\n> lingo, and that unfortunately makes it a suboptimal choice of words\n> especially to those of us, to whom a large portion of their exposure\n> to the English language is through the command words we use when we\n> talk to our computers.\n\nInterestingly, as a non-native speaker, I draw the exact reverse conclusion from this: While I had no idea what a \"staging area\" or \"to stage\" was (I did know the \"stage\" in a theater, though), I found this to not be a major problem: Using a dictionary and reading up on what it means in git made it clearly quickly enough.\n\nTo the contrary, the fact that the term was not yet overloaded with conflicting other meanings made it easier for me to attach the semantics git associates with it.\n\nIn contrast, \"index\" was exceedingly bad and confusing to me... I already had various notions of what an \"index\" is (e.g. the index of a book -- the same word actually exists in German; or more generally an index in computer science, as a kind of loopup table, etc.), and to this day, have a hard time consolidating this with the way git uses it. For me, it is yet another, seeming completely unrelated, meaning of the word \"index\" I had to memorize. Hey, just take a look at Wiki page for the many dozens of meanings associated to this word. Ugh. And worst of it, I am actually not quite sure on which of the meanings listed there \"the index\" as used by git is based... I.e. I don't even see a helpful analogy that would make it easier to understand the choice of name. \n\nIn summary: For me as a non-native speaker, \"index\" feels like about the worst possible choice (well, you could have called it the \"file\" or \"thing\", that might have been worse ;-). While staging area turned out to be surprisingly good, *precisely* because I was unfamiliar with it. \n\nSo, while \"staging area\" might not be perfect, it seems good enough to me. If this matter had indeed been discussed here for years, and no better suggestions has come up, then perhaps it is time to end the search for the (possibly non-existent) perfect solution, and instead do the pragmatic?\n\n\n> The index can also be thought of \"like the buffer cache, where new\n> contents of files are kept before they are committed to disk\n> platter.\" At least, non-native speaker with CS background would\n> understand that, much better than \"the index\" (no, I am not saying\n> that we should call it \"the cache\"; I am just saying \"the index\" is\n> not a good word, but we may need to find a better word than \"the\n> staging area\").\n\nHuh? As a non-native speaker with CS background, this actually leaves me more confused than I was before. I think about \"the staging area\", and I don't see how this is anything like an \"index\" (in any of the meaning I see on ). I can vaguely recognize a faint similarity to a \"cache\", and yet more relation to a \"buffer\", but in the end, none of these strike me as particularly illustrative.\n\nFor that matter, I never really understood of why I had to do \"git diff --cached\", I simply learned it by rote. \n\nOn the other hand, I feel that after understanding what the staging area is, then writing \"git diff --staged\" is very logical and simple to memorize.\n\n\n\n\nCheers,\nMax\n"},{"id":"229199","messageId":"5261C42E.4050208@gmail.com","threadId":"35142","inReplyTo":"1381789769-9893-4-git-send-email-felipe.contreras@gmail.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Karsten Blees","fromEmail":"karsten.blees@gmail.com","sentAt":"2013-10-18T23:28:46Z","receivedAt":"2013-10-18T23:28:46Z","isPatch":true,"sender":{"key":"karsten.blees@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1111200?v=4"},"body":"Am 15.10.2013 00:29, schrieb Felipe Contreras:\n> tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we should move\n> away from the name \"the index\".\n> \n> It has been discussed many times in the past that 'index' is not an\n> appropriate description for what the high-level user does with it, and\n> it has been agreed that 'staging area' is the best term.\n> \n\nI haven't followed the previous discussion, but if a final conclusion towards 'staging area' has already been reached, it should probably be revised.\n\n> The term 'staging area' is more intuitive for newcomers which are more\n> familiar with English than with Git, and it seems to be a\n> straightforward mental notion for people with different mother tongues.\n> \n> In fact it is so intuitive that it's used already in a lot online\n> documentation, and the people that do teach Git professionally use this\n> term, because it's easier for many kinds of audiences to grasp.\n> \n\nSuch online documentation often portraits the 'staging area' as some supposedly 'unique' git feature, which I find _very_ confusing. In fact, every major SCM has a staging area. E.g. you first need to \"svn/hg/bzr/p4 add/remove/rename/move\" a file, which is somehow recorded in the working copy. These recorded changes will then be picked up by a subsequent \"svn/hg/bzr/p4 commit/submit\".\n\nAdditionally, all those systems support selectively committing individual files (by specifying the files on the commit command line or selecting them in a GUI).\n\nSo git's 'unique staging area' boils down to this:\n\n1.) Recording individual files to commit in advance (instead of specifying them at commit time). Which isn't that hard to grasp.\n\n2.) Recording individual diff hunks or even lines to commit. Which is an advanced feature that requires even more advanced commands to be useful (i.e. stash save --keep-index; make; test; commit; stash pop). It is also entirely irrelevant to binary files (i.e. for non-technical users that use git to track documents and stuff).\n\n> index: an 'index' is a guide of pointers to something else; a book\n> index has a list of entries so the reader can locate information\n> easily without having to go through the whole book. Git porcelain is\n> not using the staging area to find out entries quicker; it's not an\n> index.\n> \n\nThe 'staging area' is a sorted list of most recently checked out files, and its primary purpose is to quickly detect changes in the working copy (i.e. its an index).\n\nOf the 28 builtin main porcelain commands, 18 read the index (read_index), and 11 of those also check the state of the working copy (ie_match_stat). Incidentally, the latter include _all_ commands that update the so-called 'staging area'.\n\nSubversion until recently kept the checked out files scattered in **/.svn/text-base directories, and many operations were terribly slow due to this. Subversion 1.7 introduced a new working copy format, based on a database in the root .svn directory (i.e. an index), leading to tremendous performance improvements.\n\nThe git index is a major feature that facilitates the incredible performance we're so much addicted to...why be shy about it and call it something else?\n\n> stage: a 'stage' is a special area designated for convenience in order\n> for some activity to take place; an orator would prepare a stage in\n> order for her speak to be successful, otherwise many people might not\n> be able to hear, or see her. Git porcelain is using the staging area\n> precisely as a special area to be separated from the working directory\n> for convenience.\n> \n\nI'm not a native speaker, but in my limited understanding, 'staging' in computer jargon is the process of preparing data for a production system (i.e. until the 'stage' or 'state' of the data is ready for production). It has nothing to do with the 'stage' in a theater. I've never heard the term 'staging' beeing used for source code or software (that would be 'integration'). I've also never heard 'staging' for moving data back from a production system to some work- or development area.\n\nIn any sense, 'staging' is a unidirectional process (even in a theater). If I think of the index as a staging area, it covers just a single use case: preparing new commits. With this world view, it is completely counter-intuitive that e.g. changing branches overwrites my staging area.\n\nIMO, it is ok to use 'like a staging area' when we talk about using the index to prepare new commits. However, its not ok to use 'staging area' as a general synonym for the index.\n\nJust my 2 cents\nKarsten\n"},{"id":"229201","messageId":"5261d528ca9cf_35b014d9e7cb6@nysa.notmuch","threadId":"35142","inReplyTo":"5261C42E.4050208@gmail.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-19T00:41:12Z","receivedAt":"2013-10-19T00:41:12Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Karsten Blees wrote:\n> Am 15.10.2013 00:29, schrieb Felipe Contreras:\n> > tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we should move\n> > away from the name \"the index\".\n> > \n> > It has been discussed many times in the past that 'index' is not an\n> > appropriate description for what the high-level user does with it, and\n> > it has been agreed that 'staging area' is the best term.\n> \n> I haven't followed the previous discussion, but if a final conclusion towards\n> 'staging area' has already been reached, it should probably be revised.\n> \n> > The term 'staging area' is more intuitive for newcomers which are more\n> > familiar with English than with Git, and it seems to be a\n> > straightforward mental notion for people with different mother tongues.\n> > \n> > In fact it is so intuitive that it's used already in a lot online\n> > documentation, and the people that do teach Git professionally use this\n> > term, because it's easier for many kinds of audiences to grasp.\n> \n> Such online documentation often portraits the 'staging area' as some\n> supposedly 'unique' git feature, which I find _very_ confusing. In fact,\n> every major SCM has a staging area. E.g. you first need to \"svn/hg/bzr/p4\n> add/remove/rename/move\" a file, which is somehow recorded in the working\n> copy. These recorded changes will then be picked up by a subsequent\n> \"svn/hg/bzr/p4 commit/submit\".\n\nThat is not a staging area.\n\n % hg init test\n % cd test\n % echo Hello > README\n % hg add README\n % echo Bye > README\n % hg commit -m Init\n % hg log -p -r -1\n changeset: 0:ba28df72474c\n tag: tip\n user: Felipe Contreras \n date: Fri Oct 18 19:43:42 2013 -0500\n summary: Init\n\n diff -r 000000000000 -r ba28df72474c README\n --- /dev/null\tThu Jan 01 00:00:00 1970 +0000\n +++ b/README\tFri Oct 18 19:43:42 2013 -0500\n @@ -0,0 +1,1 @@\n +Bye\n\n\nWhat exactly got staged?\n\nTo me the best way to think about the staging area is like a commit draft. No\nother VCS has anything like that. And what is the point about this argument?\n\n> > index: an 'index' is a guide of pointers to something else; a book\n> > index has a list of entries so the reader can locate information\n> > easily without having to go through the whole book. Git porcelain is\n> > not using the staging area to find out entries quicker; it's not an\n> > index.\n> \n> The 'staging area' is a sorted list of most recently checked out files, and\n> its primary purpose is to quickly detect changes in the working copy (i.e.\n> its an index).\n\nThat is not it's primary purpose.\n\n> Of the 28 builtin main porcelain commands, 18 read the index (read_index),\n> and 11 of those also check the state of the working copy (ie_match_stat).\n> Incidentally, the latter include _all_ commands that update the so-called\n> 'staging area'.\n> \n> Subversion until recently kept the checked out files scattered in\n> **/.svn/text-base directories, and many operations were terribly slow due to\n> this. Subversion 1.7 introduced a new working copy format, based on a\n> database in the root .svn directory (i.e. an index), leading to tremendous\n> performance improvements.\n> \n> The git index is a major feature that facilitates the incredible performance\n> we're so much addicted to...why be shy about it and call it something else?\n\nTell me which subversion command adds and removes information from their\nworking copy metadata, which is not a used as a staging area, commit draft, or\neven an index.\n\nMoreover, we are not discussing about Git's index file, that low level concept\nwill stay the same, we are talking about the high level concept.\n\n> > stage: a 'stage' is a special area designated for convenience in order\n> > for some activity to take place; an orator would prepare a stage in\n> > order for her speak to be successful, otherwise many people might not\n> > be able to hear, or see her. Git porcelain is using the staging area\n> > precisely as a special area to be separated from the working directory\n> > for convenience.\n> \n> I'm not a native speaker, but in my limited understanding, 'staging' in\n> computer jargon is the process of preparing data for a production system\n> (i.e. until the 'stage' or 'state' of the data is ready for production). It\n> has nothing to do with the 'stage' in a theater.\n\nIt is the same. A stage in the theater is also used for preparing a production.\n\n> I've never heard the term 'staging' beeing used for source code or software\n> (that would be 'integration'). I've also never heard 'staging' for moving\n> data back from a production system to some work- or development area.\n\nThen why are people using it in external documentation? Why is ProGit already using it?\n\nBut more importantly: do you have a better name?\n\n> In any sense, 'staging' is a unidirectional process (even in a theater).\n\nIt is not. Props and utilites are added and removed from the stage.\n\n> If I think of the index as a staging area, it covers just a single use case:\n> preparing new commits.\n\nThat is its main purpose.\n\n> With this world view, it is completely counter-intuitive that e.g. changing\n> branches overwrites my staging area.\n\nWhy would it do that? It's preparing the next commit, on top of which branch is\nnot defined yet.\n\n> IMO, it is ok to use 'like a staging area' when we talk about using the index\n> to prepare new commits.\n\nWhich is how it is being proposed; changing the name of the high-level concept.\n\n> However, its not ok to use 'staging area' as a general synonym for the index.\n\nNobody is proposing that; the low-level \"index file\" stays the same.\n\n-- \nFelipe Contreras\n"},{"id":"229218","messageId":"8FC260D94D1A4711AAA8A0DE7477791B@PhilipOakley","threadId":"35142","inReplyTo":"5261C42E.4050208@gmail.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-10-19T14:08:44Z","receivedAt":"2013-10-19T14:08:44Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Karsten Blees\" \n> Am 15.10.2013 00:29, schrieb Felipe Contreras:\n>> tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we\n>> should move\n>> away from the name \"the index\".\n>>\n>> It has been discussed many times in the past that 'index' is not an\n>> appropriate description for what the high-level user does with it,\n>> and\n>> it has been agreed that 'staging area' is the best term.\n>>\n>\n> I haven't followed the previous discussion, but if a final conclusion\n> towards 'staging area' has already been reached, it should probably be\n> revised.\n\nDo you mean that how that conclusion was reached should be summarised,\nor that you don't think it's an appropriate summary of the broader\nweltanschauung?\n\n>\n>> The term 'staging area' is more intuitive for newcomers which are\n>> more\n>> familiar with English than with Git, and it seems to be a\n>> straightforward mental notion for people with different mother\n>> tongues.\n>>\n>> In fact it is so intuitive that it's used already in a lot online\n>> documentation, and the people that do teach Git professionally use\n>> this\n>> term, because it's easier for many kinds of audiences to grasp.\n>>\n>\n> Such online documentation often portraits the 'staging area' as some\n> supposedly 'unique' git feature, which I find _very_ confusing. In\n> fact, every major SCM has a staging area. E.g. you first need to\n> \"svn/hg/bzr/p4 add/remove/rename/move\" a file, which is somehow\n> recorded in the working copy. These recorded changes will then be\n> picked up by a subsequent \"svn/hg/bzr/p4 commit/submit\".\n>\n> Additionally, all those systems support selectively committing\n> individual files (by specifying the files on the commit command line\n> or selecting them in a GUI).\n>\n> So git's 'unique staging area' boils down to this:\n>\n> 1.) Recording individual files to commit in advance (instead of\n> specifying them at commit time). Which isn't that hard to grasp.\n\nFor many, that separation of preparation(s), from the final action, is\nbrand new and difficult to appreciate - it's special to computer systems\n(where copying is 100% reliable, essentially instantaneous, and in Git's\ncase, 100% verifiable via crypto checksums).\n\n>\n> 2.) Recording individual diff hunks or even lines to commit. Which is\n> an advanced feature that requires even more advanced commands to be\n> useful (i.e. stash save --keep-index; make; test; commit; stash pop).\n> It is also entirely irrelevant to binary files (i.e. for non-technical\n> users that use git to track documents and stuff).\n>\n>> index: an 'index' is a guide of pointers to something else; a book\n>> index has a list of entries so the reader can locate information\n>> easily without having to go through the whole book. Git porcelain is\n>> not using the staging area to find out entries quicker; it's not an\n>> index.\n>>\n>\n> The 'staging area' is a sorted list of most recently checked out\n> files, and its primary purpose is to quickly detect changes in the\n> working copy (i.e. its an index).\n>\n\nThere is a big (human) problem here. We (humans) are able to believe\ncontradictory things (\"He ain't heavy, he's my brother\" to quote a\nsong). The Index (file) isn't a staging area, but we are happy to flip\nflop between the two ideas depending on context - others can feel\nconfused.\n\nIn one sense the \"Index\" is an implementation detail of the concept of a\npacking area where a shipment (commit) is prepared, which is most\ncommonly called the staging are in populist discussions (which I believe \nis the summary I mentioned above)\n\n> Of the 28 builtin main porcelain commands, 18 read the index\n> (read_index), and 11 of those also check the state of the working copy\n> (ie_match_stat). Incidentally, the latter include _all_ commands that\n> update the so-called 'staging area'.\n>\n> Subversion until recently kept the checked out files scattered in\n> **/.svn/text-base directories, and many operations were terribly slow\n> due to this. Subversion 1.7 introduced a new working copy format,\n> based on a database in the root .svn directory (i.e. an index),\n> leading to tremendous performance improvements.\n>\n> The git index is a major feature that facilitates the incredible\n> performance we're so much addicted to...why be shy about it and call\n> it something else?\n>\n>> stage: a 'stage' is a special area designated for convenience in\n>> order\n>> for some activity to take place; an orator would prepare a stage in\n>> order for her speak to be successful, otherwise many people might not\n>> be able to hear, or see her. Git porcelain is using the staging area\n>> precisely as a special area to be separated from the working\n>> directory\n>> for convenience.\n>>\n>\n> I'm not a native speaker, but in my limited understanding, 'staging'\n> in computer jargon is the process of preparing data for a production\n> system (i.e. until the 'stage' or 'state' of the data is ready for\n> production). It has nothing to do with the 'stage' in a theater. I've\n> never heard the term 'staging' beeing used for source code or software\n> (that would be 'integration'). I've also never heard 'staging' for\n> moving data back from a production system to some work- or development\n> area.\n\nEven 'native' speakers don't have a single consistent term for the\nconcept. Terms are stolen from many varied industries and activities\nthat have to prepare and package items (Ships, Trains, Theaters)\n(see http://en.wikipedia.org/wiki/Shipping_list, for a shortish list, \nwhich doesn't mention an Index)\n\n>\n> In any sense, 'staging' is a unidirectional process (even in a\n> theater). If I think of the index as a staging area, it covers just a\n> single use case: preparing new commits. With this world view, it is\n> completely counter-intuitive that e.g. changing branches overwrites my\n> staging area.\n>\n> IMO, it is ok to use 'like a staging area' when we talk about using\n> the index to prepare new commits. However, its not ok to use 'staging\n> area' as a general synonym for the index.\n\nAs alluded to above, the developer viewpoint includes a perception of\nhow we implement the preparation of commits, and how 'we' have come to\nfix on the term 'index'.\n\nIn one sense even that is not the right term - If compared to a book /\npamphlet / monograph (being placed in a Library / repository) it's more \nof a contents list (by chapter and verse / directory and file), with \nvarious bits of front matter such as author, publisher, previous \neditions, introductory preface, dates, contents list, and finally \ncontent. A book's 'index' is a supplementary mini grep of useful terms \nthat the reader may wish to find.\n\nAll in all it's difficult to undo this Gordian knot of confusions.\n\n>\n> Just my 2 cents\n> Karsten\n>\nThe key is probably to separate the devlopers concerns over \nimplementation details from the user's big picture view, in an arena \nthat is short of well (commonly) understood terms.\n\nPhilip\n"},{"id":"229372","messageId":"5268706B.4040303@gmail.com","threadId":"35142","inReplyTo":"8FC260D94D1A4711AAA8A0DE7477791B@PhilipOakley","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Karsten Blees","fromEmail":"karsten.blees@gmail.com","sentAt":"2013-10-24T00:57:15Z","receivedAt":"2013-10-24T00:57:15Z","isPatch":true,"sender":{"key":"karsten.blees@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1111200?v=4"},"body":"Am 19.10.2013 16:08, schrieb Philip Oakley:\n> From: \"Karsten Blees\" \n>> Am 15.10.2013 00:29, schrieb Felipe Contreras:\n>>> tl;dr: everyone except Junio C Hamano and Drew Northup agrees; we\n>>> should move\n>>> away from the name \"the index\".\n>>>\n>>> It has been discussed many times in the past that 'index' is not an\n>>> appropriate description for what the high-level user does with it,\n>>> and\n>>> it has been agreed that 'staging area' is the best term.\n>>>\n>>\n>> I haven't followed the previous discussion, but if a final conclusion\n>> towards 'staging area' has already been reached, it should probably be\n>> revised.\n> \n> Do you mean that how that conclusion was reached should be summarised,\n> or that you don't think it's an appropriate summary of the broader\n> weltanschauung?\n> \n\nThe latter. I don't know about 'broader', but I'll try to summarize _my_ world view:\n\n(1) Audience matters\n\nFor actual users, we need an accurate model that supports a variety of use cases without falling apart. IMO, a working model is more important than simplicity. Finally, its more important to agree on the actual model than on a vague term that can mean many things (theater stage vs. loading dock...).\n\nFor potential users / decision makers, we need to describe git's features in unmistakable terms that don't need extra explanation. In this sense, the index / cache / staging area is not a feature in itself but facilitates a variaty of broader features:\n- fine grained commit control (via index (add -i), but also commit -p, commit --amend, cherry-pick, rebase etc.)\n- performance\n- merging\n\n\n(2) Index\n\nAn index, as in a library, maps almost perfectly to what the git index is _and_ what we do with it. No, I don't mean .so/.dll/.lib files, I'm talking about the real thing with shelves of books and a big box with index cards (aka the index).\n\nThe defining characteristic of a book (or publication in general) is its content, not its physical representation (paper). There are typically many indistinguishable copies of the same book. An author can continue working on the manuscript without affecting the copy at the library at all.\n\nWhen a new or updated publication is submitted to the library, it is first added to the index and placed on a cart at the reception desk. Some time later, the librarian commits the content of the cart to the shelves. A user of the library will typically consult the index to lookup information or to check if his personal copy of a publication is up to date. The index can be thrown away and rebuilt from the content of the shelves. A big library may have a central repository and several local branches (aka field offices) that can be synchronized by comparing their indexes card by card.\n\nGranted, a library is typically not versioned, and its unlikely that any one user will have checked out a full copy of the library's content. But otherwise, its pretty similar to git...\n\n\n(3a) Staging area (logistics)\n\nA staging area, as in (military) logistics / transportation, is about moving physical goods around. You move an item from your stock to the staging area, then onto the truck and finally deliver it to the customer.\n\nThe defining characteristic of a physical good is its physical existence. Each item is uniquely identifiable by a serial number. There may be many of the same kind, but there are no exact copies.\n\nProblem #1: If an item in the staging area is broken, you fix it directly in the staging area, because that's where it _is_. Thus you also don't need to stage the item again. That's how conventional SCMs work: they track the identity (serial number, file name) of things.\n\nProblem #2: The transportation model only supports additions. You cannot add an item to your staging area that, upon delivery, will magically remove itself from the possession of the customer. Let alone that you'd have to steal it first to be able to physically place it into your staging area.\n\nThis can be fixed by slightly modifying our mental model: instead of real things, lets think about \"staging changes\" (or deltas, or patches). Again, that's what conventional SCMs do and what git exactly does _not_ do.\n\nProblem #3: In logistics, the state / inventory of the customer is irrelevant. If a customer orders an item he already has, its his problem. There's no need for core commands like status, diff or reset, and there's no way to explain what they do with a staging area model. What if a customer buys at another shop without telling us, effectively changing his inventory (git reset --soft)? This shouldn't affect our staging area at all, right? But with git it does...ooops.\n\n(3b) Staging area (other meanings)\n\nI don't see how a stage (as in a theater) is in any way related to the git index.\n\nData staging (as in loading a datawarehouse or web-server) fits to some extent, as its also about copying information, not moving physical things.\n\n[...]\n>>\n>> 1.) Recording individual files to commit in advance (instead of\n>> specifying them at commit time). Which isn't that hard to grasp.\n> \n> For many, that separation of preparation(s), from the final action, is\n> brand new and difficult to appreciate - it's special to computer systems\n> (where copying is 100% reliable, essentially instantaneous, and in Git's\n> case, 100% verifiable via crypto checksums).\n> \n\nI'll try to remember that next time I write a shopping list... :-)\n\n[...]\n> Even 'native' speakers don't have a single consistent term for the\n> concept. Terms are stolen from many varied industries and activities\n> that have to prepare and package items (Ships, Trains, Theaters)\n> (see http://en.wikipedia.org/wiki/Shipping_list, for a shortish list, which doesn't mention an Index)\n\nAll true, but we don't need to steal terms from unrelated fields if information science provides us with the terms we need.\n\n[...]\n> \n> In one sense even that is not the right term - If compared to a book /\n> pamphlet / monograph (being placed in a Library / repository) it's more of a contents list (by chapter and verse / directory and file), with various bits of front matter such as author, publisher, previous editions, introductory preface, dates, contents list, and finally content. A book's 'index' is a supplementary mini grep of useful terms that the reader may wish to find.\n> \n\nYes, a book's index is not the right meaning, as is stock market index or index finger. However, a library index seems to fit quite well.\n\nBy the same logic, I could argue that a file in git is not used as a tool to shape metal, therefore its not a file. Lets call it \"costume\", because a costume in a theater wraps an actor just like a file wraps content.\n\n> All in all it's difficult to undo this Gordian knot of confusions.\n> \n>>\n>> Just my 2 cents\n>> Karsten\n>>\n> The key is probably to separate the devlopers concerns over implementation details from the user's big picture view, in an arena that is short of well (commonly) understood terms.\n> \n\nYes, see my point about audience. Its probably also helpful to distinguish between unbiased SCM newbies and \"braindamaged\" VSS/CVS/SVN folks like me :-)\n\n> Philip\n> \n"},{"id":"229385","messageId":"20131024083247.GA1705@inner.h.apk.li","threadId":"35142","inReplyTo":"5268706B.4040303@gmail.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Andreas Krey","fromEmail":"a.krey@gmx.de","sentAt":"2013-10-24T08:32:47Z","receivedAt":"2013-10-24T08:32:47Z","isPatch":true,"sender":{"key":"a.krey@gmx.de","avatar":"https://avatars.githubusercontent.com/u/37810?v=4"},"body":"On Thu, 24 Oct 2013 02:57:15 +0000, Karsten Blees wrote:\n...\n> The latter. I don't know about 'broader', but I'll try to summarize _my_ world view:\n> \n> (1) Audience matters\n> \n> For actual users, we need an accurate model that supports a variety of use cases without falling apart. IMO, a working model is more important than simplicity. Finally, its more important to agree on the actual model than on a vague term that can mean many things (theater stage vs. loading dock...).\n\nTerms almost invariable mean multiple things in different contexts,\nand assume new meaning in new fields.\n\n> For potential users / decision makers, we need to describe git's features in unmistakable terms that don't need extra explanation. In this sense, the index / cache / staging area is not a feature in itself but facilitates a variaty of broader features:\n> - fine grained commit control (via index (add -i), but also commit -p, commit --amend, cherry-pick, rebase etc.)\n\nThe audience will have a hard time understanding what these features\nactually do (and how they interact) if we hide the underlying model from\nthem - they then need to build that model themselves.\n\nAnd no decision-maker will make the effort to understand either the\noperations you mention or the concept of the staging area, unless they\nare also users.\n\n...\n> An index, as in a library, maps almost perfectly to what the git index is _and_ what we do with it.\n\nNo, it doesn't. The git index actually contains the content of the added\nfiles, not just an identity reference. (Unless, maybe, you consider file\nsha1s as a reference and not actual content.) The point is that the\nindex doesn't just contain a mapping from file names to some objects,\nbut de facto a tree - that will form the next commit.\n\n...\n> (3a) Staging area (logistics)\n> \n> A staging area, as in (military) logistics / transportation, is about moving physical goods around. You move an item from your stock to the staging area, then onto the truck and finally deliver it to the customer.\n> \n> The defining characteristic of a physical good is its physical existence. Each item is uniquely identifiable by a serial number.\n\nPlease show me the serial numbers on bullets.\n\n> Problem #1: If an item in the staging area is broken, you fix it directly in the staging area, because that's where it _is_.\n\nThat may be true in a physical world, and may not be - you can as well\nreplace them instead of repairing them in place.\n\nThe real problem: You can find some reason why any possible existing\nname for this concept isn't correct.\n\n...\n> I don't see how a stage (as in a theater) is in any way related to the git index.\n\nIt's because the name 'stage (noun)' goes with the verb 'stage'. You\nstage a play, or you stage content to be committed. From that, you\nmay almost call the index just 'stage'.\n\nAndreas\n\n-- \n\"Totally trivial. Famous last words.\"\nFrom: Linus Torvalds \nDate: Fri, 22 Jan 2010 07:29:21 -0800\n"},{"id":"229472","messageId":"5269ab14157b8_6704135de7c73@nysa.notmuch","threadId":"35142","inReplyTo":"5268706B.4040303@gmail.com","subject":"Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-10-24T23:19:48Z","receivedAt":"2013-10-24T23:19:48Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Karsten Blees wrote:\n> (2) Index\n> \n> An index, as in a library, maps almost perfectly to what the git index is\n> _and_ what we do with it.\n\nNot really. An index in the context of a library, and in any other context, is\na tool that indicates where something is, in order to find it quickly.\n\nThat is not how the Git index is used, nor what it is.\n\n> (3b) Staging area (other meanings)\n> \n> I don't see how a stage (as in a theater) is in any way related to the git\n> index.\n> \n> Data staging (as in loading a datawarehouse or web-server) fits to some\n> extent, as its also about copying information, not moving physical things.\n\nA stage in theater, and in any other context, is a special place, a standing\nplace, I don't see what is so different from the git staging area.\n\n> > Even 'native' speakers don't have a single consistent term for the\n> > concept. Terms are stolen from many varied industries and activities\n> > that have to prepare and package items (Ships, Trains, Theaters)\n> > (see http://en.wikipedia.org/wiki/Shipping_list, for a shortish list, which doesn't mention an Index)\n> \n> All true, but we don't need to steal terms from unrelated fields if\n> information science provides us with the terms we need.\n\nBut it doesn't.\n\n-- \nFelipe Contreras\n"}]}