git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: git diff --added (Re: Command-line interface thoughts)

From
Junio C Hamano <gitster@pobox.com>
Date
Jun 13, 2011, 12:28 UTC
Message-ID
<7vmxhlrk3m.fsf@alter.siamese.dyndns.org>
In-Reply-To
<buotybu2wx7.fsf@dhlpc061.dev.necel.com>
Miles Bader <miles@gnu.org> writes:
Show 6 quoted lines
> Jonathan Nieder <jrnieder@gmail.com> writes:
>> Do you think it would be valuable to introduce --added as a synonym
>> for --cached and slowly steer documentation to encourage the latter
>> in place of the former?
>
> "--added" sounds very awkward though; "--staged" is much more natural.
Actually I think _both_ are equally wrong.

I have to thank you and Jonathan for making me realize the real reason why "staged" didn't sit well in my ears. The word used as adjective nauseated me forever but I couldn't clearly explain why even to myself, but now I have the explanation.

The index has data registered for paths. "add" (and "stage") are verbs used to describe the act of taking data different from what is currently registered in the index and replacing it. The phrase "added contents" thus can be (mis)interpreted to refer to only the subset of the data that is different from what you used to have in the index, typically meaning the ones that are different from HEAD, i.e. you would see the change in the output of "git diff HEAD". This is especially true because many people think in terms of "recording difference from the previous version" when they think about SCMs, and "--added" or "--staged" rhyme well with that mindset.

This potential misinterpretation does not cause problems in some contenxt, and one such context is the hidden synonym "git diff --staged", which _is_ all about the subset of the paths that are different from HEAD.

But as Jonathan in his message and you in your response brilliantly illustrated, misinterpreted "added" and "staged" break down badly in other contexts. When running "git grep" and "git rm" against the data sitting in the index, you do _not_ want to limit your request to the subset of paths in the index that are different from HEAD. "git rm --added" is not a command that chooses paths that are added to the index, and remove these paths from both the index and the working tree, but "added" would invite such a misinterpretation from new people.

The adjective "cached" refers to the _state_ of the data for various paths in the index as they exist, regardless of when or how these contents were placed there. For the majority of the paths the "cached" data may have come from the HEAD, and for other paths, "cached" data may be something you have "added", but because "cached" is a state as it exists in the index, there is no distinction between the two.

Because "cache" nor "index" are never used as verbs that mean the _act_ of putting updated things in the index, we do not risk --cached nor --index to get misinterpreted as limiting to the subset of the paths that are different from HEAD. At least that is how these four words (added, staged, cached and index) sound to my ears, and that is why I said the first two are equally wrong in the beginning of this message.

It is an entirely different issue that "cached" is _not_ the best way to spell "index-only", though.

Previous: Junio C HamanoNext: Holger Hellmuth
Message 37 of 98 in “Command-line interface thoughts”
  1. Michael NahasJun 4, 2011
  2. Jakub NarebskiJun 4, 2011
  3. Michael NahasJun 5, 2011
  4. Jakub NarebskiJun 5, 2011
  5. Scott ChaconJun 5, 2011
  6. Jakub NarebskiJun 5, 2011
  7. Junio C HamanoJun 6, 2011
  8. Michael J GruberJun 6, 2011
  9. Michael NahasJun 6, 2011
  10. Jakub NarebskiJun 6, 2011
  11. Michael J GruberJun 6, 2011
  12. Jakub NarebskiJun 8, 2011
  13. Junio C HamanoJun 6, 2011
  14. Drew NorthupJun 6, 2011
  15. Junio C HamanoJun 6, 2011
  16. Michael J GruberJun 6, 2011
  17. Junio C HamanoJun 6, 2011
  18. Scott ChaconJun 6, 2011
  19. Junio C HamanoJun 6, 2011
  20. Michael J GruberJun 7, 2011
  21. Jonathan NiederJun 7, 2011
  22. Holger HellmuthJun 7, 2011
  23. Jonathan NiederJun 7, 2011
  24. Jakub NarebskiJun 7, 2011
  25. Holger HellmuthJun 8, 2011
  26. Jakub NarebskiJun 8, 2011
  27. Holger HellmuthJun 9, 2011
  28. Jakub NarebskiJun 10, 2011
  29. Holger HellmuthJun 10, 2011
  30. Jakub NarebskiJun 10, 2011
  31. Holger HellmuthJun 10, 2011
  32. git diff --added (Re: Command-line interface thoughts)Jonathan Nieder, Jun 13, 2011
  33. Miles BaderJun 13, 2011
  34. Miles BaderJun 13, 2011
  35. Jonathan NiederJun 13, 2011
  36. Junio C HamanoJun 13, 2011
  37. Junio C HamanoJun 13, 2011
  38. Holger HellmuthJun 13, 2011
  39. Michael NahasJun 13, 2011
  40. Jakub NarebskiJun 13, 2011
  41. Holger HellmuthJun 13, 2011
  42. Michael HaggertyJun 14, 2011
  43. Jakub NarebskiJun 14, 2011
  44. René ScharfeJun 7, 2011
  45. Jakub NarebskiJun 7, 2011
  46. Jakub NarebskiJun 8, 2011
  47. Michael NahasJun 8, 2011
  48. Jakub NarebskiJun 8, 2011
  49. Michael NahasJun 8, 2011
  50. Jeff KingJun 8, 2011
  51. Michael NahasJun 8, 2011
  52. Jeff KingJun 9, 2011
  53. Michael NahasJun 9, 2011
  54. Jakub NarebskiJun 10, 2011
  55. Jakub NarebskiJun 9, 2011
  56. Michael NahasJun 9, 2011
  57. Jakub NarebskiJun 9, 2011
  58. Jakub NarebskiJun 9, 2011
  59. Michael HaggertyJun 9, 2011
  60. Andreas EricssonJun 9, 2011
  61. Thomas RastJun 9, 2011
  62. Jeff KingJun 9, 2011
  63. Jay SoffianJun 9, 2011
  64. Jeff KingJun 9, 2011
  65. Junio C HamanoJun 9, 2011
  66. Jay SoffianJun 9, 2011
  67. Junio C HamanoJun 9, 2011
  68. Michael HaggertyJun 9, 2011
  69. Junio C HamanoJun 9, 2011
  70. Michael HaggertyJun 9, 2011
  71. Jeff KingJun 9, 2011
  72. Michael HaggertyJun 9, 2011
  73. Jakub NarebskiJun 9, 2011
  74. Michael HaggertyJun 9, 2011
  75. Jakub NarebskiJun 10, 2011
  76. Michael NahasJun 10, 2011
  77. Jakub NarebskiJun 10, 2011
  78. Jeff KingJun 9, 2011
  79. Michael NahasJun 9, 2011
  80. Jeff KingJun 9, 2011
  81. Jakub NarebskiJun 9, 2011
  82. Michael NahasJun 10, 2011
  83. Jeff KingJun 10, 2011
  84. Junio C HamanoJun 10, 2011
  85. Junio C HamanoJun 10, 2011
  86. Jakub NarebskiJun 10, 2011
  87. Michael HaggertyJun 12, 2011
  88. Junio C HamanoJun 12, 2011
  89. Michael NahasJun 12, 2011
  90. Junio C HamanoJun 12, 2011
  91. Michael NahasJun 13, 2011
  92. Jeff KingJun 13, 2011
  93. Jeff KingJun 9, 2011
  94. Paul EbermannJun 5, 2011
  95. Paul EbermannJun 5, 2011
  96. Michael NahasJun 7, 2011
  97. Junio C HamanoJun 7, 2011
  98. Michael NahasJun 7, 2011

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.