Junio C Hamano [off-list ref] writes:
Felipe Contreras [off-list ref] writes:
quoted
On Sun, Apr 5, 2009 at 10:02 PM, Junio C Hamano [off-list ref] wrote:
quoted
Felipe Contreras [off-list ref] writes:
quoted
This is the list of actions I've mapped:
* add: git stage = git stage add (git add)
* rm: (git rm --cached)
* diff: (git rm --cached)
* import: stage all files; modified, deleted, new
* ls: (git ls-files --stage)
I do not think these are good ideas at all, as it just spreads more
confusion, not less.
Do you agree that there's already a lot of confusion? (stage, cache,
index, etc.)
And do you agree that many git newbies don't use the stage? Actually
most of them don't even know what it is, and just do "git commit -a".
If so, how do you think these issues should be handled?
Perhaps not spreading "stage" even wider? That is the newest confusing
term that caused the most harm.
This probably needs clarification for new people who do not know the
history.
Before Linus published the very original git, he was designing a system
that can work with the tarball+patches workflow, and dircache (which was
the name of the .git directory) was a mechanism to give various snapshots
a faster access by using the git object machinery by "caching" the result
of applying sequence of patches to certain point of history. The file
inside the .dircache that records the object names that correspond to the
state in the work tree state was .dircache/index.
We've been living with the cache/index, and many user visible actions have
been called in sentences like "adding contents to the cache" or "comparing
with the index" that used cache/index more or less interchangeably. Later
we started to standardizing on the term "index" primarily because that is
the entity on the filesystem the end user is aware of (as opposed to
"cache" that still live throughout the code).
Some operations however needed to have two modes of operation, one being
working on both work tree files and the index and another being working
only on the index. Most of the time, the former was the default (and the
only mode implemented) and the latter mode needed an explicit option to
ask for. --cached is used when you ask them to ignore work tree
(i.e. "git apply --cached", "git diff --cached"). Unfortunately apply has
a third variant that works only on the work tree and because it is meant
as a replacement of GNU patch that works outside a git repository, that
mode is the default, and you need to ask with "git apply --index" to
affect both the index and the work tree.
If we were already well into "standardize on index, not telling the
end-users about cache" journey back then, and --cached should have been
called --index-only, but unfortunately the history was the other way
around.
Later, some outside people started "git training industry" without talking
with the git development community and started using a new term "to stage"
as a verb to describe "add to the index". Addition of "git diff --staged"
was supposed to lesson the confusion resulted from this mess, but as we
can see from your patch it had a reverse effect.
I do not think "to stage" as the name of the _concept_ is a bad thing
per-se. But the name of the concept and the command verb (and option
name) does not have to agree with each other.
cf. http://gitster.livejournal.com/19427.html
In retrospect, I think it might have been less problematic if we firmly
rejected "stage" as an option name, but instead renamed the --cached
option to --index-only and made the former a synonym to the latter to
really standardize on "index". I think it still is Ok to use the word "to
stage" to colloquially call the act of "adding to index", but if we did
not add that to the UI but kept it strictly at the concept level, it would
have made the UI less confusing, not more.
On Sun, Apr 5, 2009 at 10:59 PM, Junio C Hamano [off-list ref] wrote:
Junio C Hamano [off-list ref] writes:
quoted
Felipe Contreras [off-list ref] writes:
quoted
On Sun, Apr 5, 2009 at 10:02 PM, Junio C Hamano [off-list ref] wrote:
quoted
Felipe Contreras [off-list ref] writes:
quoted
This is the list of actions I've mapped:
* add: git stage = git stage add (git add)
* rm: (git rm --cached)
* diff: (git rm --cached)
* import: stage all files; modified, deleted, new
* ls: (git ls-files --stage)
I do not think these are good ideas at all, as it just spreads more
confusion, not less.
Do you agree that there's already a lot of confusion? (stage, cache,
index, etc.)
And do you agree that many git newbies don't use the stage? Actually
most of them don't even know what it is, and just do "git commit -a".
If so, how do you think these issues should be handled?
Perhaps not spreading "stage" even wider? That is the newest confusing
term that caused the most harm.
This probably needs clarification for new people who do not know the
history.
Thanks for the clarification.
<snip/>
Consider this:
== cache ==
This word is barely used in the English language, perhaps only used in
computing nowadays. The 'cache' is often referred to a place for
temporary storage, the purpose being rapid access. It is usually
transparent to the user.
Git uses the term in a completely different manner and the --cached
option is used in important command such as rm and diff. However,
people rarely use the term "git cache", probably because it
immediately evokes multiple caches for better performances.
== index ==
It is unclear to me what the word means in English language, but it is
generally used as a list of things, the purpose being for easy
retrieval.
Again, git is using the term in a different manner, however it is the
most widely used term to identify the concept "the git index",
probably due to the fact that the word "index" evokes a single entity.
But for some reason it's not used in any important commands as
'--index' or '--indexed'.
== stage ==
The word "stage" is used widely in the English language, and it
immediately evokes a theatrical stage. Generally, it means a different
(upper) level.
In git it is barely used, mostly on the "documentation industry"
probably because it's easier to understand for most people (even
non-native-English speakers).
Ideally the term should evoke the concept of a *single* area that has
no other purpose to differentiate from the contents of the working
directory. Also, the action to add and remove content from this area
should sound natural.
That rules out "cache" since "uncache" makes no sense. Something
similar happens with "unindex", although it doesn't sound completely
bad. On the other hand "stage" and "unstage" sound perfectly fine.
I do not think "to stage" as the name of the _concept_ is a bad thing
per-se. But the name of the concept and the command verb (and option
name) does not have to agree with each other.
cf. http://gitster.livejournal.com/19427.html
In retrospect, I think it might have been less problematic if we firmly
rejected "stage" as an option name, but instead renamed the --cached
option to --index-only and made the former a synonym to the latter to
really standardize on "index". I think it still is Ok to use the word "to
stage" to colloquially call the act of "adding to index", but if we did
not add that to the UI but kept it strictly at the concept level, it would
have made the UI less confusing, not more.
Why is it so natural to co-relate "stage" to "adding to the index"?
Would such a relation make sense outside of the git world? No. It is
natural to you because you already know what is the "git index"... it
is a *staging* area for commit preparation, logically it's natural to
co-relate this area with the action "to stage".
Please note it is not an _indexing_ area, nor a _caching_ area.
I agree that the internal (plumbing) term does not need to match the
conceptual term (used in documentation, tutorials, etc.), but the
higher level (porcelain) term *must* match in order for new comers to
grasp it quickly and avoid confusion.
I understand there are historic reasons for the names "cache" and
"index" and those should be thought before considering any change.
But also consider that I'm not proposing any big change... the term
"stage" is already being used, and there's already a "git stage"
command. I'm only proposing to add a few more options :)
I would be very pleased if you could at least try the patch for a few
days, and try "git stage diff" (or "git s diff" with an alias). I've
become very fond of "git s" "git s diff" and "git s -p -u".
Cheers.
--
Felipe Contreras
On Sun, Apr 5, 2009 at 4:41 PM, Felipe Contreras
[off-list ref] wrote:
== stage ==
The word "stage" is used widely in the English language, and it
immediately evokes a theatrical stage. Generally, it means a different
(upper) level.
In git it is barely used, mostly on the "documentation industry"
probably because it's easier to understand for most people (even
non-native-English speakers).
Would an index by any other name smell as sweet?
http://www.merriam-webster.com/dictionary/staging%20area
:-)
j.
On Sun, Apr 5, 2009 at 11:55 PM, Jay Soffian [off-list ref] wrote:
On Sun, Apr 5, 2009 at 4:41 PM, Felipe Contreras
[off-list ref] wrote:
quoted
== stage ==
The word "stage" is used widely in the English language, and it
immediately evokes a theatrical stage. Generally, it means a different
(upper) level.
In git it is barely used, mostly on the "documentation industry"
probably because it's easier to understand for most people (even
non-native-English speakers).
Would an index by any other name smell as sweet?
Yeap, almost. Do you have in mind any other word that would fit?
--
Felipe Contreras