Jonathan Nieder [off-list ref] writes:
Mark Lodato wrote:
quoted
I agree with Felipe that "staging" is the most appropriate term for
"adding to the index" in git. As a native English speaker, I have
never thought of "to stage" as relating to shipping in any way. To
me, by far the most common usage is in real estate. The seller of a
home "stages" it by setting up furniture and decorations to make the
home as appealing to prospective buyers as possible.
I think staging a home does not fit very well here, actually....
By contrast, if you run an image search for "staging area", you will
see examples in all sorts of fields...
"aire de rassemblement" doesn't get as many hits from a web search,
alas, so I guess the idiom is not as popular in other languages.
All true.
Instead, it would be better to change it to something like:
This command modifies the content staged for the next commit
using content found in the working tree. It typically adds ...
The "index" file (see gitindex(5)) typically holds a snapshot of
the content of the working tree, and it is this snapshot that is
taken as the content of the next commit. Thus after making any
changes to the working directory, and before running the commit
command, you must use the add command to add any new or modified
files.
Sensible?
Comparing between the one before "Instead" and the above one, I would say
it is.
I am hoping that we are not wasting people's time by the same experiment
that already failed very early in Git's history to hide the "concept" of
that which is used to shape the tree that would be recorded in the next
commit that is different from either the current commit nor the contents
in the working tree, and instead this round is about the name of that
thing, which has been called "the index" and also colloquially known as
"the staging area" in many third-party documents.
I personally think it is a wrong way of thinking to focus too much on the
"name", though. The goal should be increased clarity and ease of learning.
For example, the first sentence in your example reads equally well if it
said "the content _prepared_ for the next commit" without losing clarity
and tells the most important thing it must tell the user: that "add" is
about updating "that thing" that is different from the working tree and
the latest commit, even if "stage" (verb) does not translate well to other
language.
About the "git stage --add/rm" commands in your follow-up message, I have
mixed feelings. Once users get that making progress and growing history
with Git is all about interacting with "that thing", writing out a new
tree out of it and recording it in a new commit with appropriate parents,
saying "stage" becomes redundant. You "add", "remove", "patch", etc. to
affect that is recorded in "that thing" (e.g. you do not "add" to commit).
Another reason of my "mixed feelings" is that an interface organized
around what is affected, instead of around what is achieved, may be
counter-productive. "add" that adds the contents in the working tree
(i.e. you already made the change you want yourself) to "that thing" makes
sense from the work-flow point of view. It is how you edit, test or
eyeball to convince yourself that you are happy with what is in your
working tree, and then approach one step closer to your next commit.
An interface built around "that thing" may have a subcommand that adds
contents to "that thing" regardless of what is in your working tree, but
it is useful in only special occasions (e.g. in filter-branch script that
does not want/need to use a temporary working tree). Such a functionality
does have a place to live, namely at the plumbing level, but already is
available as "update-index". But these commands that are organized around
"what" they operate on are and should be of "specialized" kind, not "end
user everyday activity" commands that are designed to give easier time to
people in learning and using the system.
On Sun, May 20, 2012 at 11:11 PM, Junio C Hamano [off-list ref] wrote:
I personally think it is a wrong way of thinking to focus too much on the
"name", though.
Names are important. Name it 'jaberwocky' and people would have a
harder time trying to understand what you are talking about. Maybe
just by hearing the name they would give up, thinking it's too
advanced, or too obscure, or what not.
There have been countless people that say "me too! when I realized it
was X", which suggests the current name does not help.
The goal should be increased clarity and ease of learning.
And using a common/well understood name is a step in the right direction.
But also, once we accept that "that thing" is not an index, then it
becomes much more easy to distinguish between the abstract concept,
and the actual index, and then we can begin to remove the index from
the high-level documentation and squash it to a corner where the user
does not _have_ to go unless she really does want to know the
implementation details.
Right now it's almost impossible to split the "index", and then index.
If the name is not important, why do you think people avoid the official name?
For example, the first sentence in your example reads equally well if it
said "the content _prepared_ for the next commit" without losing clarity
and tells the most important thing it must tell the user: that "add" is
about updating "that thing" that is different from the working tree and
the latest commit, even if "stage" (verb) does not translate well to other
language.
Indeed, but you are missing the important part; everything else in
that sentence.
I will put my end-user hat and read while thinking aloud the current text:
"This command updates the index"
OK, you lost me there. I don't know what is that "index", do I need to
learn what is that in order to understand the command? Maybe I
shouldn't be reading this documentation at all.
But, OK, let's give it a try... Right, an index, well, an index of
what to what? No idea. Maybe if I keep reading.
"using the current content found in the working tree, to prepare the
content staged for the next commit.
OK, maybe I'm beginning to understand... But I'm still not sure if I
should be touching this index thing, I don't understand what is being
indexed.
About the "git stage --add/rm" commands in your follow-up message, I have
mixed feelings. Once users get that making progress and growing history
with Git is all about interacting with "that thing", writing out a new
tree out of it and recording it in a new commit with appropriate parents,
saying "stage" becomes redundant. You "add", "remove", "patch", etc. to
affect that is recorded in "that thing" (e.g. you do not "add" to commit).
While I would not like to touch the 'git stage' at this point--nor do
I think it's needed--, I don't agree with what you said. In certain
commands it might be redundant, but I specially disagree on these:
The 'add' command has a long tradition in SCM; it adds a file for
content tracking--nothing more.
Using 'add' to *update* the staging area seems completely and totally
counter-intuitive to me. Adding something means that something was not
there; if it was there, you couldn't add it.
Of course, that's if you think about files, but it makes sense if you
think about changes instead, but 'git add file' and 'git add file' do
very different things conceptually depending on weather 'file' was
tracked or not; one would "add a file" (to git), and the other would
"add the changes of the file" (to the staging area). Splitting the
command in two would make this difference in concepts clearer.
And then we have all sorts of confusion. --patch; I thought we were
adding patches to the staging area, this is redundant, --selectively
might make more sense. --update; I thought we were updating! --updated
might make more sense. And what happens when you do 'git add --patch
untracked-file' (or --update)? That's very strange.
If we have a 'stage' command things become much simpler:
git add untracked-file # maybe as the current 'git add --intent-to-add'
git add tracked-file # no-op (error?)
git add --patch file # doesn't make sense; option not present
git add --update file # doesn't make sense; option not present
git stage untracked-file # add, and stage it, why not?
git stage tracked-file
git stage --hunks file
git stage --updates file
At this point 'git add' would not be doing much, and might even go
away, but I guess it's nice for people coming from other SCMs.
'rm' is similar, could be solved by 'unstage'.
Either way, I have proposed to use stage/unstage before I think,
without much success, so I think the only realist option to move
forward is to add --stage(d) and --stage-only.
Cheers.
--
Felipe Contreras
Hi Felipe,
Felipe Contreras wrote:
Indeed, but you are missing the important part; everything else in
that sentence.
You're probably onto something, but I'm missing the point in your
message. Could you repeat, carefully explaining:
- what change you would like to propose in git
- whether it is backward compatible, and if it is not, what
transition plan you propose
- briefly, the rationale behind the change, in such a way as to
convince skeptics like me that it is a good idea and to recruit
us to help in your cause
? For that third part, a good example to take inspiration from is the
project to improve Linux to function as a real-time operating system.
Each change is so well justified _individually_ that someone not
interested at all in that goal can still not help but agree with the
changes!
Perhaps your message includes these elements already, but I found it
hard to follow, hence this request.
Thanks,
Jonathan