{"thread":{"id":"56255","subject":"[PATCH 1/7] stage: add proper 'stage' command","startedAt":"2021-08-11T04:57:33Z","lastAt":"2021-08-11T21:41:04Z","messageCount":24,"participants":["Felipe Contreras","Bagas Sanjaya","Michael J Gruber","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":7},"messages":[{"id":"432439","messageId":"20210811045727.2381-2-felipe.contreras@gmail.com","threadId":"56255","inReplyTo":"20210811045727.2381-1-felipe.contreras@gmail.com","subject":"[PATCH 1/7] stage: add proper 'stage' command","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T04:57:21Z","receivedAt":"2021-08-11T04:57:33Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This is still basically the same as `git add`, but now more easily\nextendable.\n\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/git-stage.txt | 11 ++++++++---\n Makefile                    |  2 +-\n builtin.h                   |  1 +\n builtin/stage.c             | 23 +++++++++++++++++++++++\n git.c                       |  2 +-\n t/t3710-stage.sh            | 20 ++++++++++++++++++++\n 6 files changed, 54 insertions(+), 5 deletions(-)\n create mode 100644 builtin/stage.c\n create mode 100755 t/t3710-stage.sh\n\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex 25bcda936d..3f7b036901 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -9,14 +9,19 @@ git-stage - Add file contents to the staging area\n SYNOPSIS\n --------\n [verse]\n-'git stage' args...\n+'git stage' [options] [--] [<paths>...]\n \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+The staging area is a location where changes are stored in preparation for a commit.\n+\n+This is a synonym for linkgit:git-add[1].\n+\n+SEE ALSO\n+--------\n+linkgit:git-add[1]\n \n GIT\n ---\ndiff --git a/Makefile b/Makefile\nindex c3565fc0f8..0223ed7cb1 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -779,7 +779,6 @@ BUILT_INS += git-maintenance$X\n BUILT_INS += git-merge-subtree$X\n BUILT_INS += git-restore$X\n BUILT_INS += git-show$X\n-BUILT_INS += git-stage$X\n BUILT_INS += git-status$X\n BUILT_INS += git-switch$X\n BUILT_INS += git-whatchanged$X\n@@ -1153,6 +1152,7 @@ BUILTIN_OBJS += builtin/show-branch.o\n BUILTIN_OBJS += builtin/show-index.o\n BUILTIN_OBJS += builtin/show-ref.o\n BUILTIN_OBJS += builtin/sparse-checkout.o\n+BUILTIN_OBJS += builtin/stage.o\n BUILTIN_OBJS += builtin/stash.o\n BUILTIN_OBJS += builtin/stripspace.o\n BUILTIN_OBJS += builtin/submodule--helper.o\ndiff --git a/builtin.h b/builtin.h\nindex 16ecd5586f..d08d803c4f 100644\n--- a/builtin.h\n+++ b/builtin.h\n@@ -218,6 +218,7 @@ int cmd_show(int argc, const char **argv, const char *prefix);\n int cmd_show_branch(int argc, const char **argv, const char *prefix);\n int cmd_show_index(int argc, const char **argv, const char *prefix);\n int cmd_sparse_checkout(int argc, const char **argv, const char *prefix);\n+int cmd_stage(int argc, const char **argv, const char *prefix);\n int cmd_status(int argc, const char **argv, const char *prefix);\n int cmd_stash(int argc, const char **argv, const char *prefix);\n int cmd_stripspace(int argc, const char **argv, const char *prefix);\ndiff --git a/builtin/stage.c b/builtin/stage.c\nnew file mode 100644\nindex 0000000000..4dcefbedba\n--- /dev/null\n+++ b/builtin/stage.c\n@@ -0,0 +1,23 @@\n+/*\n+ * Copyright (C) 2013-2021 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] [--] <paths>...\"),\n+\tNULL\n+};\n+\n+int cmd_stage(int argc, const char **argv, const char *prefix)\n+{\n+\tstruct option options[] = {\n+\t\tOPT_END()\n+\t};\n+\n+\targc = parse_options(argc, argv, prefix, options, stage_usage,\n+\t\tPARSE_OPT_KEEP_ARGV0 | PARSE_OPT_KEEP_UNKNOWN | PARSE_OPT_KEEP_DASHDASH);\n+\n+\treturn cmd_add(argc, argv, prefix);\n+}\ndiff --git a/git.c b/git.c\nindex 18bed9a996..3b92e60329 100644\n--- a/git.c\n+++ b/git.c\n@@ -599,7 +599,7 @@ static struct cmd_struct commands[] = {\n \t{ \"show-index\", cmd_show_index, RUN_SETUP_GENTLY },\n \t{ \"show-ref\", cmd_show_ref, RUN_SETUP },\n \t{ \"sparse-checkout\", cmd_sparse_checkout, RUN_SETUP | NEED_WORK_TREE },\n-\t{ \"stage\", cmd_add, RUN_SETUP | NEED_WORK_TREE },\n+\t{ \"stage\", cmd_stage, RUN_SETUP | NEED_WORK_TREE },\n \t{ \"stash\", cmd_stash, RUN_SETUP | NEED_WORK_TREE },\n \t{ \"status\", cmd_status, RUN_SETUP | NEED_WORK_TREE },\n \t{ \"stripspace\", cmd_stripspace },\ndiff --git a/t/t3710-stage.sh b/t/t3710-stage.sh\nnew file mode 100755\nindex 0000000000..2bf59905ca\n--- /dev/null\n+++ b/t/t3710-stage.sh\n@@ -0,0 +1,20 @@\n+#!/bin/sh\n+#\n+# Copyright (C) 2021 Felipe Contreras\n+#\n+\n+test_description='Tests of git stage'\n+\n+. ./test-lib.sh\n+\n+in_stage () {\n+\ttest \"$(git ls-files \"$1\")\" == \"$1\"\n+}\n+\n+test_expect_success 'basic' '\n+\ttouch foo &&\n+\tgit stage foo &&\n+\tin_stage foo\n+'\n+\n+test_done\n-- \n2.32.0.48.g096519100f\n\n"},{"id":"432440","messageId":"20210811045727.2381-1-felipe.contreras@gmail.com","threadId":"56255","inReplyTo":null,"subject":"[PATCH 0/7] [un]stage: officially start moving to \"staging area\"","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T04:57:20Z","receivedAt":"2021-08-11T04:57:33Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"In the last 13 years of discussions virtually *everyone* has agreed that\nthe term \"the index\" is not a good approximation to how most users\nperceive and utilize this feature. For a summary of the discssions see\nmy blog post [1].\n\nThis is particularly true of newcomers, which is why everyone that\nteaches git uses the term \"staging area\".\n\nAmong all the proposals for a better name \"staging area\" is by far the\none with the most consensus.\n\nEveryone except two people agreed that \"the index\" is not a good term.\n\nAll non-official documentation already uses the term \"staging area\" [2]\n[3] [4], including what is considered by most people the best\ndocumentation out there: the Pro Git book.\n\nThere is absolutely no reason not to start using the term \"staging area\"\nofficially.\n\nLet's start by making the staging area a first-class citizen and making\n'git stage' a prominent command, similar to 'git branch'. Additionally\nadd 'git unstage' too.\n\nOnly *one* person expressed discontent with the term \"staging area\".\n\nIn favor:\n\n* Felipe Contreras\n* Scott Chacon\n* Jonathan Nieder\n* Matthieu Moy\n* Jeff King\n* Miles Bader\n* Ævar Arnfjörð Bjarmason\n* Jay Soffian\n* Pete Harlan\n* Aghiles\n* Piotr Krukowiecki\n* Phil Hord\n* Victor Engmark\n* David (bouncingcats)\n* Alexey Feldgendler\n* Alexei Sholik\n* Zbigniew Jędrzejewski-Szmek\n* Sebastien Douche\n* Thiago Farina\n* Mark Lodato\n* Philip Oakley\n* William Swanson\n* Ping Yin\n* Hilco Wijbenga\n* Lars Vogel\n* David A. Wheeler\n\n[1] https://felipec.wordpress.com/2021/08/10/git-staging-area-rename/\n[2] https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository\n[3] https://www.atlassian.com/git/tutorials/saving-changes\n[4] https://coderefinery.github.io/git-intro/04-staging-area/\n\nFelipe Contreras (7):\n  stage: add proper 'stage' command\n  stage: add helper to run commands\n  stage: add 'add' subcommand\n  stage: add 'remove' subcommand\n  unstage: add 'unstage' command\n  stage: add 'diff' subcommand\n  stage: add 'edit' command\n\n Documentation/git-stage.txt            |  38 ++++++-\n Documentation/git-unstage.txt          |  25 +++++\n Makefile                               |   2 +-\n builtin.h                              |   2 +\n builtin/stage.c                        | 147 +++++++++++++++++++++++++\n contrib/completion/git-completion.bash |   5 +\n git.c                                  |   3 +-\n t/t3710-stage.sh                       |  51 +++++++++\n 8 files changed, 267 insertions(+), 6 deletions(-)\n create mode 100644 Documentation/git-unstage.txt\n create mode 100644 builtin/stage.c\n create mode 100755 t/t3710-stage.sh\n\n-- \n2.32.0.48.g096519100f\n\n"},{"id":"432441","messageId":"20210811045727.2381-3-felipe.contreras@gmail.com","threadId":"56255","inReplyTo":"20210811045727.2381-1-felipe.contreras@gmail.com","subject":"[PATCH 2/7] stage: add helper to run commands","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T04:57:22Z","receivedAt":"2021-08-11T04:57:39Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Will be useful to run other commands.\n\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n builtin/stage.c | 26 ++++++++++++++++++++++++--\n 1 file changed, 24 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/stage.c b/builtin/stage.c\nindex 4dcefbedba..49016b0d5f 100644\n--- a/builtin/stage.c\n+++ b/builtin/stage.c\n@@ -4,12 +4,34 @@\n \n #include \"builtin.h\"\n #include \"parse-options.h\"\n+#include \"run-command.h\"\n \n static const char *const stage_usage[] = {\n \tN_(\"git stage [options] [--] <paths>...\"),\n \tNULL\n };\n \n+static int rerun(int argc, const char **argv, ...)\n+{\n+\tint ret;\n+\tstruct strvec args = STRVEC_INIT;\n+\tva_list ap;\n+\tconst char *arg;\n+\tint i;\n+\n+\tva_start(ap, argv);\n+\twhile ((arg = va_arg(ap, const char *)))\n+\t\tstrvec_push(&args, arg);\n+\tva_end(ap);\n+\n+\tfor (i = 0; i < argc; i++)\n+\t\tstrvec_push(&args, argv[i]);\n+\n+\tret = run_command_v_opt(args.v, RUN_GIT_CMD);\n+\tstrvec_clear(&args);\n+\treturn ret;\n+}\n+\n int cmd_stage(int argc, const char **argv, const char *prefix)\n {\n \tstruct option options[] = {\n@@ -17,7 +39,7 @@ int cmd_stage(int argc, const char **argv, const char *prefix)\n \t};\n \n \targc = parse_options(argc, argv, prefix, options, stage_usage,\n-\t\tPARSE_OPT_KEEP_ARGV0 | PARSE_OPT_KEEP_UNKNOWN | PARSE_OPT_KEEP_DASHDASH);\n+\t\tPARSE_OPT_KEEP_UNKNOWN | PARSE_OPT_KEEP_DASHDASH);\n \n-\treturn cmd_add(argc, argv, prefix);\n+\treturn rerun(argc, argv, \"add\", NULL);\n }\n-- \n2.32.0.48.g096519100f\n\n"},{"id":"432442","messageId":"20210811045727.2381-4-felipe.contreras@gmail.com","threadId":"56255","inReplyTo":"20210811045727.2381-1-felipe.contreras@gmail.com","subject":"[PATCH 3/7] stage: add 'add' subcommand","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T04:57:23Z","receivedAt":"2021-08-11T04:57:39Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/git-stage.txt            | 15 ++++++++++++---\n builtin/stage.c                        |  4 ++++\n contrib/completion/git-completion.bash |  5 +++++\n t/t3710-stage.sh                       |  6 ++++++\n 4 files changed, 27 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex 3f7b036901..348d7d1d92 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -3,21 +3,30 @@ 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' [options] [--] [<paths>...]\n+'git stage' (-a | --add) [options] [--] [<paths>...]\n \n \n DESCRIPTION\n -----------\n \n-The staging area is a location where changes are stored in preparation for a commit.\n+This command is useful to manage the staging area which is a location where\n+changes are stored in preparation for a commit.\n+\n+Without arguments it's a synonym for linkgit:git-add[1].\n+\n+OPTIONS\n+-------\n+-a::\n+--add::\n+\tAdd changes to the staging area. See linkgit:git-add[1].\n \n-This is a synonym for linkgit:git-add[1].\n \n SEE ALSO\n --------\ndiff --git a/builtin/stage.c b/builtin/stage.c\nindex 49016b0d5f..5a80bbc76c 100644\n--- a/builtin/stage.c\n+++ b/builtin/stage.c\n@@ -8,6 +8,7 @@\n \n static const char *const stage_usage[] = {\n \tN_(\"git stage [options] [--] <paths>...\"),\n+\tN_(\"git stage --add [options] [--] <paths>...\"),\n \tNULL\n };\n \n@@ -34,7 +35,10 @@ static int rerun(int argc, const char **argv, ...)\n \n int cmd_stage(int argc, const char **argv, const char *prefix)\n {\n+\tint add = 0;\n+\n \tstruct option options[] = {\n+\t\tOPT_BOOL_F('a', \"add\", &add, N_(\"add changes\"), PARSE_OPT_NONEG),\n \t\tOPT_END()\n \t};\n \ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex b50c5d0ea3..8656c47f39 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -2376,6 +2376,11 @@ _git_send_email ()\n \n _git_stage ()\n {\n+\tif [[ \"$cur\" == --* ]]; then\n+\t\t__gitcomp_builtin stage\n+\t\treturn\n+\tfi\n+\n \t_git_add\n }\n \ndiff --git a/t/t3710-stage.sh b/t/t3710-stage.sh\nindex 2bf59905ca..225c6dd739 100755\n--- a/t/t3710-stage.sh\n+++ b/t/t3710-stage.sh\n@@ -17,4 +17,10 @@ test_expect_success 'basic' '\n \tin_stage foo\n '\n \n+test_expect_success 'add' '\n+\ttouch bar &&\n+\tgit stage --add bar &&\n+\tin_stage bar\n+'\n+\n test_done\n-- \n2.32.0.48.g096519100f\n\n"},{"id":"432443","messageId":"20210811045727.2381-5-felipe.contreras@gmail.com","threadId":"56255","inReplyTo":"20210811045727.2381-1-felipe.contreras@gmail.com","subject":"[PATCH 4/7] stage: add 'remove' subcommand","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T04:57:24Z","receivedAt":"2021-08-11T04:57:41Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/git-stage.txt | 6 ++++++\n builtin/stage.c             | 7 ++++++-\n t/t3710-stage.sh            | 5 +++++\n 3 files changed, 17 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex 348d7d1d92..e2f83783b2 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -11,6 +11,7 @@ SYNOPSIS\n [verse]\n 'git stage' [options] [--] [<paths>...]\n 'git stage' (-a | --add) [options] [--] [<paths>...]\n+'git stage' (-r | --remove) [options] [--] [<paths>...]\n \n \n DESCRIPTION\n@@ -27,10 +28,15 @@ OPTIONS\n --add::\n \tAdd changes to the staging area. See linkgit:git-add[1].\n \n+-r::\n+--remove::\n+\tRemove changes from the staging area. See linkgit:git-reset[1].\n+\n \n SEE ALSO\n --------\n linkgit:git-add[1]\n+linkgit:git-reset[1]\n \n GIT\n ---\ndiff --git a/builtin/stage.c b/builtin/stage.c\nindex 5a80bbc76c..dee8781dc5 100644\n--- a/builtin/stage.c\n+++ b/builtin/stage.c\n@@ -9,6 +9,7 @@\n static const char *const stage_usage[] = {\n \tN_(\"git stage [options] [--] <paths>...\"),\n \tN_(\"git stage --add [options] [--] <paths>...\"),\n+\tN_(\"git stage --remove [options] [--] <paths>...\"),\n \tNULL\n };\n \n@@ -35,15 +36,19 @@ static int rerun(int argc, const char **argv, ...)\n \n int cmd_stage(int argc, const char **argv, const char *prefix)\n {\n-\tint add = 0;\n+\tint add = 0, remove = 0;\n \n \tstruct option options[] = {\n \t\tOPT_BOOL_F('a', \"add\", &add, N_(\"add changes\"), PARSE_OPT_NONEG),\n+\t\tOPT_BOOL_F('r', \"remove\", &remove, N_(\"remove changes\"), PARSE_OPT_NONEG),\n \t\tOPT_END()\n \t};\n \n \targc = parse_options(argc, argv, prefix, options, stage_usage,\n \t\tPARSE_OPT_KEEP_UNKNOWN | PARSE_OPT_KEEP_DASHDASH);\n \n+\tif (remove)\n+\t\treturn rerun(argc, argv, \"reset\", NULL);\n+\n \treturn rerun(argc, argv, \"add\", NULL);\n }\ndiff --git a/t/t3710-stage.sh b/t/t3710-stage.sh\nindex 225c6dd739..209f2bde9a 100755\n--- a/t/t3710-stage.sh\n+++ b/t/t3710-stage.sh\n@@ -23,4 +23,9 @@ test_expect_success 'add' '\n \tin_stage bar\n '\n \n+test_expect_success 'remove' '\n+\tgit stage --remove bar &&\n+\t! in_stage bar\n+'\n+\n test_done\n-- \n2.32.0.48.g096519100f\n\n"},{"id":"432444","messageId":"20210811045727.2381-6-felipe.contreras@gmail.com","threadId":"56255","inReplyTo":"20210811045727.2381-1-felipe.contreras@gmail.com","subject":"[PATCH 5/7] unstage: add 'unstage' command","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T04:57:25Z","receivedAt":"2021-08-11T04:57:44Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/git-unstage.txt | 25 +++++++++++++++++++++++++\n builtin.h                     |  1 +\n builtin/stage.c               | 15 +++++++++++++++\n git.c                         |  1 +\n t/t3710-stage.sh              |  7 +++++++\n 5 files changed, 49 insertions(+)\n create mode 100644 Documentation/git-unstage.txt\n\ndiff --git a/Documentation/git-unstage.txt b/Documentation/git-unstage.txt\nnew file mode 100644\nindex 0000000000..cafc24cb36\n--- /dev/null\n+++ b/Documentation/git-unstage.txt\n@@ -0,0 +1,25 @@\n+git-unstage(1)\n+==============\n+\n+NAME\n+----\n+git-unstage - Remove changes from the staging area\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+'git unstage' [options] [--] [<paths>...]\n+\n+DESCRIPTION\n+-----------\n+\n+Removes changes from the staging area. This is the same as `git reset`.\n+\n+SEE ALSO\n+--------\n+linkgit:git-reset[1]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/builtin.h b/builtin.h\nindex d08d803c4f..326f8af3e7 100644\n--- a/builtin.h\n+++ b/builtin.h\n@@ -229,6 +229,7 @@ int cmd_tag(int argc, const char **argv, const char *prefix);\n int cmd_tar_tree(int argc, const char **argv, const char *prefix);\n int cmd_unpack_file(int argc, const char **argv, const char *prefix);\n int cmd_unpack_objects(int argc, const char **argv, const char *prefix);\n+int cmd_unstage(int argc, const char **argv, const char *prefix);\n int cmd_update_index(int argc, const char **argv, const char *prefix);\n int cmd_update_ref(int argc, const char **argv, const char *prefix);\n int cmd_update_server_info(int argc, const char **argv, const char *prefix);\ndiff --git a/builtin/stage.c b/builtin/stage.c\nindex dee8781dc5..2d50b3c393 100644\n--- a/builtin/stage.c\n+++ b/builtin/stage.c\n@@ -13,6 +13,11 @@ static const char *const stage_usage[] = {\n \tNULL\n };\n \n+static const char *const unstage_usage[] = {\n+\tN_(\"git unstage [options] [--] <paths>...\"),\n+\tNULL\n+};\n+\n static int rerun(int argc, const char **argv, ...)\n {\n \tint ret;\n@@ -52,3 +57,13 @@ int cmd_stage(int argc, const char **argv, const char *prefix)\n \n \treturn rerun(argc, argv, \"add\", NULL);\n }\n+\n+int cmd_unstage(int argc, const char **argv, const char *prefix)\n+{\n+\tstruct option options[] = { OPT_END() };\n+\n+\targc = parse_options(argc, argv, prefix, options, unstage_usage,\n+\t\tPARSE_OPT_KEEP_UNKNOWN | PARSE_OPT_KEEP_DASHDASH);\n+\n+\treturn rerun(argc, argv, \"reset\", NULL);\n+}\ndiff --git a/git.c b/git.c\nindex 3b92e60329..2d319cc15b 100644\n--- a/git.c\n+++ b/git.c\n@@ -607,6 +607,7 @@ static struct cmd_struct commands[] = {\n \t{ \"switch\", cmd_switch, RUN_SETUP | NEED_WORK_TREE },\n \t{ \"symbolic-ref\", cmd_symbolic_ref, RUN_SETUP },\n \t{ \"tag\", cmd_tag, RUN_SETUP | DELAY_PAGER_CONFIG },\n+\t{ \"unstage\", cmd_unstage, RUN_SETUP | NEED_WORK_TREE },\n \t{ \"unpack-file\", cmd_unpack_file, RUN_SETUP | NO_PARSEOPT },\n \t{ \"unpack-objects\", cmd_unpack_objects, RUN_SETUP | NO_PARSEOPT },\n \t{ \"update-index\", cmd_update_index, RUN_SETUP },\ndiff --git a/t/t3710-stage.sh b/t/t3710-stage.sh\nindex 209f2bde9a..834eee66d5 100755\n--- a/t/t3710-stage.sh\n+++ b/t/t3710-stage.sh\n@@ -28,4 +28,11 @@ test_expect_success 'remove' '\n \t! in_stage bar\n '\n \n+test_expect_success 'unstage' '\n+\ttouch bar &&\n+\tgit stage bar &&\n+\tgit unstage bar &&\n+\t! in_stage bar\n+'\n+\n test_done\n-- \n2.32.0.48.g096519100f\n\n"},{"id":"432445","messageId":"20210811045727.2381-7-felipe.contreras@gmail.com","threadId":"56255","inReplyTo":"20210811045727.2381-1-felipe.contreras@gmail.com","subject":"[PATCH 6/7] stage: add 'diff' subcommand","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T04:57:26Z","receivedAt":"2021-08-11T04:57:45Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/git-stage.txt | 5 +++++\n builtin/stage.c             | 6 +++++-\n t/t3710-stage.sh            | 7 +++++++\n 3 files changed, 17 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex e2f83783b2..460a8d6228 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -12,6 +12,7 @@ SYNOPSIS\n 'git stage' [options] [--] [<paths>...]\n 'git stage' (-a | --add) [options] [--] [<paths>...]\n 'git stage' (-r | --remove) [options] [--] [<paths>...]\n+'git stage' (-d | --diff) [options] [--] [<paths>...]\n \n \n DESCRIPTION\n@@ -32,11 +33,15 @@ OPTIONS\n --remove::\n \tRemove changes from the staging area. See linkgit:git-reset[1].\n \n+-d::\n+--diff::\n+\tView the changes staged for the next commit. See linkgit:git-diff[1].\n \n SEE ALSO\n --------\n linkgit:git-add[1]\n linkgit:git-reset[1]\n+linkgit:git-diff[1]\n \n GIT\n ---\ndiff --git a/builtin/stage.c b/builtin/stage.c\nindex 2d50b3c393..c57bb2d683 100644\n--- a/builtin/stage.c\n+++ b/builtin/stage.c\n@@ -10,6 +10,7 @@ static const char *const stage_usage[] = {\n \tN_(\"git stage [options] [--] <paths>...\"),\n \tN_(\"git stage --add [options] [--] <paths>...\"),\n \tN_(\"git stage --remove [options] [--] <paths>...\"),\n+\tN_(\"git stage --diff [options] [<commit>] [--] <paths>...\"),\n \tNULL\n };\n \n@@ -41,11 +42,12 @@ static int rerun(int argc, const char **argv, ...)\n \n int cmd_stage(int argc, const char **argv, const char *prefix)\n {\n-\tint add = 0, remove = 0;\n+\tint add = 0, remove = 0, diff = 0;\n \n \tstruct option options[] = {\n \t\tOPT_BOOL_F('a', \"add\", &add, N_(\"add changes\"), PARSE_OPT_NONEG),\n \t\tOPT_BOOL_F('r', \"remove\", &remove, N_(\"remove changes\"), PARSE_OPT_NONEG),\n+\t\tOPT_BOOL_F('d', \"diff\", &diff, N_(\"show changes\"), PARSE_OPT_NONEG),\n \t\tOPT_END()\n \t};\n \n@@ -54,6 +56,8 @@ int cmd_stage(int argc, const char **argv, const char *prefix)\n \n \tif (remove)\n \t\treturn rerun(argc, argv, \"reset\", NULL);\n+\tif (diff)\n+\t\treturn rerun(argc, argv, \"diff\", \"--staged\", NULL);\n \n \treturn rerun(argc, argv, \"add\", NULL);\n }\ndiff --git a/t/t3710-stage.sh b/t/t3710-stage.sh\nindex 834eee66d5..aab979c20c 100755\n--- a/t/t3710-stage.sh\n+++ b/t/t3710-stage.sh\n@@ -35,4 +35,11 @@ test_expect_success 'unstage' '\n \t! in_stage bar\n '\n \n+test_expect_success 'diff' '\n+\techo foo > foo &&\n+\tgit stage --add foo &&\n+\tgit stage --diff > out &&\n+\ttest_file_not_empty out\n+'\n+\n test_done\n-- \n2.32.0.48.g096519100f\n\n"},{"id":"432446","messageId":"20210811045727.2381-8-felipe.contreras@gmail.com","threadId":"56255","inReplyTo":"20210811045727.2381-1-felipe.contreras@gmail.com","subject":"[PATCH 7/7] stage: add 'edit' command","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T04:57:27Z","receivedAt":"2021-08-11T04:57:47Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/git-stage.txt |  5 +++\n builtin/stage.c             | 76 ++++++++++++++++++++++++++++++++++++-\n t/t3710-stage.sh            |  6 +++\n 3 files changed, 86 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex 460a8d6228..baea9d96e0 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -13,6 +13,7 @@ SYNOPSIS\n 'git stage' (-a | --add) [options] [--] [<paths>...]\n 'git stage' (-r | --remove) [options] [--] [<paths>...]\n 'git stage' (-d | --diff) [options] [--] [<paths>...]\n+'git stage' (-e | --edit)\n \n \n DESCRIPTION\n@@ -37,6 +38,10 @@ OPTIONS\n --diff::\n \tView the changes staged for the next commit. See linkgit:git-diff[1].\n \n+-e::\n+--edit::\n+\tEdit the changes in the staging area.\n+\n SEE ALSO\n --------\n linkgit:git-add[1]\ndiff --git a/builtin/stage.c b/builtin/stage.c\nindex c57bb2d683..49af18dda7 100644\n--- a/builtin/stage.c\n+++ b/builtin/stage.c\n@@ -5,6 +5,9 @@\n #include \"builtin.h\"\n #include \"parse-options.h\"\n #include \"run-command.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] [--] <paths>...\"),\n@@ -40,14 +43,83 @@ static int rerun(int argc, const char **argv, ...)\n \treturn ret;\n }\n \n+static int do_reset(const char *prefix)\n+{\n+\tconst char *argv[] = { \"reset\", \"--quiet\", NULL };\n+\treturn run_command_v_opt(argv, RUN_GIT_CMD);\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 run_command_v_opt(argv, RUN_GIT_CMD);\n+}\n+\n+static int run_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+\trepo_read_index(the_repository);\n+\n+\trepo_init_revisions(the_repository, &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(the_repository, the_repository->hash_algo->empty_tree);\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+\trev.diffopt.flags.ignore_dirty_submodules = 1;\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, DIFF_INDEX_CACHED))\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-\tint add = 0, remove = 0, diff = 0;\n+\tint add = 0, remove = 0, diff = 0, edit = 0;\n \n \tstruct option options[] = {\n \t\tOPT_BOOL_F('a', \"add\", &add, N_(\"add changes\"), PARSE_OPT_NONEG),\n \t\tOPT_BOOL_F('r', \"remove\", &remove, N_(\"remove changes\"), PARSE_OPT_NONEG),\n \t\tOPT_BOOL_F('d', \"diff\", &diff, N_(\"show changes\"), PARSE_OPT_NONEG),\n+\t\tOPT_BOOL_F('e', \"edit\", &edit, N_(\"edit changes\"), PARSE_OPT_NONEG),\n \t\tOPT_END()\n \t};\n \n@@ -58,6 +130,8 @@ int cmd_stage(int argc, const char **argv, const char *prefix)\n \t\treturn rerun(argc, argv, \"reset\", NULL);\n \tif (diff)\n \t\treturn rerun(argc, argv, \"diff\", \"--staged\", NULL);\n+\tif (edit)\n+\t\treturn run_edit(argc, argv, prefix);\n \n \treturn rerun(argc, argv, \"add\", NULL);\n }\ndiff --git a/t/t3710-stage.sh b/t/t3710-stage.sh\nindex aab979c20c..3c9522249f 100755\n--- a/t/t3710-stage.sh\n+++ b/t/t3710-stage.sh\n@@ -42,4 +42,10 @@ test_expect_success 'diff' '\n \ttest_file_not_empty out\n '\n \n+test_expect_success 'edit' '\n+\tGIT_EDITOR=\"sed -i -e \\\"s/^+foo$/+edit/\\\"\" git stage --edit &&\n+\tgit stage --diff > out &&\n+\tgrep \"^+edit$\" out\n+'\n+\n test_done\n-- \n2.32.0.48.g096519100f\n\n"},{"id":"432449","messageId":"8034894f-a8dd-e1ee-1825-7cb172afdba3@gmail.com","threadId":"56255","inReplyTo":"20210811045727.2381-7-felipe.contreras@gmail.com","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-08-11T06:12:11Z","receivedAt":"2021-08-11T06:12:17Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 11/08/21 11.57, Felipe Contreras wrote:\n> @@ -12,6 +12,7 @@ SYNOPSIS\n>   'git stage' [options] [--] [<paths>...]\n>   'git stage' (-a | --add) [options] [--] [<paths>...]\n>   'git stage' (-r | --remove) [options] [--] [<paths>...]\n> +'git stage' (-d | --diff) [options] [--] [<paths>...]\n>   \n>   \n>   DESCRIPTION\n> @@ -32,11 +33,15 @@ OPTIONS\n>   --remove::\n>   \tRemove changes from the staging area. See linkgit:git-reset[1].\n>   \n> +-d::\n> +--diff::\n> +\tView the changes staged for the next commit. See linkgit:git-diff[1].\n>   \n\nIs it synonym to `git diff --staged`?\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"432454","messageId":"61137b336b712_209a208f7@natae.notmuch","threadId":"56255","inReplyTo":"8034894f-a8dd-e1ee-1825-7cb172afdba3@gmail.com","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T07:24:35Z","receivedAt":"2021-08-11T07:24:40Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Bagas Sanjaya wrote:\n> On 11/08/21 11.57, Felipe Contreras wrote:\n> > @@ -12,6 +12,7 @@ SYNOPSIS\n> >   'git stage' [options] [--] [<paths>...]\n> >   'git stage' (-a | --add) [options] [--] [<paths>...]\n> >   'git stage' (-r | --remove) [options] [--] [<paths>...]\n> > +'git stage' (-d | --diff) [options] [--] [<paths>...]\n> >   \n> >   \n> >   DESCRIPTION\n> > @@ -32,11 +33,15 @@ OPTIONS\n> >   --remove::\n> >   \tRemove changes from the staging area. See linkgit:git-reset[1].\n> >   \n> > +-d::\n> > +--diff::\n> > +\tView the changes staged for the next commit. See linkgit:git-diff[1].\n> >   \n> \n> Is it synonym to `git diff --staged`?\n\nYes, it's the same thing.\n\nAlthough from discussions in 2013 people found it odd that the option is\n--staged when specifying something that affects the future. It should\nprobably be `git diff --stage`.\n\n-- \nFelipe Contreras\n"},{"id":"432476","messageId":"162867867735.7067.8548435810107710895.git@grubix.eu","threadId":"56255","inReplyTo":"20210811045727.2381-1-felipe.contreras@gmail.com","subject":"Re: [PATCH 0/7] [un]stage: officially start moving to \"staging area\"","fromName":"Michael J Gruber","fromEmail":"git@grubix.eu","sentAt":"2021-08-11T10:44:37Z","receivedAt":"2021-08-11T10:50:41Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Felipe Contreras venit, vidit, dixit 2021-08-11 06:57:20:\n> In the last 13 years of discussions virtually *everyone* has agreed that\n> the term \"the index\" is not a good approximation to how most users\n> perceive and utilize this feature. For a summary of the discssions see\n> my blog post [1].\n> \n> This is particularly true of newcomers, which is why everyone that\n> teaches git uses the term \"staging area\".\n> \n> Among all the proposals for a better name \"staging area\" is by far the\n> one with the most consensus.\n> \n> Everyone except two people agreed that \"the index\" is not a good term.\n> \n> All non-official documentation already uses the term \"staging area\" [2]\n> [3] [4], including what is considered by most people the best\n> documentation out there: the Pro Git book.\n> \n> There is absolutely no reason not to start using the term \"staging area\"\n> officially.\n> \n> Let's start by making the staging area a first-class citizen and making\n> 'git stage' a prominent command, similar to 'git branch'. Additionally\n> add 'git unstage' too.\n> \n> Only *one* person expressed discontent with the term \"staging area\".\n> \n> In favor:\n> \n> * Felipe Contreras\n> * Scott Chacon\n> * Jonathan Nieder\n> * Matthieu Moy\n> * Jeff King\n> * Miles Bader\n> * Ævar Arnfjörð Bjarmason\n> * Jay Soffian\n> * Pete Harlan\n> * Aghiles\n> * Piotr Krukowiecki\n> * Phil Hord\n> * Victor Engmark\n> * David (bouncingcats)\n> * Alexey Feldgendler\n> * Alexei Sholik\n> * Zbigniew Jędrzejewski-Szmek\n> * Sebastien Douche\n> * Thiago Farina\n> * Mark Lodato\n> * Philip Oakley\n> * William Swanson\n> * Ping Yin\n> * Hilco Wijbenga\n> * Lars Vogel\n> * David A. Wheeler\n> \n> [1] https://felipec.wordpress.com/2021/08/10/git-staging-area-rename/\n> [2] https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository\n> [3] https://www.atlassian.com/git/tutorials/saving-changes\n> [4] https://coderefinery.github.io/git-intro/04-staging-area/\n\nOf the many possible ways to restart this discussion, calling out names\nand pitching people against each other is quite possibly the worst.\nIncidentally, this proves (again) what I wrote back then.\n\nGit (the project) has always been about the strive for the \"best\"\nsolution, and different people have different views about the metrics\n(technically sound, user friedly, consistency, backwards compatibility ...),\ntheir scales and their relative weights - and the same is true for\njudging a particular suggested solution in these metrics.\n\nThere are definitely more than two \"staging camps\" in this community -\nyou can come up with a count of \"2\" only if you conflate a multitude of\naspects, such as:\n\n- use the term staging area in documentation\n- scratch the term index from the documentation\n- use \"--staged\" option aliases\n- rename \"--cached\" option to \"--staged\"\n- use \"stage\" command alias for \"add\"\n- rename \"add\" to \"stage\" (and possibly revamp)\n- use pseudorev STAGE (and dump \"--cached\")\n- use pseudorev INDEX (and dump \"--cached\")\n- one of the above plus WORKTREE\n- ...\n\nI would in fact think that this community is comprised of individuals\nrather than camps, and that overall it does not object against the use of\n\"stage/staging area\". At the same time, the fact that 13 years on we\nstill have the same \"git diff --cached\" etc. indicates that we never had\nan alternative concept and implementation which the majority agreed on.\nSo, depending on how you conflate the aspects above into two, either the\n\"pro\" or the \"contra\" camp consists of 1 person, and you can certainly\nreach most 2-partitionings.\n\nJust imagine someone who thinks purely in terms of \"technically sound\"\nand \"backwards compatible\" (you know who you are ;) ): that person will\nnever be \"pro stage\" or \"contra stage\", but if they don't like your\nimplementation of \"git stage\" you will put them in the \"contra camp\",\ngiving up all chances of winning them over technically.\n\n[As a side note, index might be more l10n-friendly than stage because of\nits latin origin (so it's there in more languages already).]\n\nI have been away from the project quite a bit (merely for lack of time),\nbut some people will remember me as striving for \"consistency\" in the UI\n(e.g., favouring \"git diff [HEAD] INDEX\" over \"git diff --cached [HEAD]\").\n\nIndependent of my remarks about the restart of the discussion, I had a\nquick glance at this series. The questions which arose already around\n\"stage/staged\" seem to indicate that the series is more about renaming,\nsome reorganising but not so much about a fresh look at a consistent\nuser experience.\n\nIn other words (and to show a way forward), a cover letter with the\npotential to bring many on board could start with:\n\n##\n\nIt has been 13 years that we discussed about \"the index\", \"the cache\",\n\"staging\" and the \"staging area\". There seemed to be overall consensus\nthat the concept of \"put something on stage that is to be committed [to]\"\nserves well in training and documentation when we explain git's index\nand related commands which change the index (git add) and compare to it\n(git diff --cached).\n\nLet's try and find a common ground for implementing this in user facing\ncommands. Here are a few possible appoaches:\n- command/option aliases\n- command/option renaming\n- revamping of the command structure (as we did \"checkout->switch\")\n- revamping the rev UI (from \"--cached\" to \"INDEX\" or \"STAGE\")\n- you name it\n\nTo kick start this, here are a few more thoughts on some of these/an\nexample implemenation for one of these/...\n\n##\n\n\nCheers\nMichael\n"},{"id":"432489","messageId":"xmqqzgto9dkd.fsf@gitster.g","threadId":"56255","inReplyTo":"8034894f-a8dd-e1ee-1825-7cb172afdba3@gmail.com","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-08-11T16:00:18Z","receivedAt":"2021-08-11T16:00:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya <bagasdotme@gmail.com> writes:\n\n> On 11/08/21 11.57, Felipe Contreras wrote:\n>> @@ -12,6 +12,7 @@ SYNOPSIS\n>>   'git stage' [options] [--] [<paths>...]\n>>   'git stage' (-a | --add) [options] [--] [<paths>...]\n>>   'git stage' (-r | --remove) [options] [--] [<paths>...]\n>> +'git stage' (-d | --diff) [options] [--] [<paths>...]\n>>     \n>>   DESCRIPTION\n>> @@ -32,11 +33,15 @@ OPTIONS\n>>   --remove::\n>>   \tRemove changes from the staging area. See linkgit:git-reset[1].\n>>   +-d::\n>> +--diff::\n>> +\tView the changes staged for the next commit. See linkgit:git-diff[1].\n>>   \n>\n> Is it synonym to `git diff --staged`?\n\nLooks like it.\n\nA more notable aspect of the above list is not the similarity but\ndifference from the rest of Git.  The above organizes various\noperations on the staging area in a single command as its operating\nmodes, so you'd use \"git stage --diff\" for comparing with the\nstaging area but use something else (\"git commit --diff HEAD\"???).\n\nIt is a good example that illustrates that the proposed organization\nmay not help learning or using the system for operations that also\napply to other things like commit and working tree (in other words,\n\"git stage --grep\" may not be such a good idea for the same reason\nas \"git stage --diff\").  But if it were limited to operations that\napply only to the index (e.g. \"git add\" and \"git rm\"), it may be an\nimprovement (I think we added \"git stage\" synonym exactly for that\nreason, already).\n\nHaving said that, if we added \"git stage --remove\", there may be\ncomplaints that say \"the stage command does too many things\", just\nlike those that caused \"checkout\" to be split into \"restore\" (check\nout contents for selected paths in order to work on the current\nbranch) and \"switch\" (check out a branch in order to start working\non it).  I dunno.\n"},{"id":"432494","messageId":"611400ff3e169_30a2087c@natae.notmuch","threadId":"56255","inReplyTo":"162867867735.7067.8548435810107710895.git@grubix.eu","subject":"Re: [PATCH 0/7] [un]stage: officially start moving to \"staging area\"","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T16:55:27Z","receivedAt":"2021-08-11T16:55:34Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Michael J Gruber wrote:\n> Felipe Contreras venit, vidit, dixit 2021-08-11 06:57:20:\n> > In the last 13 years of discussions virtually *everyone* has agreed that\n> > the term \"the index\" is not a good approximation to how most users\n> > perceive and utilize this feature. For a summary of the discssions see\n> > my blog post [1].\n> > \n> > This is particularly true of newcomers, which is why everyone that\n> > teaches git uses the term \"staging area\".\n> > \n> > Among all the proposals for a better name \"staging area\" is by far the\n> > one with the most consensus.\n> > \n> > Everyone except two people agreed that \"the index\" is not a good term.\n> > \n> > All non-official documentation already uses the term \"staging area\" [2]\n> > [3] [4], including what is considered by most people the best\n> > documentation out there: the Pro Git book.\n> > \n> > There is absolutely no reason not to start using the term \"staging area\"\n> > officially.\n> > \n> > Let's start by making the staging area a first-class citizen and making\n> > 'git stage' a prominent command, similar to 'git branch'. Additionally\n> > add 'git unstage' too.\n> > \n> > Only *one* person expressed discontent with the term \"staging area\".\n> > \n> > In favor:\n> > \n> > * Felipe Contreras\n> > * Scott Chacon\n> > * Jonathan Nieder\n> > * Matthieu Moy\n> > * Jeff King\n> > * Miles Bader\n> > * Ævar Arnfjörð Bjarmason\n> > * Jay Soffian\n> > * Pete Harlan\n> > * Aghiles\n> > * Piotr Krukowiecki\n> > * Phil Hord\n> > * Victor Engmark\n> > * David (bouncingcats)\n> > * Alexey Feldgendler\n> > * Alexei Sholik\n> > * Zbigniew Jędrzejewski-Szmek\n> > * Sebastien Douche\n> > * Thiago Farina\n> > * Mark Lodato\n> > * Philip Oakley\n> > * William Swanson\n> > * Ping Yin\n> > * Hilco Wijbenga\n> > * Lars Vogel\n> > * David A. Wheeler\n> > \n> > [1] https://felipec.wordpress.com/2021/08/10/git-staging-area-rename/\n> > [2] https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository\n> > [3] https://www.atlassian.com/git/tutorials/saving-changes\n> > [4] https://coderefinery.github.io/git-intro/04-staging-area/\n> \n> Of the many possible ways to restart this discussion, calling out\n> names and pitching people against each other is quite possibly the\n> worst.  Incidentally, this proves (again) what I wrote back then.\n\nEveryone already agrees that \"staging area\" is a better term than \"the\nindex\".\n\n> Git (the project) has always been about the strive for the \"best\"\n> solution, and different people have different views about the metrics\n> (technically sound, user friedly, consistency, backwards compatibility ...),\n> their scales and their relative weights - and the same is true for\n> judging a particular suggested solution in these metrics.\n> \n> There are definitely more than two \"staging camps\" in this community -\n> you can come up with a count of \"2\" only if you conflate a multitude of\n> aspects, such as:\n\nFor any question there's always three camps: in favor, against, neutral.\n\nIn the particular question of \"staging area\" versus \"the index\" the\nconsensus is overwhelmingly in favor, very very few are neutral, and\nonly one person is against.\n\n> - use the term staging area in documentation\n> - scratch the term index from the documentation\n> - use \"--staged\" option aliases\n> - rename \"--cached\" option to \"--staged\"\n> - use \"stage\" command alias for \"add\"\n> - rename \"add\" to \"stage\" (and possibly revamp)\n> - use pseudorev STAGE (and dump \"--cached\")\n> - use pseudorev INDEX (and dump \"--cached\")\n> - one of the above plus WORKTREE\n> - ...\n\nEach one of these questions has different people in\nfavor/against/neutral and they are mostly orthogonal to each other. For\nexample a person can be in favor of adding the term \"staging area\" in\nthe documentation but neutral to the \"stage\" command alias.\n\nEither way the whole point of my proposal was to shine a light to the\nquestion we have all agreed to: \"staging area\" versus \"the index\".\n\nThis means by extension that everyone (except one person) would be in\nfavor of using the term \"staging area\" in the documentation, which is\nyour first point.\n\nEach one of those points could be implemented in a different patch\nseries, and each patch series can be discussed separately.\n\nBut my main concern is the *first* patch series, regardless of which it\nis, so the term finally becomes official. If you don't like the first\npatch series that I chose, then please state which would it be easier\nfor you to get behind and I'll gladly work on that.\n\nI also have a patch series that implements --stage everywhere, and that\nseries already received feedback in 2014.\n\nThe reason why I chose this point is that 1) it's the one that I find\nmore useful, 2) it's the one that it's easier to implement, 3)\nalready received positive feedback, and 4) I wasn't the only one who\nsuggested this.\n\nIn case you don't remember, you yourself stated \"in principle I like this\na lot\" [1] back in 2011.\n\n> I would in fact think that this community is comprised of individuals\n> rather than camps, and that overall it does not object against the use of\n> \"stage/staging area\".\n\nJunio objects to the use of the term \"staging area\".\n\n> At the same time, the fact that 13 years on we still have the same\n> \"git diff --cached\" etc. indicates that we never had an alternative\n> concept and implementation which the majority agreed on.\n\nNo it doesn't. Git is not a democracy: the majority can agree on\nsomething and yet if Junio disagrees, that's the end of that (as is the\ncase here).\n\n> So, depending on how you conflate the aspects above into two, either the\n> \"pro\" or the \"contra\" camp consists of 1 person, and you can certainly\n> reach most 2-partitionings.\n> \n> Just imagine someone who thinks purely in terms of \"technically sound\"\n> and \"backwards compatible\" (you know who you are ;) ): that person will\n> never be \"pro stage\" or \"contra stage\", but if they don't like your\n> implementation of \"git stage\" you will put them in the \"contra camp\",\n> giving up all chances of winning them over technically.\n\nNo. Being against a particular patch series doesn't necessarily mean\nagainst the spirit of the patch series.\n\nIf that person would rather start with the --stage aliases, or using\n\"staging area\" in the documentation, then that person can simply state\nso on this patch series, and I will work on that instead.\n\n> [As a side note, index might be more l10n-friendly than stage because of\n> its latin origin (so it's there in more languages already).]\n\nWe don't need to go into the hypotheticals of \"might\" because this has\nalready been discussed, and translators already agreed that \"staging\narea\" is better.\n\nAdditionally Ævar Arnfjörð Bjarmason explained [2] that it makes no sense to\nlook for a term in English that is easier to translate, but instead the\nbetter term in English should be picked, and then that meaning is what\ngets translated.\n\nAll this is mentioned in my blog post.\n\n> I have been away from the project quite a bit (merely for lack of time),\n> but some people will remember me as striving for \"consistency\" in the UI\n> (e.g., favouring \"git diff [HEAD] INDEX\" over \"git diff --cached [HEAD]\").\n> \n> Independent of my remarks about the restart of the discussion, I had a\n> quick glance at this series. The questions which arose already around\n> \"stage/staged\" seem to indicate that the series is more about renaming,\n> some reorganising but not so much about a fresh look at a consistent\n> user experience.\n\nI did have a \"fresh look\" at a consistent user experience, and I did\nsend those patches in 2014 [3]. However, those patches had no hope of\ngoing anywhere until Junio agrees to start using the term \"staging area\"\nofficially. So that's what this patch series attempts to do (although\nI'm not hopeful in the least).\n\n> In other words (and to show a way forward), a cover letter with the\n> potential to bring many on board could start with:\n\nOnce again everyone is already on board.\n\n> ##\n> \n> It has been 13 years that we discussed about \"the index\", \"the cache\",\n> \"staging\" and the \"staging area\". There seemed to be overall consensus\n> that the concept of \"put something on stage that is to be committed [to]\"\n> serves well in training and documentation when we explain git's index\n> and related commands which change the index (git add) and compare to it\n> (git diff --cached).\n\nIt didn't \"seem\" there was overall consensus, there *was* close to 100%\nconsensus.\n\n> Let's try and find a common ground for implementing this in user facing\n> commands. Here are a few possible appoaches:\n> - command/option aliases\n> - command/option renaming\n> - revamping of the command structure (as we did \"checkout->switch\")\n> - revamping the rev UI (from \"--cached\" to \"INDEX\" or \"STAGE\")\n> - you name it\n\nMost of these are not practical. For example why start renaming if we\ncan start with aliases, and then later on deprecate the old ones, and\nfinally obsolete them?\n\nAnd again, these have already been discussed before and what people\nseemed to gravitate towards are:\n\n * Officially use \"staging area\" instead of \"the index\" in the\n   documentation\n * Add --stage aliases instead of --cache and --index\n * Make `git stage` more prominent\n\nAnything else would require more discussion, and that's not my goal\nhere (not yet).\n\n> To kick start this, here are a few more thoughts on some of these/an\n> example implemenation for one of these/...\n> \n> ##\n\nI'm all in favor of changing the cover letter and even pick another\npoint on the list to officially start moving to the term \"staging area\",\nbut I think you are missing the main point:\n\nConsensus has *already* been reached.\n\nIn fact, in all my years working on git I have never seen a UI change\nproposal with more consensus.\n\nCheers.\n\n[1] https://lore.kernel.org/git/4D594911.40409@drmicha.warpmail.net/\n[2] https://lore.kernel.org/git/CACBZZX7LOKqKNe09636N0xJ_VvmKP58BMDtjoKn1t5e9hJ0OiQ@mail.gmail.com/\n[3] https://lore.kernel.org/git/1398449567-16314-1-git-send-email-felipe.contreras@gmail.com/\n\n-- \nFelipe Contreras"},{"id":"432496","messageId":"6114062dc362d_30a208f9@natae.notmuch","threadId":"56255","inReplyTo":"xmqqzgto9dkd.fsf@gitster.g","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T17:17:33Z","receivedAt":"2021-08-11T17:17:38Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> A more notable aspect of the above list is not the similarity but\n> difference from the rest of Git.  The above organizes various\n> operations on the staging area in a single command as its operating\n> modes, so you'd use \"git stage --diff\" for comparing with the\n> staging area but use something else (\"git commit --diff HEAD\"???).\n\nIt is not different from the rest of git:\n\n * git branch --delete\n * git tag --delete\n * git remote remove\n * git stash drop\n * git worktree remove\n * git submodule add\n * git config --edit\n * git notes remove\n * git bundle create\n * git bisect start\n\nPlus it's not unusual for commands and options to be redundant,\nespecially when they attempt to simplify or improve the user interface,\nstarting with `git checkout` / `git switch`.\n\n> It is a good example that illustrates that the proposed organization\n> may not help learning or using the system for operations that also\n> apply to other things like commit and working tree (in other words,\n> \"git stage --grep\" may not be such a good idea for the same reason\n> as \"git stage --diff\").  But if it were limited to operations that\n> apply only to the index (e.g. \"git add\" and \"git rm\"), it may be an\n> improvement (I think we added \"git stage\" synonym exactly for that\n> reason, already).\n> \n> Having said that, if we added \"git stage --remove\", there may be\n> complaints that say \"the stage command does too many things\",\n\nOr there might not.\n\n> just like those that caused \"checkout\" to be split into \"restore\"\n> (check out contents for selected paths in order to work on the current\n> branch) and \"switch\" (check out a branch in order to start working on\n> it).  I dunno.\n\nI don't see many people complaining that `git branch` does \"too many\nthings\", neither `git stash` or any of the commands listed above.\n\nMoreover, you are not addressing the most interesting thing my proposal\nenables:\n\n  git stage --edit\n\n-- \nFelipe Contreras\n"},{"id":"432506","messageId":"YRQfx+Njj1WxOnyG@coredump.intra.peff.net","threadId":"56255","inReplyTo":"xmqqzgto9dkd.fsf@gitster.g","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-08-11T19:06:47Z","receivedAt":"2021-08-11T19:06:50Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 11, 2021 at 09:00:18AM -0700, Junio C Hamano wrote:\n\n> A more notable aspect of the above list is not the similarity but\n> difference from the rest of Git.  The above organizes various\n> operations on the staging area in a single command as its operating\n> modes, so you'd use \"git stage --diff\" for comparing with the\n> staging area but use something else (\"git commit --diff HEAD\"???).\n> \n> It is a good example that illustrates that the proposed organization\n> may not help learning or using the system for operations that also\n> apply to other things like commit and working tree (in other words,\n> \"git stage --grep\" may not be such a good idea for the same reason\n> as \"git stage --diff\").  But if it were limited to operations that\n> apply only to the index (e.g. \"git add\" and \"git rm\"), it may be an\n> improvement (I think we added \"git stage\" synonym exactly for that\n> reason, already).\n\nOne thing I find off-putting about \"git stage --diff\" is that to me,\n\"stage\" reads as a verb. So it is like \"git add --diff\", which seems\nout-of-place; there are two verbs in a row.\n\nI do not mind the term \"staging area\", but using \"the stage\" as a noun\nis simply confusing to me in this context.\n\n-Peff\n"},{"id":"432512","messageId":"611430a5b83e1_19f82083b@natae.notmuch","threadId":"56255","inReplyTo":"YRQfx+Njj1WxOnyG@coredump.intra.peff.net","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T20:18:45Z","receivedAt":"2021-08-11T20:18:56Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Wed, Aug 11, 2021 at 09:00:18AM -0700, Junio C Hamano wrote:\n> \n> > A more notable aspect of the above list is not the similarity but\n> > difference from the rest of Git.  The above organizes various\n> > operations on the staging area in a single command as its operating\n> > modes, so you'd use \"git stage --diff\" for comparing with the\n> > staging area but use something else (\"git commit --diff HEAD\"???).\n> > \n> > It is a good example that illustrates that the proposed organization\n> > may not help learning or using the system for operations that also\n> > apply to other things like commit and working tree (in other words,\n> > \"git stage --grep\" may not be such a good idea for the same reason\n> > as \"git stage --diff\").  But if it were limited to operations that\n> > apply only to the index (e.g. \"git add\" and \"git rm\"), it may be an\n> > improvement (I think we added \"git stage\" synonym exactly for that\n> > reason, already).\n> \n> One thing I find off-putting about \"git stage --diff\" is that to me,\n> \"stage\" reads as a verb. So it is like \"git add --diff\", which seems\n> out-of-place; there are two verbs in a row.\n> \n> I do not mind the term \"staging area\", but using \"the stage\" as a noun\n> is simply confusing to me in this context.\n\nOK, but \"stage\" can be a noun.\n\nHere is one of the definitions:\n\n  : a center of attention or scene of action\n\nThis definition doesn't imply what the action is about, but\n\"commit stage\" should be perfectly aligned with that definition.\n\nHere's another one:\n\n  : one of two or more sections of a rocket that have their own fuel and engine\n\nThese rocket stages need to be prepared before the launch, just like\nchanges before a commit. A commit can be thought of as a single-stage\nrocket, and just like parts can be added and removed from this\nsingle-stage before launch, so can changes before a commit.\n\nI understand why this might not seem natural to native English speakers,\nbut it's perfectly aligned with the etymology of the word \"stage\"\n(to stay).\n\nI'm not saying it should be thought of this way, merely that it *can*.\n\n\nEither way, I also thought about adding yet another command\n`git staging-area` and diff instead of an option be a subcommand:\n`git staging-area diff`, but to be frank I don't think anybody would end\nup using this command, especially without default aliases (like\n`git sa`). So I opted against it.\n\nEven though `git stage --diff` is not ideal, it's the least bad option\nin my option.\n\n-- \nFelipe Contreras\n"},{"id":"432513","messageId":"162871314612.7067.6886805754107701040.git@grubix.eu","threadId":"56255","inReplyTo":"YRQfx+Njj1WxOnyG@coredump.intra.peff.net","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Michael J Gruber","fromEmail":"git@grubix.eu","sentAt":"2021-08-11T20:19:06Z","receivedAt":"2021-08-11T20:19:19Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jeff King venit, vidit, dixit 2021-08-11 21:06:47:\n> On Wed, Aug 11, 2021 at 09:00:18AM -0700, Junio C Hamano wrote:\n> \n> > A more notable aspect of the above list is not the similarity but\n> > difference from the rest of Git.  The above organizes various\n> > operations on the staging area in a single command as its operating\n> > modes, so you'd use \"git stage --diff\" for comparing with the\n> > staging area but use something else (\"git commit --diff HEAD\"???).\n> > \n> > It is a good example that illustrates that the proposed organization\n> > may not help learning or using the system for operations that also\n> > apply to other things like commit and working tree (in other words,\n> > \"git stage --grep\" may not be such a good idea for the same reason\n> > as \"git stage --diff\").  But if it were limited to operations that\n> > apply only to the index (e.g. \"git add\" and \"git rm\"), it may be an\n> > improvement (I think we added \"git stage\" synonym exactly for that\n> > reason, already).\n> \n> One thing I find off-putting about \"git stage --diff\" is that to me,\n> \"stage\" reads as a verb. So it is like \"git add --diff\", which seems\n> out-of-place; there are two verbs in a row.\n> \n> I do not mind the term \"staging area\", but using \"the stage\" as a noun\n> is simply confusing to me in this context.\n\nI think this exemplifies what I meant by discussing things in order. The\nconcept \"staging area\" works in teaching and explaining things. But\nthat does not imply that a \"stage command\" is the best way to convey\nthat concept in the UI.\n\nFormost, \"staging area\" is a conceptual item much like a \"commit\", a\n\"rev\", a \"reference\", a \"working tree\" etc.\n\nWhen it comes to the UI, I don't think we have any concept or guide\nto decide what are verbs and nouns, what ends up as a command and what\nas an option or argument. In particular: Do we say \"git verb object\" or\n\"git object verb\"? Consequently, the status quo provides conflicting\nexamples to follow.\n\nTake \"git branch\" and \"git tag\": Both use the term as a noun when they\nlist the refs (but in singular form) and as a verb when they create\nthem. The difference between \"list\" and \"create\" is indicated only by\nthe absence or presence of an argument. We are used to that, and it's\nconvenient, but it's certainly not good UI.\n\nFor other subcommands, they use options like \"-m\" etc.\n\n\"git remote\", \"git submodule\" use arguments to indicate subcommands.\n\nAt least, they stay within their \"realm\" (\"git branch\" acting on branch\nrefs etc.).\n\nThe staging area/index is necessarily something that you not only \"list\"\nor act on, but also compare to other items, or create other items from\n(a commit). A very \"non-verby\" conceptual item, instead an \"object\" (in\nlinguistic terms).\n\nTherefore, \"git stage\" as an alias to \"git add\" does not serve the purpose\nof establishing \"staging area\" very well, and \"git stage --diff\" shows\nexactly the problem with turning an \"object-like item\" into a \"verb-like\ncommand\".\n\nIn fact: \"It adds the current state of pathspec to the staging area\" is\na perfect answer to the question: \"What does git add pathspec do?\"\n\nI mean, so much of git is about operating on or comparing between three\ndifferent types of \"sources\": the working tree, the index, a treeish. A\nlot of confusion comes from the fact that we hide this behind different\ncommands to act on them and different ways to specify these conceptual\nitems:\n- You specify a treeish as an argument to a command.\n- You specify the index as an option (--cached, --staged) or by choosing\n  the right command.\n- You specify the working tree as an option (--worktree) or by choosing\n  the right command (checkout vs. reset) or number of options (diff).\n\nNewer commands like \"restore\" try to help but fail badly when e.g. \"restore\n--staged\" means you overwrite what is staged with something from a\ntreeish.\n\nI still think it's very worthwhile to fantasize about a git which has\nonly verb-like commands (such as diff, add, checkout, checkin) and a\nconsistent way of specifying the objects to act upon (possibly amended\nby \"git pluralnoun\" being synonymous to \"git ls noun\" or similar\nconvenience shortcuts).\n\nMichael\n"},{"id":"432515","messageId":"YRQzbPpk23dVqP+g@coredump.intra.peff.net","threadId":"56255","inReplyTo":"611430a5b83e1_19f82083b@natae.notmuch","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-08-11T20:30:36Z","receivedAt":"2021-08-11T20:30:38Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 11, 2021 at 03:18:45PM -0500, Felipe Contreras wrote:\n\n> > One thing I find off-putting about \"git stage --diff\" is that to me,\n> > \"stage\" reads as a verb. So it is like \"git add --diff\", which seems\n> > out-of-place; there are two verbs in a row.\n> > \n> > I do not mind the term \"staging area\", but using \"the stage\" as a noun\n> > is simply confusing to me in this context.\n> \n> OK, but \"stage\" can be a noun.\n> \n> Here is one of the definitions:\n> \n>   : a center of attention or scene of action\n> \n> This definition doesn't imply what the action is about, but\n> \"commit stage\" should be perfectly aligned with that definition.\n> \n> Here's another one:\n> \n>   : one of two or more sections of a rocket that have their own fuel and engine\n\nSure, I know the various meanings of \"stage\" in English. But I do not find it a\nsynonym for \"staging area\" at all. Now my opinion may not matter, but:\n\n  - I thought the goal of using a different name was to find something\n    that made intuitive sense to English speakers. I do not find \"the\n    stage\" any better than \"the index\" (in fact, I find it worse).\n\n  - Part of your argument seems to be \"many people expressed an opinion\n    that the term 'staging area' was a good idea\". My name was among\n    them.  But in the very email from which you quoted me, I am arguing\n    that \"staging area\" makes sense to me, but \"the stage\" does not.\n\n-Peff\n"},{"id":"432517","messageId":"YRQ11bYH5lV9D24D@coredump.intra.peff.net","threadId":"56255","inReplyTo":"162871314612.7067.6886805754107701040.git@grubix.eu","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-08-11T20:40:53Z","receivedAt":"2021-08-11T20:40:56Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 11, 2021 at 10:19:06PM +0200, Michael J Gruber wrote:\n\n> > > It is a good example that illustrates that the proposed organization\n> > > may not help learning or using the system for operations that also\n> > > apply to other things like commit and working tree (in other words,\n> > > \"git stage --grep\" may not be such a good idea for the same reason\n> > > as \"git stage --diff\").  But if it were limited to operations that\n> > > apply only to the index (e.g. \"git add\" and \"git rm\"), it may be an\n> > > improvement (I think we added \"git stage\" synonym exactly for that\n> > > reason, already).\n> > \n> > One thing I find off-putting about \"git stage --diff\" is that to me,\n> > \"stage\" reads as a verb. So it is like \"git add --diff\", which seems\n> > out-of-place; there are two verbs in a row.\n> > \n> > I do not mind the term \"staging area\", but using \"the stage\" as a noun\n> > is simply confusing to me in this context.\n> \n> I think this exemplifies what I meant by discussing things in order. The\n> concept \"staging area\" works in teaching and explaining things. But\n> that does not imply that a \"stage command\" is the best way to convey\n> that concept in the UI.\n\nYeah, I agree very much that saying \"the term staging area makes sense\"\ndoes not imply that the \"stage command\" is a good idea.\n\n> I mean, so much of git is about operating on or comparing between three\n> different types of \"sources\": the working tree, the index, a treeish. A\n> lot of confusion comes from the fact that we hide this behind different\n> commands to act on them and different ways to specify these conceptual\n> items:\n> - You specify a treeish as an argument to a command.\n> - You specify the index as an option (--cached, --staged) or by choosing\n>   the right command.\n> - You specify the working tree as an option (--worktree) or by choosing\n>   the right command (checkout vs. reset) or number of options (diff).\n> \n> Newer commands like \"restore\" try to help but fail badly when e.g. \"restore\n> --staged\" means you overwrite what is staged with something from a\n> treeish.\n\nAgreed. At one point[1] I half-proposed a \"git put\" command that would\nmove changes between those three places (and giving a concrete name for\nthe index and working tree so they could be specified as sources or\ndestinations).\n\nI do still like it as a conceptual model, but IIRC it gets hairy in some\nof the details (e.g., \"checkout -p HEAD\" is still using the index as an\nintermediary).\n\n> I still think it's very worthwhile to fantasize about a git which has\n> only verb-like commands (such as diff, add, checkout, checkin) and a\n> consistent way of specifying the objects to act upon (possibly amended\n> by \"git pluralnoun\" being synonymous to \"git ls noun\" or similar\n> convenience shortcuts).\n\nI don't really disagree with anything in your post, but I do think a\npure-verb world would be tricky in some ways. Or at least verbose. We\nhave \"git branch --delete\". But \"git delete\" seems a little too\nopen-ended. The concept of that verb is meaningful only in the context\nor a particular noun. We could call it \"git delete-branch\", but that\ndoesn't really seem to make the world a better place. :)\n\n-Peff\n"},{"id":"432518","messageId":"162871511371.7067.11584829113417456747.git@grubix.eu","threadId":"56255","inReplyTo":"YRQ11bYH5lV9D24D@coredump.intra.peff.net","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Michael J Gruber","fromEmail":"git@grubix.eu","sentAt":"2021-08-11T20:51:53Z","receivedAt":"2021-08-11T20:51:58Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jeff King venit, vidit, dixit 2021-08-11 22:40:53:\n> I don't really disagree with anything in your post, but I do think a\n> pure-verb world would be tricky in some ways. Or at least verbose. We\n> have \"git branch --delete\". But \"git delete\" seems a little too\n> open-ended. The concept of that verb is meaningful only in the context\n> or a particular noun. We could call it \"git delete-branch\", but that\n> doesn't really seem to make the world a better place. :)\n\nIn fact I think it does, because it keeps the verb-object order and\navoids \"verbs as options\":\n\ngit rm-branch\ngit rm-tag\ngit rm-remote\ngit ls-branch\ngit ls-tag\ngit ls-remote (yeah, I know... maybe use ls-pluralform instead for all)\n...\n\nMaybe:\ngit branches aliased to \"git ls-branch\" etc. as convenience.\n\nFor sake of convenience, if we have \"ls-pluralform\" (aliased to \"pluralform\")\nwe could even alias \"create-singularform\" to \"singularform\". I mean, I\nwant use this git thing myself ;)\n\nMichael\n"},{"id":"432519","messageId":"xmqq7dgr8zt7.fsf@gitster.g","threadId":"56255","inReplyTo":"162871314612.7067.6886805754107701040.git@grubix.eu","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-08-11T20:57:24Z","receivedAt":"2021-08-11T20:57:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber <git@grubix.eu> writes:\n\n> I still think it's very worthwhile to fantasize about a git which has\n> only verb-like commands (such as diff, add, checkout, checkin) and a\n> consistent way of specifying the objects to act upon (possibly amended\n> by \"git pluralnoun\" being synonymous to \"git ls noun\" or similar\n> convenience shortcuts).\n\nIt is nice to fantasize that the world were without confusing\nmixture of variety of things.\n\nI am not sure if a single \"git create\" command that can be used to\ncreate a new commit (aka \"git commit\"), a new tag (aka \"git tag\"),\nor a new worktree (aka \"git worktree add\"), or a single \"git remove\"\ncommand that can be used to remove a branch (aka \"git branch -d\"), a\ntracked file (aka \"git rm\"), would create a more easy to learn and\nexplain UI.  At some point, I suspect that we would run out verbs\nmore quickily than we can organize commands and concepts in a way\nthat is easy to understand and explain by using them.\n\n"},{"id":"432520","messageId":"YRQ64HDKF4NgacAv@coredump.intra.peff.net","threadId":"56255","inReplyTo":"YRQ11bYH5lV9D24D@coredump.intra.peff.net","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-08-11T21:02:24Z","receivedAt":"2021-08-11T21:02:26Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 11, 2021 at 04:40:54PM -0400, Jeff King wrote:\n\n> Agreed. At one point[1] I half-proposed a \"git put\" command that would\n> move changes between those three places (and giving a concrete name for\n> the index and working tree so they could be specified as sources or\n> destinations).\n\nI forgot my footnote. It's:\n\n  https://lore.kernel.org/git/20110607200659.GA6177@sigill.intra.peff.net/\n\nNot that I really think it's worth anybody's time to dig too far into\nit.\n\n-Peff\n"},{"id":"432521","messageId":"61144021e75ac_1ed6208da@natae.notmuch","threadId":"56255","inReplyTo":"YRQzbPpk23dVqP+g@coredump.intra.peff.net","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T21:24:49Z","receivedAt":"2021-08-11T21:24:56Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Wed, Aug 11, 2021 at 03:18:45PM -0500, Felipe Contreras wrote:\n> \n> > > One thing I find off-putting about \"git stage --diff\" is that to me,\n> > > \"stage\" reads as a verb. So it is like \"git add --diff\", which seems\n> > > out-of-place; there are two verbs in a row.\n> > > \n> > > I do not mind the term \"staging area\", but using \"the stage\" as a noun\n> > > is simply confusing to me in this context.\n> > \n> > OK, but \"stage\" can be a noun.\n> > \n> > Here is one of the definitions:\n> > \n> >   : a center of attention or scene of action\n> > \n> > This definition doesn't imply what the action is about, but\n> > \"commit stage\" should be perfectly aligned with that definition.\n> > \n> > Here's another one:\n> > \n> >   : one of two or more sections of a rocket that have their own fuel and engine\n> \n> Sure, I know the various meanings of \"stage\" in English. But I do not find it a\n> synonym for \"staging area\" at all.\n\nNowhere did I argue that they are synonyms.\n\nI said \"stage\" can be a noun. Just like \"staging area\" is also a noun.\n\nThey do not mean the same thing.\n\n> Now my opinion may not matter, but:\n> \n>   - I thought the goal of using a different name was to find something\n>     that made intuitive sense to English speakers. I do not find \"the\n>     stage\" any better than \"the index\" (in fact, I find it worse).\n\nWe already found something more intuitive to English speakers:\n\"staging area\".\n\n>   - Part of your argument seems to be \"many people expressed an opinion\n>     that the term 'staging area' was a good idea\". My name was among\n>     them.  But in the very email from which you quoted me, I am arguing\n>     that \"staging area\" makes sense to me, but \"the stage\" does not.\n\nI am perfectly aware of that.\n\nEveryone agrees \"staging area\" is the way to go.\n\nHow that gets translated to the user interface is a *different* matter:\n\n  * git diff --staged\n  * git diff --stage\n  * git diff --staging-area\n  * git staging-area --diff\n  * git stage --diff\n\nMy main concern is not precisely how this term gets transcribed to the\nUI, it is that it actually gets done.\n\nIf it's easier to start by updating the documentation to start using\n\"staging area\" since that requires less discussion about term mapping,\nthen I'll gladly attempt that first.\n\n-- \nFelipe Contreras\n"},{"id":"432525","messageId":"611443ebea222_1ed62089f@natae.notmuch","threadId":"56255","inReplyTo":"162871314612.7067.6886805754107701040.git@grubix.eu","subject":"Re: [PATCH 6/7] stage: add 'diff' subcommand","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-08-11T21:40:59Z","receivedAt":"2021-08-11T21:41:04Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Michael J Gruber wrote:\n\n> Therefore, \"git stage\" as an alias to \"git add\" does not serve the purpose\n> of establishing \"staging area\" very well, and \"git stage --diff\" shows\n> exactly the problem with turning an \"object-like item\" into a \"verb-like\n> command\".\n\nBut \"stage\" can be a noun in English too. Just like \"branch\" can be both\na verb and a noun.\n\n> I still think it's very worthwhile to fantasize about a git which has\n> only verb-like commands (such as diff, add, checkout, checkin) and a\n> consistent way of specifying the objects to act upon (possibly amended\n> by \"git pluralnoun\" being synonymous to \"git ls noun\" or similar\n> convenience shortcuts).\n\nThere was a sub-thread in which we fantasized a consistent UI [1], and\ntaking Mercurial as inspiration the way to fix some of the warts would\nbe:\n\n  git branch          # verb\n  git branches new    # noun verb\n  git branches delete # noun verb\n\nNow, it's pretty unlikely that the inconsistencies with `git branch`\nwill ever be fixed, but we can take that as guidance for the staging\narea:\n\n  git stage               # verb\n  git unstage             # verb\n  git staging-area add    # noun verb\n  git staging-area remove # noun verb\n  git staging-area diff   # noun verb\n\nThis I think would be the most consistent way of implementing this, my\nonly problem is that 'staging-area' is too long. Of course users could\neasily write aliases, but git should be easy to use by default.\n\nIf git implemented default aliases as I suggested [2], then I would have\nno problem with 'staging-area', because the user could simply do:\n\n  git sa diff\n\nBut that's a very big *if*.\n\nCheers.\n\n[1] https://lore.kernel.org/git/f0770358-be4c-a747-0851-b2fd73c1978e@mfriebe.de/\n[2] http://lore.kernel.org/git/20210702100506.1422429-1-felipe.contreras@gmail.com\n\n-- \nFelipe Contreras\n"}]}