Re: Aw: Re: [PATCH 1/3] Remove outdated/missleading/irrelevant entries from glossary-content.txt
Thomas Ackermann writes: >> Even though I personally am slightly in favor of removal, I suspect >> that is primarily because I already know what Git tag is, and it is >> different from the type tag in the Lisp-speak. >> > I assumed the cardinality of the set of Lisp users is so small that > this addition will confuse more people than help somebody. > >> The text indeed has a room for improvement, but it probably makes >> sense to have an entry for `directory` here, as folks who are used >> to say "Folders" may not know what it is. >> > I assumed the number of such people so low that it's not worth > to keep this - to most people obvious - explanation. For the above two (they are of the same theme) to help one audience, I tend to be cautious and try not to say "I don't fall into the target audience, and to me it is misleading/irrelevant, so let's remove it". >> Which one of outdated, misleading or irrelevant category does this >> fall into? It certainly is not outdated (diff --cc/-c is often a >> way to view evil merges), the text defines what an evil merge is >> precisely and I do not think it is misleading. Is it irrelevant? >> > I considered it "irrelevant" because it tries to define > "evil merge" which is - at least to my experience - not used > as some kind of well known notion. But I might of course be wrong. In a merge-heavy workflow, evil merges have to happen from time to time, and it is a good concept to know about. I however think the description is too literal and it does not lead to the understanding of what it is used for. I see a few questions on the stackoverflow with unsatisfactory literal answers, too. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Aw: Re: [PATCH 1/3] Remove outdated/missleading/irrelevant entries from glossary-content.txt
> > The text indeed has a room for improvement, but it probably makes > sense to have an entry for `directory` here, as folks who are used > to say "Folders" may not know what it is. > I assumed the number of such people so low that it's not worth to keep this - to most people obvious - explanation. > > Which one of outdated, misleading or irrelevant category does this > fall into? It certainly is not outdated (diff --cc/-c is often a > way to view evil merges), the text defines what an evil merge is > precisely and I do not think it is misleading. Is it irrelevant? > I considered it "irrelevant" because it tries to define "evil merge" which is - at least to my experience - not used as some kind of well known notion. But I might of course be wrong. > > Even though I personally am slightly in favor of removal, I suspect > that is primarily because I already know what Git tag is, and it is > different from the type tag in the Lisp-speak. > I assumed the cardinality of the set of Lisp users is so small that this addition will confuse more people than help somebody. --- Thomas -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/3] Remove outdated/missleading/irrelevant entries from glossary-content.txt
Thomas Ackermann writes: > -[[def_directory]]directory:: > - The list you get with "ls" :-) > - The text indeed has a room for improvement, but it probably makes sense to have an entry for `directory` here, as folks who are used to say "Folders" may not know what it is. > -[[def_evil_merge]]evil merge:: > - An evil merge is a <> that introduces changes that > - do not appear in any <>. Which one of outdated, misleading or irrelevant category does this fall into? It certainly is not outdated (diff --cc/-c is often a way to view evil merges), the text defines what an evil merge is precisely and I do not think it is misleading. Is it irrelevant? > @@ -468,9 +452,7 @@ should not be combined with other pathspec. > object of an arbitrary type (typically a tag points to either a > <> or a <>). > In contrast to a <>, a tag is not updated by > - the `commit` command. A Git tag has nothing to do with a Lisp > - tag (which would be called an <> > - in Git's context). A tag is most typically used to mark a particular > + the `commit` command. A tag is most typically used to mark a particular > point in the commit ancestry <>. Even though I personally am slightly in favor of removal, I suspect that is primarily because I already know what Git tag is, and it is different from the type tag in the Lisp-speak. It's similar in spirit why I would prefer to keep `directory` to help people who speak of "Folders". Other changes in this patch look OK to me. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 1/3] Remove outdated/missleading/irrelevant entries from glossary-content.txt
Signed-off-by: Thomas Ackermann --- Documentation/glossary-content.txt | 28 +--- 1 file changed, 5 insertions(+), 23 deletions(-) diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index eb7ba84..ab02238 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -5,7 +5,7 @@ [[def_bare_repository]]bare repository:: A bare repository is normally an appropriately - named <> with a `.git` suffix that does not + named directory with a `.git` suffix that does not have a locally checked-out copy of any of the files under revision control. That is, all of the Git administrative and control files that would normally be present in the @@ -79,7 +79,7 @@ to point at the new commit. An <> which contains the information about a particular <>, such as <>, committer, author, date and the <> which corresponds - to the top <> of the stored + to the top directory of the stored revision. [[def_core_git]]core Git:: @@ -104,26 +104,11 @@ to point at the new commit. an arbitrary <> that isn't necessarily the tip of any particular branch. In this case HEAD is said to be "detached". -[[def_dircache]]dircache:: - You are *way* behind. See <>. - -[[def_directory]]directory:: - The list you get with "ls" :-) - [[def_dirty]]dirty:: A <> is said to be "dirty" if it contains modifications which have not been <> to the current <>. -[[def_ent]]ent:: - Favorite synonym to "<>" by some total geeks. See - http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth - explanation. Avoid this term, not to confuse people. - -[[def_evil_merge]]evil merge:: - An evil merge is a <> that introduces changes that - do not appear in any <>. - [[def_fast_forward]]fast-forward:: A fast-forward is a special type of <> where you have a <> and you are "merging" another @@ -257,8 +242,7 @@ This commit is referred to as a "merge commit", or sometimes just a <>. [[def_octopus]]octopus:: - To <> more than two <>. Also denotes an - intelligent predator. + To <> more than two <>. [[def_origin]]origin:: The default upstream <>. Most projects have @@ -468,9 +452,7 @@ should not be combined with other pathspec. object of an arbitrary type (typically a tag points to either a <> or a <>). In contrast to a <>, a tag is not updated by - the `commit` command. A Git tag has nothing to do with a Lisp - tag (which would be called an <> - in Git's context). A tag is most typically used to mark a particular + the `commit` command. A tag is most typically used to mark a particular point in the commit ancestry <>. [[def_tag_object]]tag object:: @@ -494,7 +476,7 @@ should not be combined with other pathspec. [[def_tree_object]]tree object:: An <> containing a list of file names and modes along with refs to the associated blob and/or tree objects. A - <> is equivalent to a <>. + <> is equivalent to a directory. [[def_tree-ish]]tree-ish:: A <> pointing to either a
