{"thread":{"id":"4048","subject":"[PATCH 1/3] Alphabetize the glossary.","startedAt":"2006-05-04T04:15:46Z","lastAt":"2006-05-05T19:02:15Z","messageCount":5,"participants":["Jon Loeliger","Junio C Hamano","Johannes Schindelin"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"19494","messageId":"E1FbVFi-0004Tt-Aw@jdl.com","threadId":"4048","inReplyTo":null,"subject":"[PATCH 1/3] Alphabetize the glossary.","fromName":"Jon Loeliger","fromEmail":"jdl@jdl.com","sentAt":"2006-05-04T04:15:46Z","receivedAt":"2006-05-04T04:15:46Z","isPatch":true,"sender":{"key":"jdl@jdl.com","avatar":"https://gravatar.com/avatar/75ce9a10b151acd2c28ec4ab2136dba7b2ff1634530bd04b155981a749d08a64?d=mp&s=160"},"body":"\nSigned-off-by: Jon Loeliger <jdl@jdl.com>\n\n---\n\nYeah, there is a script that also alphabetize the glossary.\nBut let's just be explicit and complete here.\n\n\n Documentation/glossary.txt |  339 ++++++++++++++++++++++----------------------\n 1 files changed, 170 insertions(+), 169 deletions(-)\n\n374314abaefe3509c6016eb811b09e115ec4f2a8\ndiff --git a/Documentation/glossary.txt b/Documentation/glossary.txt\nindex 02a9d9c..075c078 100644\n--- a/Documentation/glossary.txt\n+++ b/Documentation/glossary.txt\n@@ -1,79 +1,37 @@\n-object::\n-\tThe unit of storage in git. It is uniquely identified by\n-\tthe SHA1 of its contents. Consequently, an object can not\n-\tbe changed.\n-\n-object name::\n-\tThe unique identifier of an object. The hash of the object's contents\n-\tusing the Secure Hash Algorithm 1 and usually represented by the 40\n-\tcharacter hexadecimal encoding of the hash of the object (possibly\n-\tfollowed by a white space).\n-\n-SHA1::\n-\tSynonym for object name.\n-\n-object identifier::\n-\tSynonym for object name.\n-\n-hash::\n-\tIn git's context, synonym to object name.\n-\n-object database::\n-\tStores a set of \"objects\", and an individual object is identified\n-\tby its object name. The objects usually live in `$GIT_DIR/objects/`.\n+alternate object database::\n+\tVia the alternates mechanism, a repository can inherit part of its\n+\tobject database from another object database, which is called\n+\t\"alternate\".\n \n blob object::\n \tUntyped object, e.g. the contents of a file.\n \n-tree object::\n-\tAn object containing a list of file names and modes along with refs\n-\tto the associated blob and/or tree objects. A tree is equivalent\n-\tto a directory.\n-\n-tree::\n-\tEither a working tree, or a tree object together with the\n-\tdependent blob and tree objects (i.e. a stored representation\n-\tof a working tree).\n-\n-DAG::\n-\tDirected acyclic graph. The commit objects form a directed acyclic\n-\tgraph, because they have parents (directed), and the graph of commit\n-\tobjects is acyclic (there is no chain which begins and ends with the\n-\tsame object).\n-\n-index::\n-\tA collection of files with stat information, whose contents are\n-\tstored as objects. The index is a stored version of your working\n-\ttree. Truth be told, it can also contain a second, and even a third\n-\tversion of a working tree, which are used when merging.\n-\n-index entry::\n-\tThe information regarding a particular file, stored in the index.\n-\tAn index entry can be unmerged, if a merge was started, but not\n-\tyet finished (i.e. if the index contains multiple versions of\n-\tthat file).\n-\n-unmerged index:\n-\tAn index which contains unmerged index entries.\n+branch::\n+\tA non-cyclical graph of revisions, i.e. the complete history of\n+\ta particular revision, which is called the branch head. The\n+\tbranch heads are stored in `$GIT_DIR/refs/heads/`.\n \n cache::\n \tObsolete for: index.\n \n-working tree::\n-\tThe set of files and directories currently being worked on,\n-\ti.e. you can work in your working tree without using git at all.\n-\n-directory::\n-\tThe list you get with \"ls\" :-)\n+chain::\n+\tA list of objects, where each object in the list contains a\n+\treference to its successor (for example, the successor of a commit\n+\tcould be one of its parents).\n \n-revision::\n-\tA particular state of files and directories which was stored in\n-\tthe object database. It is referenced by a commit object.\n+changeset::\n+\tBitKeeper/cvsps speak for \"commit\". Since git does not store\n+\tchanges, but states, it really does not make sense to use\n+\tthe term \"changesets\" with git.\n \n checkout::\n \tThe action of updating the working tree to a revision which was\n \tstored in the object database.\n \n+clean::\n+\tA working tree is clean, if it corresponds to the revision\n+\treferenced by the current head.  Also see \"dirty\".\n+\n commit::\n \tAs a verb: The action of storing the current state of the index in the\n \tobject database. The result is a revision.\n@@ -85,73 +43,72 @@ commit object::\n \ttree object which corresponds to the top directory of the\n \tstored revision.\n \n-parent::\n-\tA commit object contains a (possibly empty) list of the logical\n-\tpredecessor(s) in the line of development, i.e. its parents.\n+core git::\n+\tFundamental data structures and utilities of git. Exposes only\n+\tlimited source code management tools.\n \n-changeset::\n-\tBitKeeper/cvsps speak for \"commit\". Since git does not store\n-\tchanges, but states, it really does not make sense to use\n-\tthe term \"changesets\" with git.\n+DAG::\n+\tDirected acyclic graph. The commit objects form a directed acyclic\n+\tgraph, because they have parents (directed), and the graph of commit\n+\tobjects is acyclic (there is no chain which begins and ends with the\n+\tsame object).\n \n-clean::\n-\tA working tree is clean, if it corresponds to the revision\n-\treferenced by the current head.\n+dircache::\n+\tYou are *waaaaay* behind.\n \n dirty::\n \tA working tree is said to be dirty if it contains modifications\n \twhich have not been committed to the current branch.\n \n-head::\n-\tThe top of a branch. It contains a ref to the corresponding\n-\tcommit object.\n+directory::\n+\tThe list you get with \"ls\" :-)\n \n-branch::\n-\tA non-cyclical graph of revisions, i.e. the complete history of\n-\ta particular revision, which is called the branch head. The\n-\tbranch heads are stored in `$GIT_DIR/refs/heads/`.\n+ent::\n+\tFavorite synonym to \"tree-ish\" by some total geeks. See\n+\t`http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth\n+\texplanation.\n \n-master::\n-\tThe default branch. Whenever you create a git repository, a branch\n-\tnamed \"master\" is created, and becomes the active branch. In most\n-\tcases, this contains the local development.\n+fetch::\n+\tFetching a branch means to get the branch's head ref from a\n+\tremote repository, to find out which objects are missing from\n+\tthe local object database, and to get them, too.\n \n-origin::\n-\tThe default upstream branch. Most projects have one upstream\n-\tproject which they track, and by default 'origin' is used for\n-\tthat purpose.  New updates from upstream will be fetched into\n-\tthis branch; you should never commit to it yourself.\n+file system::\n+\tLinus Torvalds originally designed git to be a user space file\n+\tsystem, i.e. the infrastructure to hold files and directories.\n+\tThat ensured the efficiency and speed of git.\n \n-ref::\n-\tA 40-byte hex representation of a SHA1 pointing to a particular\n-\tobject. These may be stored in `$GIT_DIR/refs/`.\n+git archive::\n+\tSynonym for repository (for arch people).\n+\n+hash::\n+\tIn git's context, synonym to object name.\n+\n+head::\n+\tThe top of a branch. It contains a ref to the corresponding\n+\tcommit object.\n \n head ref::\n \tA ref pointing to a head. Often, this is abbreviated to \"head\".\n \tHead refs are stored in `$GIT_DIR/refs/heads/`.\n \n-tree-ish::\n-\tA ref pointing to either a commit object, a tree object, or a\n-\ttag object pointing to a tag or commit or tree object.\n+index::\n+\tA collection of files with stat information, whose contents are\n+\tstored as objects. The index is a stored version of your working\n+\ttree. Truth be told, it can also contain a second, and even a third\n+\tversion of a working tree, which are used when merging.\n \n-ent::\n-\tFavorite synonym to \"tree-ish\" by some total geeks. See\n-\t`http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth\n-\texplanation.\n+index entry::\n+\tThe information regarding a particular file, stored in the index.\n+\tAn index entry can be unmerged, if a merge was started, but not\n+\tyet finished (i.e. if the index contains multiple versions of\n+\tthat file).\n \n-tag object::\n-\tAn object containing a ref pointing to another object, which can\n-\tcontain a message just like a commit object. It can also\n-\tcontain a (PGP) signature, in which case it is called a \"signed\n-\ttag object\".\n+master::\n+\tThe default branch. Whenever you create a git repository, a branch\n+\tnamed \"master\" is created, and becomes the active branch. In most\n+\tcases, this contains the local development.\n \n-tag::\n-\tA ref pointing to a tag or commit object. In contrast to a head,\n-\ta tag is not changed by a commit. Tags (not tag objects) are\n-\tstored in `$GIT_DIR/refs/tags/`. A git tag has nothing to do with\n-\ta Lisp tag (which is called object type in git's context).\n-\tA tag is most typically used to mark a particular point in the\n-\tcommit ancestry chain.\n \n merge::\n \tTo merge branches means to try to accumulate the changes since a\n@@ -159,55 +116,57 @@ merge::\n \tmerge uses heuristics to accomplish that. Evidently, an automatic\n \tmerge can fail.\n \n-octopus::\n-\tTo merge more than two branches. Also denotes an intelligent\n-\tpredator.\n+object::\n+\tThe unit of storage in git. It is uniquely identified by\n+\tthe SHA1 of its contents. Consequently, an object can not\n+\tbe changed.\n \n-resolve::\n-\tThe action of fixing up manually what a failed automatic merge\n-\tleft behind.\n+object database::\n+\tStores a set of \"objects\", and an individual object is identified\n+\tby its object name. The objects usually live in `$GIT_DIR/objects/`.\n \n-rewind::\n-\tTo throw away part of the development, i.e. to assign the head to\n-\tan earlier revision.\n+object identifier::\n+\tSynonym for object name.\n \n-rebase::\n-\tTo clean a branch by starting from the head of the main line of\n-\tdevelopment (\"master\"), and reapply the (possibly cherry-picked)\n-\tchanges from that branch.\n+object name::\n+\tThe unique identifier of an object. The hash of the object's contents\n+\tusing the Secure Hash Algorithm 1 and usually represented by the 40\n+\tcharacter hexadecimal encoding of the hash of the object (possibly\n+\tfollowed by a white space).\n \n-repository::\n-\tA collection of refs together with an object database containing\n-\tall objects, which are reachable from the refs, possibly accompanied\n-\tby meta data from one or more porcelains. A repository can\n-\tshare an object database with other repositories.\n+object type:\n+\tOne of the identifiers \"commit\",\"tree\",\"tag\" and \"blob\" describing\n+\tthe type of an object.\n \n-git archive::\n-\tSynonym for repository (for arch people).\n+octopus::\n+\tTo merge more than two branches. Also denotes an intelligent\n+\tpredator.\n \n-file system::\n-\tLinus Torvalds originally designed git to be a user space file\n-\tsystem, i.e. the infrastructure to hold files and directories.\n-\tThat ensured the efficiency and speed of git.\n+origin::\n+\tThe default upstream branch. Most projects have one upstream\n+\tproject which they track, and by default 'origin' is used for\n+\tthat purpose.  New updates from upstream will be fetched into\n+\tthis branch; you should never commit to it yourself.\n \n-alternate object database::\n-\tVia the alternates mechanism, a repository can inherit part of its\n-\tobject database from another object database, which is called\n-\t\"alternate\".\n+pack::\n+\tA set of objects which have been compressed into one file (to save\n+\tspace or to transmit them efficiently).\n \n-reachable::\n-\tAn object is reachable from a ref/commit/tree/tag, if there is a\n-\tchain leading from the latter to the former.\n+pack index::\n+\tThe list of identifiers, and other information, of the objects in a\n+\tpack, to assist in efficiently accessing the contents of a pack. \n \n-chain::\n-\tA list of objects, where each object in the list contains a\n-\treference to its successor (for example, the successor of a commit\n-\tcould be one of its parents).\n+parent::\n+\tA commit object contains a (possibly empty) list of the logical\n+\tpredecessor(s) in the line of development, i.e. its parents.\n \n-fetch::\n-\tFetching a branch means to get the branch's head ref from a\n-\tremote repository, to find out which objects are missing from\n-\tthe local object database, and to get them, too.\n+plumbing::\n+\tCute name for core git.\n+\n+porcelain::\n+\tCute name for programs and program suites depending on core git,\n+\tpresenting a high level access to core git. Porcelains expose\n+\tmore of a SCM interface than the plumbing.\n \n pull::\n \tPulling a branch means to fetch it and merge it.\n@@ -221,33 +180,75 @@ push::\n \tthe remote head ref. If the remote head is not an ancestor to the\n \tlocal head, the push fails.\n \n-pack::\n-\tA set of objects which have been compressed into one file (to save\n-\tspace or to transmit them efficiently).\n+reachable::\n+\tAn object is reachable from a ref/commit/tree/tag, if there is a\n+\tchain leading from the latter to the former.\n \n-pack index::\n-\tThe list of identifiers, and other information, of the objects in a\n-\tpack, to assist in efficiently accessing the contents of a pack. \n+rebase::\n+\tTo clean a branch by starting from the head of the main line of\n+\tdevelopment (\"master\"), and reapply the (possibly cherry-picked)\n+\tchanges from that branch.\n \n-core git::\n-\tFundamental data structures and utilities of git. Exposes only\n-\tlimited source code management tools.\n+ref::\n+\tA 40-byte hex representation of a SHA1 pointing to a particular\n+\tobject. These may be stored in `$GIT_DIR/refs/`.\n \n-plumbing::\n-\tCute name for core git.\n+repository::\n+\tA collection of refs together with an object database containing\n+\tall objects, which are reachable from the refs, possibly accompanied\n+\tby meta data from one or more porcelains. A repository can\n+\tshare an object database with other repositories.\n \n-porcelain::\n-\tCute name for programs and program suites depending on core git,\n-\tpresenting a high level access to core git. Porcelains expose\n-\tmore of a SCM interface than the plumbing.\n+resolve::\n+\tThe action of fixing up manually what a failed automatic merge\n+\tleft behind.\n \n-object type:\n-\tOne of the identifiers \"commit\",\"tree\",\"tag\" and \"blob\" describing\n-\tthe type of an object.\n+revision::\n+\tA particular state of files and directories which was stored in\n+\tthe object database. It is referenced by a commit object.\n+\n+rewind::\n+\tTo throw away part of the development, i.e. to assign the head to\n+\tan earlier revision.\n \n SCM::\n \tSource code management (tool).\n \n-dircache::\n-\tYou are *waaaaay* behind.\n+SHA1::\n+\tSynonym for object name.\n+\n+tree object::\n+\tAn object containing a list of file names and modes along with refs\n+\tto the associated blob and/or tree objects. A tree is equivalent\n+\tto a directory.\n+\n+tree::\n+\tEither a working tree, or a tree object together with the\n+\tdependent blob and tree objects (i.e. a stored representation\n+\tof a working tree).\n+\n+tree-ish::\n+\tA ref pointing to either a commit object, a tree object, or a\n+\ttag object pointing to a tag or commit or tree object.\n+\n+tag object::\n+\tAn object containing a ref pointing to another object, which can\n+\tcontain a message just like a commit object. It can also\n+\tcontain a (PGP) signature, in which case it is called a \"signed\n+\ttag object\".\n+\n+tag::\n+\tA ref pointing to a tag or commit object. In contrast to a head,\n+\ta tag is not changed by a commit. Tags (not tag objects) are\n+\tstored in `$GIT_DIR/refs/tags/`. A git tag has nothing to do with\n+\ta Lisp tag (which is called object type in git's context).\n+\tA tag is most typically used to mark a particular point in the\n+\tcommit ancestry chain.\n+\n+unmerged index:\n+\tAn index which contains unmerged index entries.\n+\n+working tree::\n+\tThe set of files and directories currently being worked on,\n+\ti.e. you can work in your working tree without using git at all.\n \n-- \n1.3.1.g3d990\n"},{"id":"19499","messageId":"7v1wva9wbe.fsf@assigned-by-dhcp.cox.net","threadId":"4048","inReplyTo":"E1FbVFi-0004Tt-Aw@jdl.com","subject":"Re: [PATCH 1/3] Alphabetize the glossary.","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-05-04T05:46:13Z","receivedAt":"2006-05-04T05:46:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jon Loeliger <jdl@jdl.com> writes:\n\n> Signed-off-by: Jon Loeliger <jdl@jdl.com>\n>\n> ---\n>\n> Yeah, there is a script that also alphabetize the glossary.\n> But let's just be explicit and complete here.\n\nYou alphabetized, _and_ added reference to \"dirty\" from clean,\nwithout adding a corresponding reference to \"clean\" from dirty,\nwhich is probably OK.\n"},{"id":"19511","messageId":"Pine.LNX.4.63.0605041238240.26488@wbgn013.biozentrum.uni-wuerzburg.de","threadId":"4048","inReplyTo":"E1FbVFi-0004Tt-Aw@jdl.com","subject":"Re: [PATCH 1/3] Alphabetize the glossary.","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2006-05-04T10:41:19Z","receivedAt":"2006-05-04T10:41:19Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Wed, 3 May 2006, Jon Loeliger wrote:\n\n> Yeah, there is a script that also alphabetize the glossary.\n> But let's just be explicit and complete here.\n\nThe idea of having it not alphabetized, but doing it by a script, was to \nlet people actually _read_ it. There is nothing more annoying than having \nto jump forward and backward and eventually be lost.\n\nglossary, as I started it, was topologically ordered: no Git term was used \nbefore it was described (at least that was the plan).\n\nCiao,\nDscho\n"},{"id":"19515","messageId":"E1Fbe1L-0006Vf-P0@jdl.com","threadId":"4048","inReplyTo":"7v1wva9wbe.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH 1/3] Alphabetize the glossary.","fromName":"Jon Loeliger","fromEmail":"jdl@jdl.com","sentAt":"2006-05-04T13:37:31Z","receivedAt":"2006-05-04T13:37:31Z","isPatch":true,"sender":{"key":"jdl@jdl.com","avatar":"https://gravatar.com/avatar/75ce9a10b151acd2c28ec4ab2136dba7b2ff1634530bd04b155981a749d08a64?d=mp&s=160"},"body":"So, like, the other day Junio C Hamano mumbled:\n> \n> You alphabetized, _and_ added reference to \"dirty\" from clean,\n> without adding a corresponding reference to \"clean\" from dirty,\n> which is probably OK.\n\nRats.  Would you like a symmetrical patch?\n\njdl\n"},{"id":"19575","messageId":"7vu084xpl4.fsf@assigned-by-dhcp.cox.net","threadId":"4048","inReplyTo":"Pine.LNX.4.63.0605041238240.26488@wbgn013.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH 1/3] Alphabetize the glossary.","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-05-05T19:02:15Z","receivedAt":"2006-05-05T19:02:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n> The idea of having it not alphabetized, but doing it by a script, was to \n> let people actually _read_ it. There is nothing more annoying than having \n> to jump forward and backward and eventually be lost.\n>\n> glossary, as I started it, was topologically ordered: no Git term was used \n> before it was described (at least that was the plan).\n\nI myself rarely read either man nor html formatted ones.  When I\nneed to find something, I go straight to Documentation/\ndirectory looking for *.txt files.  Being able to find things\nfrom an alphabetized list is very handy.\n\nOn the other hand, we would want to make it easy for people to\nread it in the logical order.  For that purpose, html formatted\nversion, thanks to the cross references the script creates, is a\nlot easier than the plain text version.\n\nMaybe we should do both.  We _could_ teach the sort script to\nalso do an topological sort, and have two sections in the\nresulting formatted documentation, the top part being\n\"alphabetical\", and the second part being \"bedtime reading\".\n\nA random sort that is merely topologically correct probably is\nnot what we want, so it might make sense to have a hint that\ninstructs \"these should come first before those although they\nare topologically independent\" to the sort script.  Of course\nthat \"hint\" could be the order entries appear in the source text\n(which was what you had originally), but when somebody wants to\nadd a new entry to the glossary, it makes unambiguous where the\nnew entry should go if the source text is already sorted, which\nI am hoping would make it somewhat easier to maintain.\n"}]}