{"thread":{"id":"1377","subject":"Terminology","startedAt":"2005-07-31T13:52:25Z","lastAt":"2005-08-05T23:08:48Z","messageCount":8,"participants":["Johannes Schindelin","Junio C Hamano","Linus Torvalds","barkalow@iabervon.org"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"6667","messageId":"Pine.LNX.4.58.0507311541340.29235@wgmdd8.biozentrum.uni-wuerzburg.de","threadId":"1377","inReplyTo":null,"subject":"Terminology","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2005-07-31T13:52:25Z","receivedAt":"2005-07-31T13:52:25Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nthe other day I got confused by the terminology. Maybe I'm not the only\none:\n\nThe GIT equivalent of a CVS branch is sometimes called a branch\n(git-new-branch), sometimes a tree (git-switch-tree), and sometimes a\nhead (which seems counterintuitive to CVS people: they only have one\nHEAD; pun(s) intended).\n\nWhat is worse: a tree often refers to something different, namely a\ndirectory structure corresponding to a certain commit (which SVN people\nwould call revision). And in $GIT_DIR/branches, short cuts for remote\naddresses are stored (and therefore I would have preferred\n$GIT_DIR/remotes).\n\nMaybe we should decide on a common terminology before kicking out 1.0, and\nlook through all files in Documentation/ to have a consistent vocabulary.\nAnd poor me does not get confused no more.\n\nCiao,\nDscho\n\n--\nGit-R-Done\n"},{"id":"6668","messageId":"7vhdeaj05n.fsf@assigned-by-dhcp.cox.net","threadId":"1377","inReplyTo":"Pine.LNX.4.58.0507311541340.29235@wgmdd8.biozentrum.uni-wuerzburg.de","subject":"Re: Terminology","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-07-31T18:33:24Z","receivedAt":"2005-07-31T18:33:24Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n> Maybe we should decide on a common terminology before kicking out 1.0, and\n> look through all files in Documentation/ to have a consistent vocabulary.\n> And poor me does not get confused no more.\n\nGlad to see you started the discussion on this one.  I have a\nslight worry and suspicion that this might open a can of worms,\nbut I agree we need to get this done.  We probably would end up\nspliting the Terminology section in Documentation/git.txt into a\nseparate \"Glossary\" document.\n\nCare to volunteer drafting a strawman, listing the concepts we\nneed terms for, marking the ones we seem to use the same word\nfor?   You do not have to suggest which candidate term to use\nfor all of them.  Something along these lines...\n\n - The unit of storage in GIT is called \"object\"; no other word\n   is used and the word \"object\" is used only for this purpose\n   so this one is OK.\n  \n - A 20-byte SHA1 to uniquely identify \"objects\"; README and\n   early Linus messages call this \"object name\" so does\n   tutorial.  Many places say \"object SHA1\" or just \"SHA1\".\n\n - An \"object database\" stores a set of \"objects\", and an\n   individial object can be retrieved by giving it its object\n   name.\n\n - Storing a regular file or a symlink in the object database\n   results in a \"blob object\" created.  You cannot directly\n   store filesystem directory, but a collection of blob objects\n   and other tree objects can be recorded as a \"tree object\"\n   which corresponds to this notion.\n\n - $GIT_INDEX_FILE is \"index file\", which is a collection of\n   \"cache entries\".  The former is sometimes called \"cache\n   file\", the latter just \"cache\".\n\n - the directory which corresponds to the top of the hierarchy\n   described in the index file; I've seen words like \"working\n   tree\", \"working directory\", \"work tree\" used.\n\n - When the stat information a cache entry records matches what\n   is in the work tree, the entry is called \"clean\" or\n   \"up-to-date\".  The opposite is \"dirty\" or \"not up-to-date\".\n\n - An index file can be in \"merged\" or \"unmerged\" state.  The\n   former is when it does not have anything but stage 0 entries,\n   the latter otherwise.\n\n - An merged index file can be written as a \"tree object\", which\n   is technically a set of interconnected tree objects but we\n   equate it with the toplevel tree object with this set.\n\n - A \"tree object\" can be recorded as a part of a \"commit\n   object\".  The tree object is said to be \"associated with\" the\n   commit object.\n\n - A \"tag object\" can be recorded as a pointer to another object\n   of any type. The act of following the pointer a tag object\n   holds (this can go recursively) until we get to a non-tag\n   object is sometimes called \"resolving the tag\".\n\n - The following objects are collectively called \"tree-ish\": a\n   tree object, a commit object, a tag object that resolves to\n   either a commit or a tree object, and can be given to\n   commands that expect to work on a tree object.\n\n - The files under $GIT_DIR/refs record object names, and are\n   called \"refs\".  What is under refs/heads/ are called \"heads\",\n   refs/tags/ \"tags\".  Typically, they are either object names\n   of commit objects or tag objects that resolve to commit\n   objects, but a tag can point at any object.\n\n - A \"head\" is always an object name of a commit, and marks the\n   latest commit in one line of development.  A line of\n   development is often called a \"branch\".  We sometimes use the\n   word \"branch head\" to stress the fact that we are talking\n   about a single commit that is the latest one in a \"branch\".\n\n - Combining the states from more than one lines of developments\n   is called \"merging\" and typically done between two branch\n   heads.  This is called \"resolving\" in the tutorial and there\n   is git-resolve-script command for it.\n\n - A set of \"refs\" with the set of objects reachable from them\n   constitute a \"repository\".  Although currently there is no\n   provision for a repository to say that its objects are stored\n   in this and that object database, multiple repositories can\n   share the same object database, and there is not a conceptual\n   limit that a repository must retrive its objects from a\n   single object database.\n\n - The act of finding out the object names recorded in \"refs\" a\n   different repository records, optionally updating a local\n   \"refs\" with their values, and retrieving the objects\n   reachable from them is called \"fetching\".  Fetching immediately\n   followed by merging is called \"pulling\".\n\n - The act of updating \"refs\" in a different repository with new\n   value and populating the object database(s) associated with\n   the repository is called \"pushing\".\n\n - Currently refs/heads records branch heads of both locally\n   created branches and branches fetched from other\n   repositories.\n\n - Currently, fetching always happen against a single branch\n   head on a remote repository, and (a remote repository, name\n   of the branch) is stored in $GIT_DIR/branches/ as a\n   short-hand mechanism.  A file in this directory identifies\n   a remote repository by its URL, and the branch to fetch/pull\n   from is identified with the URL fragment notation, absense of\n   which makes it default to \"master\".\n\n-jc\n"},{"id":"6679","messageId":"Pine.LNX.4.58.0508010038250.32179@wgmdd8.biozentrum.uni-wuerzburg.de","threadId":"1377","inReplyTo":"7vhdeaj05n.fsf@assigned-by-dhcp.cox.net","subject":"Re: Terminology","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2005-07-31T22:38:54Z","receivedAt":"2005-07-31T22:38:54Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nI tried to avoid the work. But I'll do it.\n\nCiao,\nDscho\n"},{"id":"6851","messageId":"Pine.LNX.4.63.0508051655480.8418@wgmdd8.biozentrum.uni-wuerzburg.de","threadId":"1377","inReplyTo":"7vhdeaj05n.fsf@assigned-by-dhcp.cox.net","subject":"Re: Terminology","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2005-08-05T14:57:33Z","receivedAt":"2005-08-05T14:57:33Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nI am finally finished with my preliminary survey: I took what you sent as \na strawman, and inserted what I found (I tried to say only something about \nambiguous naming):\n\n  - The unit of storage in GIT is called \"object\"; no other word\n    is used and the word \"object\" is used only for this purpose\n    so this one is OK.\n\n  - A 20-byte SHA1 to uniquely identify \"objects\"; README and\n    early Linus messages call this \"object name\" so does\n    tutorial.  Many places say \"object SHA1\" or just \"SHA1\".\n\n\"Object\" is short for \"immutable object\". git-cat-file.txt says\n\"repository object\".\n\n  - An \"object database\" stores a set of \"objects\", and an\n    individial object can be retrieved by giving it its object\n    name.\n\nTutorial calls it an \"object store\". git-fsck-cache.txt names it\n\"database\" at first, but then also uses \"object pool\".\n\n  - Storing a regular file or a symlink in the object database\n    results in a \"blob object\" created.  You cannot directly\n    store filesystem directory, but a collection of blob objects\n    and other tree objects can be recorded as a \"tree object\"\n    which corresponds to this notion.\n\n  - $GIT_INDEX_FILE is \"index file\", which is a collection of\n    \"cache entries\".  The former is sometimes called \"cache\n    file\", the latter just \"cache\".\n\nTutorial says \"cache\" aka \"index\". Though technically, a cache\nis the index file _plus_ the related objects in the object database.\ngit-update-cache.txt even makes the difference between the \"index\"\nand the \"directory cache\".\n\n  - the directory which corresponds to the top of the hierarchy\n    described in the index file; I've seen words like \"working\n    tree\", \"working directory\", \"work tree\" used.\n\nThe tutorial initially says \"working tree\", but then \"working\ndirectory\". Usually, a directory does not include its\nsubdirectories, though. git-apply-patch-script.txt, git-apply.txt,\ngit-hash-object.txt, git-read-tree.txt\nuse \"work tree\". git-checkout-cache.txt, git-commit-tree.txt,\ngit-diff-cache.txt, git-ls-tree.txt, git-update-cache.txt contain\n\"working directory\". git-diff-files.txt talks about a \"working tree\".\n\n  - When the stat information a cache entry records matches what\n    is in the work tree, the entry is called \"clean\" or\n    \"up-to-date\".  The opposite is \"dirty\" or \"not up-to-date\".\n\n  - An index file can be in \"merged\" or \"unmerged\" state.  The\n    former is when it does not have anything but stage 0 entries,\n    the latter otherwise.\n\nThat seems to be unambiguous (sometimes it's called \"index\",\nsometimes \"index file\"; I don't think that matters).\n\n  - An merged index file can be written as a \"tree object\", which\n    is technically a set of interconnected tree objects but we\n    equate it with the toplevel tree object with this set.\n\n  - A \"tree object\" can be recorded as a part of a \"commit\n    object\".  The tree object is said to be \"associated with\" the\n    commit object.\n\nIn diffcore.txt, \"changeset\" is used in place of \"commit\".\n\n  - A \"tag object\" can be recorded as a pointer to another object\n    of any type. The act of following the pointer a tag object\n    holds (this can go recursively) until we get to a non-tag\n    object is sometimes called \"resolving the tag\".\n\n  - The following objects are collectively called \"tree-ish\": a\n    tree object, a commit object, a tag object that resolves to\n    either a commit or a tree object, and can be given to\n    commands that expect to work on a tree object.\n\nWe could call this category an \"ent\".\n\n  - The files under $GIT_DIR/refs record object names, and are\n    called \"refs\".  What is under refs/heads/ are called \"heads\",\n    refs/tags/ \"tags\".  Typically, they are either object names\n    of commit objects or tag objects that resolve to commit\n    objects, but a tag can point at any object.\n\nThe tutorial never calls them \"refs\", but instead \"references\".\n\n  - A \"head\" is always an object name of a commit, and marks the\n    latest commit in one line of development.  A line of\n    development is often called a \"branch\".  We sometimes use the\n    word \"branch head\" to stress the fact that we are talking\n    about a single commit that is the latest one in a \"branch\".\n\nIn the tutorial, the latter is used in reverse: it talks about a\n\"HEAD development branch\" and a \"HEAD branch\".\n\nI find it a little bit troublesome that $GIT_DIR/branches does not\nreally refer to a branch, but rather to a (possibly remote) repository.\n\n  - Combining the states from more than one lines of developments\n    is called \"merging\" and typically done between two branch\n    heads.  This is called \"resolving\" in the tutorial and there\n    is git-resolve-script command for it.\n\n  - A set of \"refs\" with the set of objects reachable from them\n    constitute a \"repository\".  Although currently there is no\n    provision for a repository to say that its objects are stored\n    in this and that object database, multiple repositories can\n    share the same object database, and there is not a conceptual\n    limit that a repository must retrive its objects from a\n    single object database.\n\nThis is referred to as \"git archive\" in the tutorial at first,\nand later as \"repository\". However, in \"Copying archives\", a\nvery confusing explanation tells us that a \"repository\" normally\nis a \"working tree\", where I would rather say that the repository\nlives inside a hidden subdirectory of the working tree.\n\ngit-fsck-cache.txt talks about an \"archive\", too. However, it then\nsays \"valid tree\", when sureley a repository is meant.\n\nEverywhere else, it is called \"repository\".\n\n  - The act of finding out the object names recorded in \"refs\" a\n    different repository records, optionally updating a local\n    \"refs\" with their values, and retrieving the objects\n    reachable from them is called \"fetching\".  Fetching immediately\n    followed by merging is called \"pulling\".\n\nIn that sense, git-http-pull would be more appropriately named\ngit-http-fetch, and analogous git-ssh-pull.\n\nAlso, git-pull-script.txt says \"Pull and merge\", contradicting this\ndefinition.\n\n  - The act of updating \"refs\" in a different repository with new\n    value and populating the object database(s) associated with\n    the repository is called \"pushing\".\n\n  - Currently refs/heads records branch heads of both locally\n    created branches and branches fetched from other\n    repositories.\n\n  - Currently, fetching always happen against a single branch\n    head on a remote repository, and (a remote repository, name\n    of the branch) is stored in $GIT_DIR/branches/ as a\n    short-hand mechanism.  A file in this directory identifies\n    a remote repository by its URL, and the branch to fetch/pull\n    from is identified with the URL fragment notation, absense of\n    which makes it default to \"master\".\n\n  - a \"pack\" usually consists of two files: a file containing objects\n    in a compressed format, and an index to the first file. If the\n    pack is uncompressed at once (e.g. when git-clone is called), the\n    index is not necessary.\n\ngit-pack-objects calls this a \"packed archive\" first, but then reverts\nto \"pack\". git-show-index.txt and git-verify-pack.txt call the .pack file\n\"packed GIT archive\", and the index \"idx file\". git-unpack-objects.txt\ncalls the .pack file \"pack archive\".\n\nI'd also add a short explanation of the following unambiguous terms:\n\n\"plumbing\", also referred to as \"core\": the basic set of programs and\nscripts usable to half-gods like Linus.\n\n\"porcelain\", also referred to as \"SCM\": a thin layer over the plumbing\nmaking GIT usage nice to regular people.\n\n\"type\": one of the identifiers \"commit\",\"tree\",\"tag\" and \"blob\" describing\nthe type of an object.\n\nCiao,\nDscho\n"},{"id":"6860","messageId":"Pine.LNX.4.58.0508051104510.3258@g5.osdl.org","threadId":"1377","inReplyTo":"Pine.LNX.4.63.0508051655480.8418@wgmdd8.biozentrum.uni-wuerzburg.de","subject":"Re: Terminology","fromName":"Linus Torvalds","fromEmail":"torvalds@osdl.org","sentAt":"2005-08-05T18:57:48Z","receivedAt":"2005-08-05T18:57:48Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Fri, 5 Aug 2005, Johannes Schindelin wrote:\n> \n> Tutorial says \"cache\" aka \"index\". Though technically, a cache\n> is the index file _plus_ the related objects in the object database.\n> git-update-cache.txt even makes the difference between the \"index\"\n> and the \"directory cache\".\n\nI think we should globally rename it to \"index\".\n\nThe \"directory cache\" and later \"cache\" naming came from when I started\ndoing the work - before git was even git at all, and had no backing store\nwhat-so-ever, I started out writing \"cache.h\" and \"read-cache.c\", and it\nwas really first a trial at doing a totally SCM-neutral directory cache\nfront-end.\n\nYou don't even see that in the git revision history, because that was \nbefore git was self-hosting - the project was partly started to also work \nas possibly just a fast front-end to something that wasn't as fast (ie \nthink something like a front-end to make \"monotone\" work better).\n\nSo the \"directory cache\" and \"cache\" naming comes from that historical \nbackground: it was really started as a front-end cache, and in fact the \n\".git\" directory was called \".dircache\" initially. You can see some of \nthat in the very earliest git releases: by then I had already done the \nbacking store, and the thing was already called \"git\", but the \"dircache\" \nnaming still remains in places.\n\nFor example, here's my \"backup\" target in the initial checkin:\n\n\tbackup: clean\n\t\tcd .. ; tar czvf dircache.tar.gz dir-cache\n\nwhich shows that not only did I call the resulting tar file \"dircache\", \nthe directory I was developing stuff in was called \"dir-cache\" as well ;)\n\nThe index obviously ended up doing a lot more, and especially with the\ndifferent stages it became much more than just a directory cache thing:  \nit's integral to how git does the fast part of a merge. So we should call\nit \"index\" and edit out the old \"cache\" and \"director cache\" naming\nentirely.\n\n>   - the directory which corresponds to the top of the hierarchy\n>     described in the index file; I've seen words like \"working\n>     tree\", \"working directory\", \"work tree\" used.\n> \n> The tutorial initially says \"working tree\", but then \"working\n> directory\". Usually, a directory does not include its\n> subdirectories, though. git-apply-patch-script.txt, git-apply.txt,\n> git-hash-object.txt, git-read-tree.txt\n> use \"work tree\". git-checkout-cache.txt, git-commit-tree.txt,\n> git-diff-cache.txt, git-ls-tree.txt, git-update-cache.txt contain\n> \"working directory\". git-diff-files.txt talks about a \"working tree\".\n\nI think we should use \"working tree\" throughout, since \"working directory\" \nis unix-speak for \"pwd\" and has a totally different meaning.\n\n>   - When the stat information a cache entry records matches what\n>     is in the work tree, the entry is called \"clean\" or\n>     \"up-to-date\".  The opposite is \"dirty\" or \"not up-to-date\".\n>\n>   - An index file can be in \"merged\" or \"unmerged\" state.  The\n>     former is when it does not have anything but stage 0 entries,\n>     the latter otherwise.\n\nI think the \"unmerged\" case should be mentioned in the \"cache entry\" \nthing, since it's really a per-entry state, exactly like \"dirty/clean\".\n\nThen, explaining a \"unmerged index\" as being an index file with some \nentries being unmerged makes more sense. \n\nAs it is, the above \"explains\" an index file as being unmerged by talking \nabout \"stage 0 entries\", which in turn haven't been explained at all.\n\n>   - A \"tree object\" can be recorded as a part of a \"commit\n>     object\".  The tree object is said to be \"associated with\" the\n>     commit object.\n> \n> In diffcore.txt, \"changeset\" is used in place of \"commit\".\n\nWe really should use \"commit\" throughout. ex-BK users sometimes lip into\n\"changeset\" (which in turn is probably because BK had these per-file\ncommits too - deltas), but there's no point in the distinction in git. A \ncommit is a commit.\n\n>   - The following objects are collectively called \"tree-ish\": a\n>     tree object, a commit object, a tag object that resolves to\n>     either a commit or a tree object, and can be given to\n>     commands that expect to work on a tree object.\n> \n> We could call this category an \"ent\".\n\nLOL. You are a total geek.\n\n>   - The files under $GIT_DIR/refs record object names, and are\n>     called \"refs\".  What is under refs/heads/ are called \"heads\",\n>     refs/tags/ \"tags\".  Typically, they are either object names\n>     of commit objects or tag objects that resolve to commit\n>     objects, but a tag can point at any object.\n> \n> The tutorial never calls them \"refs\", but instead \"references\".\n\nIt might be worth saying explicitly that a reference is nothing but the \nsame thing as a \"object name\" aka \"sha1\". And make it very clear that it \ncan point to any object type, although commits tend to be the most common \nthng you want to reference. That then leads naturally into a very specific \n_subcase_ of refs, namely a \"head\":\n\n>   - A \"head\" is always an object name of a commit, and marks the\n>     latest commit in one line of development.  A line of\n>     development is often called a \"branch\".  We sometimes use the\n>     word \"branch head\" to stress the fact that we are talking\n>     about a single commit that is the latest one in a \"branch\".\n> \n> In the tutorial, the latter is used in reverse: it talks about a\n> \"HEAD development branch\" and a \"HEAD branch\".\n> \n> I find it a little bit troublesome that $GIT_DIR/branches does not\n> really refer to a branch, but rather to a (possibly remote) repository.\n\nYes, I find the $GIT_DIR/branches naming to be confusing too. \n\nThey are really pointers to external repositories, and \"branch\" is\nconfusing. But I suspect the confusion is partly due to me, since I used\nto think (and argue) that we should aim for a \"separate repositories for\nseparate branches\" approach.\n\nThat single-branch-multiple-repository mentality came from my BK\nbackground, and from me thinking that local branches would be confusing.  \n\nJeff has been dragging me into the \"local branches are good\" camp, and\nthese days I'm obviously a big believer. But the blame for this confusion\nfalls squarely on me, with Pasky picking it up from there into cogito and\nusing the \"branches\" name, and then git pickin git back up from cogito\nthrough trying to compatible.\n\n>   - The act of finding out the object names recorded in \"refs\" a\n>     different repository records, optionally updating a local\n>     \"refs\" with their values, and retrieving the objects\n>     reachable from them is called \"fetching\".  Fetching immediately\n>     followed by merging is called \"pulling\".\n> \n> In that sense, git-http-pull would be more appropriately named\n> git-http-fetch, and analogous git-ssh-pull.\n> \n> Also, git-pull-script.txt says \"Pull and merge\", contradicting this\n> definition.\n\nTo confuse things even more, cogito calls a fetch \"pull\" and a pull \n\"update\".\n\nI personally think \"fetch\" is unambigious: it's just the act of fetching, \nwith no \"merge\" activity at all. So we should use that.\n\nWhat to call a \"fetch+merge\" is a bit ambiguous. I obviously prefer\n\"pull\", but cogito disagrees, and you're right, \"git-http-pull\" and\n\"git-ssh-pull\" both really do just fetches.\n\nBut I think \"update\" isn't right either: to me, update would be the \nnon-merging kind (ie I think \"update\" implies \"refresh\" which in turn \nimplies a \"fetch\"-like behaviour).\n\nSo I'd vote for making the suggested definition official: \"fetch\" means\nfetching the data, and \"pull\" means \"fetch + merge\". \n\nAnd \"update\" would be just something that happens to refs: A \"fetch\" will\nobviously update the reference that we had to the external tree we fetched\nfrom, while a commit/merge/whatever will obviously update the current\nbranch reference (HEAD).\n\nSo \"update\" would really be just a small technical detail.\n\n>   - a \"pack\" usually consists of two files: a file containing objects\n>     in a compressed format, and an index to the first file. If the\n>     pack is uncompressed at once (e.g. when git-clone is called), the\n>     index is not necessary.\n> \n> git-pack-objects calls this a \"packed archive\" first, but then reverts\n> to \"pack\". git-show-index.txt and git-verify-pack.txt call the .pack file\n> \"packed GIT archive\", and the index \"idx file\". git-unpack-objects.txt\n> calls the .pack file \"pack archive\".\n\nWe should just call them packs. An archive can be multiple packs and lots \nof non-packed objects too. \n\n> \"plumbing\", also referred to as \"core\": the basic set of programs and\n> scripts usable to half-gods like Linus.\n> \n> \"porcelain\", also referred to as \"SCM\": a thin layer over the plumbing\n> making GIT usage nice to regular people.\n> \n> \"type\": one of the identifiers \"commit\",\"tree\",\"tag\" and \"blob\" describing\n> the type of an object.\n\nYes. Some old docs may call this type a \"tag\", since I was really thinking\nin not in the SCM meaning at all, but in the _computer_architecture_\nmeaning, where people usually call objects with enforced types \"tagged\".\n\nIe from a computer architecture standpoint you can have \"tagged memory\" or\n\"tagged pointers\", and LISP machines are often implemented with the\npointers containing the type (\"tag\") of the thing they point to (for\nexample, the low two bits might be the \"tag\" on the pointer). So I was\ntalking about \"tagged objects\" when I just meant that the type of the\nobject was embedded in the object itself, the way tagged memory\narchitectures work.\n\nIn retrospect, that naming _really_ confused some people, I know I had\ntrouble explaining git concepts to David Wheeler because I used \"tagged\nobjects\" _not_ to mean a SCM style \"tag\", but to mean \"typed objects\".\n\nIf somebody sees an old reference to \"object tags\", those should all be \nfixed to say \"object types\".\n\n\t\t\tLinus\n"},{"id":"6863","messageId":"Pine.LNX.4.62.0508051531400.23721@iabervon.org","threadId":"1377","inReplyTo":"Pine.LNX.4.58.0508051104510.3258@g5.osdl.org","subject":"Re: Terminology","fromName":"","fromEmail":"barkalow@iabervon.org","sentAt":"2005-08-05T19:53:19Z","receivedAt":"2005-08-05T19:53:19Z","isPatch":false,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Fri, 5 Aug 2005, Linus Torvalds wrote:\n\n> On Fri, 5 Aug 2005, Johannes Schindelin wrote:\n> \n> >   - The files under $GIT_DIR/refs record object names, and are\n> >     called \"refs\".  What is under refs/heads/ are called \"heads\",\n> >     refs/tags/ \"tags\".  Typically, they are either object names\n> >     of commit objects or tag objects that resolve to commit\n> >     objects, but a tag can point at any object.\n> > \n> > The tutorial never calls them \"refs\", but instead \"references\".\n> \n> It might be worth saying explicitly that a reference is nothing but the \n> same thing as a \"object name\" aka \"sha1\".\n\nWell, it's an object name stored in a file. This adds a layer of \nindirection and a meaningful name.\n\n> So I'd vote for making the suggested definition official: \"fetch\" means\n> fetching the data, and \"pull\" means \"fetch + merge\". \n\nSo what's the converse of \"fetch\" (to rename git-ssh-push to)? \nMaybe \"ship\"?\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"6864","messageId":"Pine.LNX.4.63.0508060041550.10873@wgmdd8.biozentrum.uni-wuerzburg.de","threadId":"1377","inReplyTo":"Pine.LNX.4.58.0508051104510.3258@g5.osdl.org","subject":"Re: Terminology","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2005-08-05T23:07:16Z","receivedAt":"2005-08-05T23:07:16Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nwow! What a long mail! But I probably deserved it, quoting that lengthy \nmail from Junio...\n\nOn Fri, 5 Aug 2005, Linus Torvalds wrote:\n\n> On Fri, 5 Aug 2005, Johannes Schindelin wrote:\n> > \n> > Tutorial says \"cache\" aka \"index\". Though technically, a cache\n> > is the index file _plus_ the related objects in the object database.\n> > git-update-cache.txt even makes the difference between the \"index\"\n> > and the \"directory cache\".\n> \n> I think we should globally rename it to \"index\".\n\nTotally agree. The index is a central concept. But let's keep in mind -- \nand make future Documentation/ readers do the same -- that the index,\nwithout the referenced objects in the objects database, is only a \nskeleton.\n\n> The \"directory cache\" and later \"cache\" naming came from when I started\n> doing the work - before git was even git at all, and had no backing store\n> what-so-ever, I started out writing \"cache.h\" and \"read-cache.c\", and it\n> was really first a trial at doing a totally SCM-neutral directory cache\n> front-end.\n> \n> You don't even see that in the git revision history, because that was \n> before git was self-hosting - the project was partly started to also work \n> as possibly just a fast front-end to something that wasn't as fast (ie \n> think something like a front-end to make \"monotone\" work better).\n> \n> So the \"directory cache\" and \"cache\" naming comes from that historical \n> background: it was really started as a front-end cache, and in fact the \n> \".git\" directory was called \".dircache\" initially. You can see some of \n> that in the very earliest git releases: by then I had already done the \n> backing store, and the thing was already called \"git\", but the \"dircache\" \n> naming still remains in places.\n> \n> For example, here's my \"backup\" target in the initial checkin:\n> \n> \tbackup: clean\n> \t\tcd .. ; tar czvf dircache.tar.gz dir-cache\n> \n> which shows that not only did I call the resulting tar file \"dircache\", \n> the directory I was developing stuff in was called \"dir-cache\" as well ;)\n> \n> The index obviously ended up doing a lot more, and especially with the\n> different stages it became much more than just a directory cache thing:  \n> it's integral to how git does the fast part of a merge. So we should call\n> it \"index\" and edit out the old \"cache\" and \"director cache\" naming\n> entirely.\n\nI quoted this entirely, for a good reason: Linus, one day you really \nshould write a Wikibook about all the \"small\" projects you started. I \nstill remember the words \"I'm doing a (free) operating system (just a \nhobby, won't be big...\". There's so much to be learnt about good \nengineering. And people do want to add there anecdotes to it.\n\n> >   - the directory which corresponds to the top of the hierarchy\n> >     described in the index file; I've seen words like \"working\n> >     tree\", \"working directory\", \"work tree\" used.\n> > \n> > The tutorial initially says \"working tree\", but then \"working\n> > directory\". Usually, a directory does not include its\n> > subdirectories, though. git-apply-patch-script.txt, git-apply.txt,\n> > git-hash-object.txt, git-read-tree.txt\n> > use \"work tree\". git-checkout-cache.txt, git-commit-tree.txt,\n> > git-diff-cache.txt, git-ls-tree.txt, git-update-cache.txt contain\n> > \"working directory\". git-diff-files.txt talks about a \"working tree\".\n> \n> I think we should use \"working tree\" throughout, since \"working directory\" \n> is unix-speak for \"pwd\" and has a totally different meaning.\n\nI hoped so much.\n\n> >   - An index file can be in \"merged\" or \"unmerged\" state.  The\n> >     former is when it does not have anything but stage 0 entries,\n> >     the latter otherwise.\n> \n> I think the \"unmerged\" case should be mentioned in the \"cache entry\" \n> thing, since it's really a per-entry state, exactly like \"dirty/clean\".\n> \n> Then, explaining a \"unmerged index\" as being an index file with some \n> entries being unmerged makes more sense. \n> \n> As it is, the above \"explains\" an index file as being unmerged by talking \n> about \"stage 0 entries\", which in turn haven't been explained at all.\n\nThat's right. We probably should copy a bit from git-read-tree.txt, or at \nleast reference it in the glossary.\n\n> >   - A \"tree object\" can be recorded as a part of a \"commit\n> >     object\".  The tree object is said to be \"associated with\" the\n> >     commit object.\n> > \n> > In diffcore.txt, \"changeset\" is used in place of \"commit\".\n> \n> We really should use \"commit\" throughout. ex-BK users sometimes lip into\n> \"changeset\" (which in turn is probably because BK had these per-file\n> commits too - deltas), but there's no point in the distinction in git. A \n> commit is a commit.\n\nThat is, if you don't do \"git-update-cache <single-file>\" (which is not \npossible with some porcelains).\n\nApart from that: I think that it is quite important to make the \ndistinction between a \"commit\" and a \"commit object\". Newbies (in that \ncase, people working with CVS are newbies to the concepts of git, too) \ntend understand better what you say, if you make that distinction very \nclearly, IMHO.\n\n> >   - The following objects are collectively called \"tree-ish\": a\n> >     tree object, a commit object, a tag object that resolves to\n> >     either a commit or a tree object, and can be given to\n> >     commands that expect to work on a tree object.\n> > \n> > We could call this category an \"ent\".\n> \n> LOL. You are a total geek.\n\nI take that as a compliment :-)\n\n> >   - The files under $GIT_DIR/refs record object names, and are\n> >     called \"refs\".  What is under refs/heads/ are called \"heads\",\n> >     refs/tags/ \"tags\".  Typically, they are either object names\n> >     of commit objects or tag objects that resolve to commit\n> >     objects, but a tag can point at any object.\n> > \n> > The tutorial never calls them \"refs\", but instead \"references\".\n> \n> It might be worth saying explicitly that a reference is nothing but the \n> same thing as a \"object name\" aka \"sha1\". And make it very clear that it \n> can point to any object type, although commits tend to be the most common \n> thng you want to reference. That then leads naturally into a very specific \n> _subcase_ of refs, namely a \"head\":\n\nDo not forget signed tags! Strictly said, these are references to \nreferences which are signed.\n\n> >   - A \"head\" is always an object name of a commit, and marks the\n> >     latest commit in one line of development.  A line of\n> >     development is often called a \"branch\".  We sometimes use the\n> >     word \"branch head\" to stress the fact that we are talking\n> >     about a single commit that is the latest one in a \"branch\".\n> > \n> > In the tutorial, the latter is used in reverse: it talks about a\n> > \"HEAD development branch\" and a \"HEAD branch\".\n\nActually, I don't think it a good idea to talk about a \"HEAD branch\" or \n\"development branch\". I'd prefer \"branch\".\n\n> > I find it a little bit troublesome that $GIT_DIR/branches does not\n> > really refer to a branch, but rather to a (possibly remote) repository.\n> \n> Yes, I find the $GIT_DIR/branches naming to be confusing too. \n\nI don't know if we can hide it from the users, or if we should bite the \napple and rename it to \"remotes/\", or even better \"repositories/\".\n\n> Jeff has been dragging me into the \"local branches are good\" camp, and\n> these days I'm obviously a big believer.\n\nI think that Jeff really deserves the credit for this. Yours truly was \nconvinced that one repository should hold one branch only. But I was \nconvinced otherwise, too.\n\n> >   - The act of finding out the object names recorded in \"refs\" a\n> >     different repository records, optionally updating a local\n> >     \"refs\" with their values, and retrieving the objects\n> >     reachable from them is called \"fetching\".  Fetching immediately\n> >     followed by merging is called \"pulling\".\n> > \n> > In that sense, git-http-pull would be more appropriately named\n> > git-http-fetch, and analogous git-ssh-pull.\n> > \n> > Also, git-pull-script.txt says \"Pull and merge\", contradicting this\n> > definition.\n> \n> To confuse things even more, cogito calls a fetch \"pull\" and a pull \n> \"update\".\n\nI really think this should be unified. Pasky?\n\n> I personally think \"fetch\" is unambigious: it's just the act of fetching, \n> with no \"merge\" activity at all. So we should use that.\n\nAgree.\n\n> What to call a \"fetch+merge\" is a bit ambiguous. I obviously prefer\n> \"pull\", but cogito disagrees, and you're right, \"git-http-pull\" and\n> \"git-ssh-pull\" both really do just fetches.\n\nLet's rename them before 1.0.\n\n> But I think \"update\" isn't right either: to me, update would be the \n> non-merging kind (ie I think \"update\" implies \"refresh\" which in turn \n> implies a \"fetch\"-like behaviour).\n> \n> So I'd vote for making the suggested definition official: \"fetch\" means\n> fetching the data, and \"pull\" means \"fetch + merge\". \n\nThis should be discussed. Obviously, I come from CVS and understand \n\"update\" to be what cogito says it is. But then, it is also true that \nCVS's usage of \"update\" is misleading, because it really does a merge, not \nforcing the user to do a commit before merge (because that is not possible \nin CVS). So basically, I agree: \"pull\" is unambiguous as far as I am \nconcerned.\n\n> >   - a \"pack\" usually consists of two files: a file containing objects\n> >     in a compressed format, and an index to the first file. If the\n> >     pack is uncompressed at once (e.g. when git-clone is called), the\n> >     index is not necessary.\n> > \n> > git-pack-objects calls this a \"packed archive\" first, but then reverts\n> > to \"pack\". git-show-index.txt and git-verify-pack.txt call the .pack file\n> > \"packed GIT archive\", and the index \"idx file\". git-unpack-objects.txt\n> > calls the .pack file \"pack archive\".\n> \n> We should just call them packs. An archive can be multiple packs and lots \n> of non-packed objects too. \n\nAnd they can have pack indices which do not relate at all to the central \nGIT index.\n\n> > \"type\": one of the identifiers \"commit\",\"tree\",\"tag\" and \"blob\" describing\n> > the type of an object.\n> \n> Yes. Some old docs may call this type a \"tag\", since I was really thinking\n> in not in the SCM meaning at all, but in the _computer_architecture_\n> meaning, where people usually call objects with enforced types \"tagged\".\n> \n> Ie from a computer architecture standpoint you can have \"tagged memory\" or\n> \"tagged pointers\", and LISP machines are often implemented with the\n> pointers containing the type (\"tag\") of the thing they point to (for\n> example, the low two bits might be the \"tag\" on the pointer). So I was\n> talking about \"tagged objects\" when I just meant that the type of the\n> object was embedded in the object itself, the way tagged memory\n> architectures work.\n> \n> In retrospect, that naming _really_ confused some people, I know I had\n> trouble explaining git concepts to David Wheeler because I used \"tagged\n> objects\" _not_ to mean a SCM style \"tag\", but to mean \"typed objects\".\n> \n> If somebody sees an old reference to \"object tags\", those should all be \n> fixed to say \"object types\".\n\nAgree.\n\nCiao,\nDscho\n"},{"id":"6865","messageId":"Pine.LNX.4.63.0508060107350.10873@wgmdd8.biozentrum.uni-wuerzburg.de","threadId":"1377","inReplyTo":"Pine.LNX.4.62.0508051531400.23721@iabervon.org","subject":"Re: Terminology","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2005-08-05T23:08:48Z","receivedAt":"2005-08-05T23:08:48Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Fri, 5 Aug 2005, barkalow@iabervon.org wrote:\n\n> On Fri, 5 Aug 2005, Linus Torvalds wrote:\n> \n> > On Fri, 5 Aug 2005, Johannes Schindelin wrote:\n> > \n> > >   - The files under $GIT_DIR/refs record object names, and are\n> > >     called \"refs\".  What is under refs/heads/ are called \"heads\",\n> > >     refs/tags/ \"tags\".  Typically, they are either object names\n> > >     of commit objects or tag objects that resolve to commit\n> > >     objects, but a tag can point at any object.\n> > > \n> > > The tutorial never calls them \"refs\", but instead \"references\".\n> > \n> > It might be worth saying explicitly that a reference is nothing but the \n> > same thing as a \"object name\" aka \"sha1\".\n> \n> Well, it's an object name stored in a file. This adds a layer of \n> indirection and a meaningful name.\n\nYes.\n\n> > So I'd vote for making the suggested definition official: \"fetch\" means\n> > fetching the data, and \"pull\" means \"fetch + merge\". \n> \n> So what's the converse of \"fetch\" (to rename git-ssh-push to)? \n> Maybe \"ship\"?\n\nI actually like \"push\". You know, not everybody agrees that \"push\" is the \nopposite of \"pull\"...\n\nCiao,\nDscho\n"}]}