{"thread":{"id":"25473","subject":"Git terminology: remote, add, track, stage, etc.","startedAt":"2010-10-18T20:45:50Z","lastAt":"2011-02-12T23:14:22Z","messageCount":59,"participants":["Thore Husfeldt","Jonathan Nieder","Sverre Rabbelier","Matthieu Moy","Jakub Narebski","Junio C Hamano","Miles Bader","Matthijs Kooijman","Wincent Colaiuta","Ramkumar Ramachandra","Eugene Sajine","Nicolas Pitre","Drew Northup","Michael Haggerty","Paul Bolle","Ævar Arnfjörð Bjarmason"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"153747","messageId":"8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com","threadId":"25473","inReplyTo":null,"subject":"Git terminology: remote, add, track, stage, etc.","fromName":"Thore Husfeldt","fromEmail":"thore.husfeldt@gmail.com","sentAt":"2010-10-18T20:45:50Z","receivedAt":"2010-10-18T20:45:50Z","isPatch":false,"sender":{"key":"thore.husfeldt@gmail.com","avatar":"https://gravatar.com/avatar/d09b67dd2db2b4213ff54d74d8db9d0dd2830a92b60bea8828ce3132cdf8b853?d=mp&s=160"},"body":"I’ve just learned Git. What a wonderful system, thanks for building\nit. \n\nAnd what an annoying learning experience. \n\nI promised myself to try to remember what made it all so hard, and to\nwrite it down in a comprehensive and possibly even constructive\nfashion. Here it is, for what it’s worth. Read it as the friendly, but\nsomewhat exasparated suggestions of a newcomer. I’d love to help (in\nthe form of submitting patches to the documentation or CLI responses),\nbut I’d like to test the waters first.\n\nSo, in no particular order, here are the highlights of my former\nconfusion, if only for your entertainment. Comments are welcome, in\nparticular where my suggestions are born out of ignorance.\n\nRemote (tracking) branches\n--------------------------\n\nThere are at least two uses of the word *tracking* in Git's\nterminology.\n\nThe first, used in the form “git tracks a file” (in the sense that Git\nknows about the file) is harmless enough, and is handled under `git\nadd` below.\n\nBut the real monster is the *tracking branch*, sometimes called the\nremote branch, the remote-tracking branch, or the remote tracking\nbranch. Boy did that ever confuse me. And, reading the git mailing\nlist and the web, many others. There are so many things wrong with how\nthis simple concept is obfuscated by the documentation that I have a\nhard time organising my thoughts about writing it down.\n\nPlease, *please* fix this. It was the single most confusing and\nannoying part of learning Git.\n\nFirst, the word, “tracking”. These branches don’t track or follow\nanything. They are standing completely still. Please believe me that\nwhen first you are led to believe that origin/master tracks a branch\non the remote (like a hound tracks it quarry, or a radar tracks a\nflight) that it is very difficult to hunt this misunderstanding down:\nI believed for a long time that the tracking branch stayed in sync,\nautomagically, with a synonymous branch at the remote. The CLI and\ndocumentation worked very hard to keep me in that state of\nignorance. I *know* that my colleague just updated the remote\nrepository, yet the remote branch (or is the remote tracking branch?\nor the remote-tracking branch?) is as it always was...? (How could I\n*ever* believe that? Well, *now* I get it, and have a difficult time\nrecollecting that misunderstanding. *Now* it’s easy.)\n\nSecond, the word “remote” as opposed to “local”, a dichotomy enforced\nby both the documentation and by the output of `git branch -r` (list\nall remote branches, says user-manual.txt). Things began to dawn on me\nonly when I understood that origin/master is certainly and absolutely\na “local” branch, in the sense that it points to a commit in my local\nrepository. (It differs from my other local branches mainly in how it\nis updated. It’s not committed to, but fetched to. But both are local,\nand the remote can be many commits ahead of me.)\n\nSo, remote tracking branches are neither remote (they are *local*\ncopies of how the remote once was) and they stand completely still\nuntil you tell them to “fetch”. So remote means local, and tracking\nmeans still, “local still-standing” would be a less confusing term\nthat “remote tracking”. Lovely.\n\nTracking branches *track* in the sense that a stuffed Basset Hound\ntracks. Namely, not. It‘s a dream of what once was.\n\nThe hyphenated *remote-tracking* is a lot better terminology already\n(and sometimes even used in the documentation), because at least it\ndoesn't pretend to be a remote branch (`git branch -r`, of course,\nstill does). So that single hyphen already does some good, and should\nbe edited for consistency. (It did take time for me to convince myself\nduring the learning process that “remote tracking” and\n“remote-tracking” probably are the same thing, and “tracked remote”\nsomething else, abandoning and resurrecting these hypetheses several\ntimes.)\n\nAnd *even if* the word was meaningful and consistenly spelt, the\ndocumentation uses it to *refer* to different things. Assume that we\nhave the branches master, origin/master, and origin’s master\n(understanding that they exist, and are different, is another Aha!\nmoment largely prevented by the documentation). For 50 points, which\nis the remote tracking branch? Or the remote-tracking branch? The\nremote branch? Which branch tracks which other branch? Does master\ntrack anything? Nobody seems to know, and documentation and CLI\ninclude various inconsistent suggestions. (I know there have been\nlong, and inconclusive threads about this on the git mailing list, and\nI learned a lot from seeing other people’s misconceptions mirror my\nown.) Granted, I think the term “tracked remote branch” is used with\nlaudable consistentcy to refer to a branch on the remote. And “remote\ntracking branch” (with our without the hyphen) more often than not\nrefers to origin/master. It may be that terminology is slowly\nconverging. (To something confusing, but still...)\n\nBut to appreciate how incredibly difficult this was to understand,\ncheck this, from the Git Community book:\n\n A 'tracking branch' in Git is a local branch that is connected to\n a remote branch.\n\nTo a new user, who *almost* gets it, this is just a slap in the\nface. Which one of these is origin/master again? None? (Or rather, it\nis the confirmation one needs that nobody in the Git community cares\nmuch, so the once-believed-to-be-carefully-worded documentation loses\nsome of its authority and therefore the learner can abandon some\nmisunderstandings.)\n\nThere probably is a radical case to be made for abandoning the word\n“tracking” entirely. First, because tracking branches don’t track, and\nsecond because “tracking” already means something else in Git (see\nbelow). I realise that this terminology is now so ingrained in Git\nusers that conservatism will probably perpetuate it. But it would be\n*very* helpful to think this through, and at least agree on who\n“tracks” what. In the ideal world, origin/master would be something\nlike “the fetching branch” for the origin’s master, or the “snapshot\nbranch” or the “fetched branch”. (I am partial to use “fetching”\nbecause it makes that operation a first-class conceptual citizen,\nrather than pulling, which is another siren that lures newbies into a\nmaelstroem of confusion.)\n\nMore radically, I am sure some head scratching would be able to find\nuseful terminology for master, origin/master, and origin’s master. I’d\nlove to see suggestions. As I said, I admire how wonderfully simple\nand clean this has been implemented, and the documentation, CLI, and\nterminology should reflect that.\n\nThe staging area\n----------------\n\nThe wonderful and central concept of staging area exists under at\nleast three names in Git terminology. And that’s really, really\nannoying. The index, the cache, and the staging area are all the same,\nwhich is a huge revelation to a newcomer.\n\nThis problem could of course be easily fixed by making up your\nmind. The decision which of the three terms to adopt is somewhat\narbitrary, but *staging area* gives the strongest and best\nmetaphor. It also verb quite well, even though it is not the best,\nshortest noun. *Index* would have been a good word for the files known\nto Git (what is now called, sometimes, “tracked files”), and *cache*\nis terrible in any case.\n\n`git stage` is already part of the distribution. Great.\n\n1. Search for index and cache in the documentation and rephrase any\nand all their occurences to use “staged” (or, if it can’t be avoided\n“the staging area”) instead. Say “staged to be committed” often, it’s\na strong metaphor.\n\n2. Introduce the alias `git unstage` for `git reset HEAD` in the\nstandard distribution.\n\n3. Duplicate various occurences of `cached` flags as `staged` (and\nchange the documentation and man pages accordingly), so as to have,\ne.g., `git diff --staged`.\n\ngit status\n----------\n\nOne of the earliest-to-use commands is `git status`, whose message are\n*wordy*, but were initially completely unhelpful to me. In particular,\n\n working directory clean\n\nClean? What’s this now? Clean and dirty are Git slang, and not what I\nwant to meet as a new user. The message should inform me that the\nuntracked files in the working directory are equal to their previous\ncommit. But there are other things wrong with the message. For\nexample, even though there’s nothing to commit: `nothing added to\ncommit but untracked files present (use \"git add\" to track)`? The last\nparanethesis should set off warning bells already. And what did clean\nmean with respect to untracked files? And “added to commmit”? That\nsounds like amending. We add to the index or the staging area, don’t\nwe, “ready to be included in the next commit,” so they aren’t added to\nthat commit quite yet?\n\n changed but not updated:\n\nI’m still not sure what “update” was ever supposed to mean in this\nsentence. I just edited the file, so it’s updated, for crying out\nloud! The message might just say “Changed files, but not staged to be\ncommitted.” The meant-to-be helpful “use [...] to update what will be\ncommitted” is another can of worms, and I can find at least two ways\nto completely misunderstand this. Change to “use `git stage ` to\nstage”. (With the new command name it’s almost superfluous.)\n \nHere are some concrete suggestions:\n\n1.\n\n nothing added to commit but untracked files present\n\nshould be\n\n nothing staged to commit, but untracked files present\n\n(Comment: maybe “... but working directory contains untracked files.”\nI realise that “directory” is not quite comprehensive here, because\nfiles can reside in subdirectories. But I’d like to be more concrete\nthan “be present”.)\n\n2.\n Untracked files:\n (use \"git add ...\" to include in what will be committed)\n\nshould be\n\n Untracked files:\n (use \"git track \" to track)\n\n3.\n\n Changes to be committed:\n (use \"git reset HEAD ...\" to unstage)\n\nshould be\n\n Staged to be committed:\t\t \n (use \"git unstage \" to unstage)\n\nAdding\n------\n\nThe tutorial tells us that \n\n Many revision control systems provide an add command that tells\n the system to start tracking changes to a new file. Git's add\n command does something simpler and more powerful: git add is used\n both for new and newly modified files, and in both cases it takes\n a snapshot of the given files and stages that content in the\n index, ready for inclusion in the next commit.\n\nThis is true, and once you grok how Git actually works it also makes\ncomplete sense. “Making the file known to Git” (sometimes called\n“tracking the file”) and “staging for the next commit” result in the\nexact same operations, from Git’s perspective.\n\nBut this is a good example of what’s wrong with the way the\ndocumentation thinks: Git’s implementation perspective should not\ndefine how concepts are explained. In particular, *tracking* (in the\nsense of making a file known to git) and *staging* are conceptually\ndifferent things. In fact, the two things remain conceptually\ndifferent later on: un-tracking (removing the file from Git’s\nworldview) and un-staging are not the same thing at all, neither\nconceptually nor implementationally. The opposite of staging is `git\nreset HEAD ` and the opposite of tracking is -- well, I’m not\nsure, actually. Maybe `git update-index --force-remove `?\nBut this only strenghtens my point: tracking and staging are different\nconcepts, and therefore deserve different terms in the documentation\nand (ideally) in the CLI.\n\nThe entire quoted paragraph in the tutorial can be removed: there’s\nsimply no reason to tell the reader that git behaves differently from\nother version control systems (indeed, to take some perverse *pride*\nin that fact). \n\nFixing this requires no change to the implementation. `git stage` is\nalready a synonym for `git add`. It merely requires discipline in\nusing the terminology of staging. Note that it completely valid to\ntell the reader, maybe immediately and in a footnote, that `git add`\nand `git stage` *are* indeed synonyms, because of Git’s elegant\nmodel. In fact, given the amount of documentation cruft one can find\non the Internet, this would be a welcome footnote.\n\nAn even more radical suggestion (which would take all of 20 seconds to\nimplement) is to introduce `git track` as another alias for `git\nadd`. (See above under `git status`). This would be especially useful\nif tracking *branches* no longer existed.\n\nThere’s another issue with this, namely that “added files are\nimmediately staged”. In fact, I do understand why Git does that, but\nconceptually it’s pure evil: one of the conceptual conrnerstones of\nGit -- that files can be tracked and changed yet not staged, i.e., the\nstaging areas is conceptually a first-class citizen -- is violated\nevery time a new file is “born”. Newborn files are *special* until\ntheir first commit, and that’s a shame, because the first thing the\nnew file (and, vicariously, the new user) experiences is an\naberration. I admit that I have not thought this through."},{"id":"153748","messageId":"20101018211522.GA7655@burratino","threadId":"25473","inReplyTo":"8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-18T21:15:22Z","receivedAt":"2010-10-18T21:15:22Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi Thore,\n\nThore Husfeldt wrote:\n\n> what an annoying learning experience. \n> \n> I promised myself to try to remember what made it all so hard, and to\n> write it down in a comprehensive and possibly even constructive\n> fashion.\n\nThanks for doing this work!\n\n> There probably is a radical case to be made for abandoning the word\n> “tracking” entirely. First, because tracking branches don’t track, and\n> second because “tracking” already means something else in Git (see\n> below).\n\nI think you are overthinking this \"tracking like a Basset hound\" thing.\n\nWhen a person keeps a diary to track their appointments, is it always\nup to date? No, it is only as up to date as the person is diligent.\nSimilarly, git provides a namespace for branches that a person can\nuse to track remote branches, which is only as up to date as one\nkeeps it.\n\nSo what would be a better term?\n\n> In the ideal world, origin/master would be something\n> like “the fetching branch” for the origin’s master, or the “snapshot\n> branch” or the “fetched branch”.\n\nFamiliarity might be leaving me blind, but these all sound even more\nconfusing to me. In fact, origin/master is not only updated by\nfetching but by pushing (at least if I remember correctly). It is\nmeant to be git's local memory of remote content.\n\nUsing the term \"remote-tracking\" consistently would certainly be an\nimprovement and would make it easier to do a search-and-destroy (erm,\n-and-replace) if another term comes up that seems to fit the concept\nbetter.\n\n> The wonderful and central concept of staging area exists under at\n> least three names in Git terminology. And that’s really, really\n> annoying. The index, the cache, and the staging area are all the same,\n> which is a huge revelation to a newcomer.\n\nHeh. Personally I tend to think in terms of \"the index\".\n\ne.g., \"git add\" registers changes for use in the next commit.\nInformation about the commit in preparation is stored in the\nindex.\n\nWhy? Because \"staging area\" has this misleading feeling of\nnot-jargon. It is jargon and when misused can be very confusing\n(to me, at least).\n\n> 2. Introduce the alias `git unstage` for `git reset HEAD` in the\n> standard distribution.\n\nDoesn't \"git reset\" ('reset the staged content to match...') fit the\nsame metaphor?\n\n> 3. Duplicate various occurences of `cached` flags as `staged` (and\n> change the documentation and man pages accordingly), so as to have,\n> e.g., `git diff --staged`.\n\nAlready exists (though in practice it tends to be easier to teach\n--cached since that is the option that documents all over the web\nuse).\n\n> Clean? What’s this now? Clean and dirty are Git slang, and not what I\n> want to meet as a new user. The message should inform me that the\n> untracked files in the working directory are equal to their previous\n> commit.\n\nHuh?\n\nAnyway, improvements welcome (in the form of a simple mockup, or even\nbetter, patches).\n\n> changed but not updated:\n> \n> I’m still not sure what “update” was ever supposed to mean in this\n> sentence.\n\nIt's historical residue. (What is now done with \"git add\" used to be\ndone with \"git update-index\").\n\n> Untracked files:\n> (use \"git add ...\" to include in what will be committed)\n>\n> should be\n>\n> Untracked files:\n> (use \"git track \" to track)\n\nIs this \"git track\" a synonym for \"git add -N\"?\n\n> The opposite of staging is `git\n> reset HEAD ` and the opposite of tracking is -- well, I’m not\n> sure, actually.\n\nAh, this is a kind of obnoxious thing! For a newly added file,\n\n\tgit reset -- \n\nought to un-add it, but it doesn't.\n\nFor a file that has been around for a while, removal is imho just\nadding a different kind of change. It would be nice if\n\n\tgit add -- \n\npointed to \"git rm --cached\" to help the operator to do that.\n\n> The entire quoted paragraph in the tutorial can be removed: there’s\n> simply no reason to tell the reader that git behaves differently from\n> other version control systems\n\nHow will a person used to e.g. cvs ever adjust if they don't even\nrealize git is different?\n\nHope that helps,\nJonathan\n"},{"id":"153749","messageId":"AANLkTimkovH9OysLSxA+=di89Xi+dTCYL5hRPmNaADDH@mail.gmail.com","threadId":"25473","inReplyTo":"8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-10-18T21:35:32Z","receivedAt":"2010-10-18T21:35:32Z","isPatch":false,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\n[+Scott, who's done a lot of work on making git more newbie friendly]\n[+Jonathan, I saw his reply just before sending this]\n\nOn Mon, Oct 18, 2010 at 15:45, Thore Husfeldt wrote:\n> I’ve just learned Git. What a wonderful system, thanks for building\n> it.\n\nThanks.\n\n> And what an annoying learning experience.\n\nThanks again :).\n\n> I promised myself to try to remember what made it all so hard, and to\n> write it down in a comprehensive and possibly even constructive\n> fashion. Here it is, for what it’s worth. Read it as the friendly, but\n> somewhat exasperated suggestions of a newcomer. I’d love to help (in\n> the form of submitting patches to the documentation or CLI responses),\n> but I’d like to test the waters first.\n\nAwesome! Your experiences are very welcome indeed!\n\n> So, remote tracking branches are neither remote (they are *local*\n> copies of how the remote once was) and they stand completely still\n> until you tell them to “fetch”. So remote means local, and tracking\n> means still, “local still-standing” would be a less confusing term\n> that “remote tracking”. Lovely.\n\n*chortles*, nicely observed.\n\n> The hyphenated *remote-tracking* is a lot better terminology already\n> (and sometimes even used in the documentation), because at least it\n> doesn't pretend to be a remote branch (`git branch -r`, of course,\n> still does).\n\nWhat do you mean with the last part (about `git branch -r`)? The fact\nthat 'refs/remotes' is not immutable?\n\n> So that single hyphen already does some good, and should\n> be edited for consistency.\n\nIf we agree that \"remote-tracking\" is the way to go, a patch doing\nsuch editing would be very welcome.\n\n> And *even if* the word was meaningful and consistently spelt, the\n> documentation uses it to *refer* to different things. Assume that we\n> have the branches master, origin/master, and origin’s master\n> (understanding that they exist, and are different, is another Aha!\n> moment largely prevented by the documentation).\n\nHow could the documentation make this more clear?\n\n> Or rather, it is the confirmation one needs that nobody in the Git\n> community cares much\n\nOn the contrary, we care a lot, but once you're not a new user\nyourself anymore, it's hard to know what to fix.\n\n> There probably is a radical case to be made for abandoning the word\n> “tracking” entirely. First, because tracking branches don’t track, and\n> second because “tracking” already means something else in Git (see\n> below). I realise that this terminology is now so ingrained in Git\n> users that conservatism will probably perpetuate it. But it would be\n> *very* helpful to think this through, and at least agree on who\n> “tracks” what. In the ideal world, origin/master would be something\n> like “the fetching branch” for the origin’s master, or the “snapshot\n> branch” or the “fetched branch”.\n> [...]\n> More radically, I am sure some head scratching would be able to find\n> useful terminology for master, origin/master, and origin’s master. I’d\n> love to see suggestions. As I said, I admire how wonderfully simple\n> and clean this has been implemented, and the documentation, CLI, and\n> terminology should reflect that.\n\nI don't have any objections to changing these terms, but I don't have\nany suggestions on what to change them _to_.\n\n> 2. Introduce the alias `git unstage` for `git reset HEAD` in the\n> standard distribution.\n\n(or 'git rm --cached' for newly added files)\n\n>    nothing added to commit but untracked files present\n>\n> should be\n>\n>    nothing staged to commit, but untracked files present\n\nI've always liked the whole 'stage(d)' concept, so I like this, but I\nremember Junio being fairly hesitant to use it more extensively.\n\n> (Comment: maybe “... but working directory contains untracked files.”\n> I realise that “directory” is not quite comprehensive here, because\n> files can reside in subdirectories.\n\nWe use \"worktree\" elsewhere, how about that?\n\n>    (use \"git track \" to track)\n\nSo basically you want to split out 'git add' into 'git track' and 'git stage'?\n\n>    Changes to be committed:\n>    (use \"git reset HEAD ...\" to unstage)\n>\n> should be\n>\n>    Staged to be committed:\n>    (use \"git unstage \" to unstage)\n\nThis would be extra nice since 'git unstage' could also be used in a\nfresh repository.\n\n\n> But this is a good example of what’s wrong with the way the\n> documentation thinks: Git’s implementation perspective should not\n> define how concepts are explained. In particular, *tracking* (in the\n> sense of making a file known to git) and *staging* are conceptually\n> different things. In fact, the two things remain conceptually\n> different later on: un-tracking (removing the file from Git’s\n> worldview) and un-staging are not the same thing at all, neither\n> conceptually nor implementationally.\n\nFair point, I think.\n\n> The opposite of staging is `git\n> reset HEAD ` and the opposite of tracking is -- well, I’m not\n> sure, actually. Maybe `git update-index --force-remove `?\n\n'git rm --cached'\n\n> The entire quoted paragraph in the tutorial can be removed: there’s\n> simply no reason to tell the reader that git behaves differently from\n> other version control systems\n\nI disagree, many people come from another VCS, and pointing out where\ntheir assumptions are invalid is generally useful.\n\n> There’s another issue with this, namely that “added files are\n> immediately staged”. In fact, I do understand why Git does that, but\n> conceptually it’s pure evil: one of the conceptual conrnerstones of\n> Git -- that files can be tracked and changed yet not staged, i.e., the\n> staging areas is conceptually a first-class citizen -- is violated\n> every time a new file is “born”. Newborn files are *special* until\n> their first commit, and that’s a shame, because the first thing the\n> new file (and, vicariously, the new user) experiences is an\n> aberration.\n\nEh, I think it's not an aberration, it's more of a convenience. I\ndon't think the benefit of making the concept of tracking vs. staging\nclear to the user is worth the hassle of having to execute two things\nto do one thing (staging a new file). You can also see it the other\nway around, why are new files any different from other files? Why\nshouldn't you be able to stage new files?\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"153750","messageId":"vpq8w1v5gce.fsf@bauges.imag.fr","threadId":"25473","inReplyTo":"8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-10-18T21:41:21Z","receivedAt":"2010-10-18T21:41:21Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Thore Husfeldt writes:\n\n> Read it as the friendly, but\n> somewhat exasparated suggestions of a newcomer. I’d love to help (in\n> the form of submitting patches to the documentation or CLI responses),\n> but I’d like to test the waters first.\n\n(it's common practice here to test the water with RFC/PATCHes too)\n\n> There are at least two uses of the word *tracking* in Git's\n> terminology.\n\nActually, there's a third, known to be rather unfortunate.\n\nFor example, when you clone a repository, by default, you end up with\n\n1) The master branch hosted remotely\n2) origin/master, locally, but \"remote-tracking\"\n3) master, your working branch.\n\nWhen you do a \"git pull\" when sitting on local branch master, Git\nknows it must :\n\na) fetch (i.e. download) from branch 1) into branch 2)\nb) merge from branch 2) into branch 1)\n\nRule a) come from remote..fetch, and rule b) comes from\nbranch.master.merge in your .git/config.\n\nUsually, we refer to tracking branch to mean rule a), but the \"track\"\nin \"git branch --track\" means \"setup git for rule b) above\".\n\nWe already came up with a better wording, namely \"upstream\", and used\nin in \"git push --set-upstream\". Probably a next step would be to\ndeprecate any other occurence of --track meaning the same thing (git\ncheckout --track seems to me to be a candidate, git branch has both\n--track and --set-upstream). One difficulty is to do that with\nbackward compatibility in mind.\n\n> 3. Duplicate various occurences of `cached` flags as `staged` (and\n> change the documentation and man pages accordingly), so as to have,\n> e.g., `git diff --staged`.\n\nI do like this, but to be complete, one should also deal with more\ncomplex cases. For example, \"git apply\" has _both_ --index and\n--cached, with different semantics.\n\nAnd changing just _some_ of the occurences of --index and --cached may\nhelp, but do not fix the problem of inconsistancies. Up to now, there\nhave been many efforts towards consistancy, but I guess no one had the\ncourrage of doing a global-enough approach to eliminate all\ninconsistancies.\n\nIn other words, I encourage you to continue the effort you've stated\nhere, but that won't help much unless you push the idea far enough\nIMHO.\n\n> changed but not updated:\n>\n> I’m still not sure what “update” was ever supposed to mean in this\n> sentence.\n\nHistorically, the staging area was seen as a cache (hence the name),\nwhich was purposedly out-of-date when doing a partial commit. Hence,\nGit inherited some of the terminology of usual caches (a cache is\n\"dirty\" when it's not in sync with what it caches, \"clean\" when it is,\nand you \"update\" it to make it in sync).\n\nBut I do agree that the analogy with a cache is disturbing for the\nuser, even if it's meaningful for the developper: as a user, a cache\nis meant to be a performance optimization, not supposed to interfer\nwith the functionality.\n\n> 2.\n> Untracked files:\n> (use \"git add ...\" to include in what will be committed)\n>\n> should be\n>\n> Untracked files:\n> (use \"git track \" to track)\n\nThis hypothetical \"git track\" actually exists under the name \"git add\n-N\".\n\n> The opposite of staging is `git\n> reset HEAD ` and the opposite of tracking is -- well, I’m not\n> sure, actually. Maybe `git update-index --force-remove `?\n\ngit rm --cached ?\n\nAs a bare mortal, you shouldn't need update-index, it's a plumbing\ncommand (i.e. meant for scripts or low-level manipulations).\n\n> An even more radical suggestion (which would take all of 20 seconds to\n> implement) is to introduce `git track` as another alias for `git\n> add`. (See above under `git status`). This would be especially useful\n> if tracking *branches* no longer existed.\n\nI disagree that adding aliases would help users. See your confusion,\nand then the relief when you found out that index, cache, and staging\narea were synonymous. Now, what should a user think after learning\nstage, track and add, and asking for the difference.\n\nI agree that adding new files and adding new content to existing files\nare done for different reasons, but the conceptual simplicity of Git\ncomes from the fact that Git is purely snapshot oriented, and I to\nsome extent, it's nice to have this reflected in the user-interface.\n\nWhen you say \"git add X\", you don't talk about the difference between\nthe previous commit and the next, or about the difference between\nworking tree and next commit, or so. You're basically saying \"file X\nwill exist in the next commit, and it will have this content\". Whether\nit existed or not in the previous commit doesn't matter. It's\nimplemented this way, and it's really something fundamental in the Git\nmodel.\n\n> There’s another issue with this, namely that “added files are\n> immediately staged”. In fact, I do understand why Git does that, but\n> conceptually it’s pure evil: one of the conceptual conrnerstones of\n> Git -- that files can be tracked and changed yet not staged,\n\nRephrase that as \"the working tree can have content different from the\nstaged content\". Both \"working tree content\" and \"staged content\" are\nsnapshot (i.e. they exist regardless of each other). Then newly\ncreated files won't be different anymore. Files exist, with some\n(possibly empty) content, or they don't.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"153752","messageId":"m3ocar5fmo.fsf@localhost.localdomain","threadId":"25473","inReplyTo":"8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-10-18T21:57:19Z","receivedAt":"2010-10-18T21:57:19Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Thore Husfeldt writes:\n\n> I’ve just learned Git. What a wonderful system, thanks for building\n> it. \n> \n> And what an annoying learning experience. \n> \n> I promised myself to try to remember what made it all so hard, and to\n> write it down in a comprehensive and possibly even constructive\n> fashion. Here it is, for what it’s worth. Read it as the friendly, but\n> somewhat exasparated suggestions of a newcomer. I’d love to help (in\n> the form of submitting patches to the documentation or CLI responses),\n> but I’d like to test the waters first.\n\nThank you very much for writing those down. It is very helpful for\nus, which are used to Git and know by heart its sometimes obscure\njargon, and might not notice that it is hard to understand.\n \n\n> Remote (tracking) branches\n> --------------------------\n> \n> There are at least two uses of the word *tracking* in Git's\n> terminology.\n> \n> The first, used in the form `git tracks a file' (in the sense that Git\n> knows about the file) is harmless enough, and is handled under `git\n> add` below.\n\nIn this sense of \"tracked\", i.e. \"tracked file\", it means that given\nfile is versioned / is under version control.\n\nThough I don't think we use `git tracks a file` anywhere in the\ndocumentation and messages (at least I hope so); we use `tracked file`.\nI think it is all right for `tracked file` and `\"tracked\" branch`\nto mean different things.\n\n\n> But the real monster is the *tracking branch*, sometimes called the\n> remote branch, the remote-tracking branch, or the remote tracking\n> branch. Boy did that ever confuse me. [...]\n> \n> Please, *please* fix this. It was the single most confusing and\n> annoying part of learning Git.\n> \n> First, the word, \"tracking\". These branches don’t track or follow\n> anything. They are standing completely still. Please believe me that\n> when first you are led to believe that origin/master tracks a branch\n> on the remote (like a hound tracks it quarry, or a radar tracks a\n> flight) that it is very difficult to hunt this misunderstanding down:\n> I believed for a long time that the tracking branch stayed in sync,\n> automagically, with a synonymous branch at the remote.\n\nBut those 'remote-tracking branches' are *used* to track where there\nare branches in remote repository.\n\nSidenote: give thanks that you didn't start to use git before version\n1.5.0, when so called \"separate remote\" layout was made default (which\nmeans tracking branch 'foo' in remote 'origin' using 'origin/foo'\nremote-tracking branch).\n\n[...]\n\n> The hyphenated *remote-tracking* is a lot better terminology already\n> (and sometimes even used in the documentation), because at least it\n> doesn't pretend to be a remote branch (`git branch -r`, of course,\n> still does). So that single hyphen already does some good, and should\n> be edited for consistency. [...]\n\nThe name 'remote-tracking branch' is the name we arrived at after long\ndiscussions not that long time ago, and it is a name that should be\nused thorough the documentation. It is ongoing effort.\n\n> [...] It may be that terminology is slowly converging. (To something\n> confusing, but still...)\n\n[...]\n\n> More radically, I am sure some head scratching would be able to find\n> useful terminology for master, origin/master, and origin’s master. I’d\n> love to see suggestions. As I said, I admire how wonderfully simple\n> and clean this has been implemented, and the documentation, CLI, and\n> terminology should reflect that.\n\nThere is also additional complication that you can have the same\nrelation that local branch 'master' has to 'origin/master'\nremote-tracking branch with two local branches.\n\nWe nowadays say that 'origin/master' is \"upstream\" for 'master'\nbranch; we used to say that 'master' branch \"tracks\" 'origin/master'\nbranch (which can be seen in the name of `--track' option to \n'git branch').\n \n> The staging area\n> ----------------\n> \n> The wonderful and central concept of staging area exists under at\n> least three names in Git terminology. And that’s really, really\n> annoying. The index, the cache, and the staging area are all the same,\n> which is a huge revelation to a newcomer.\n\nThis inconsistence is results of historical issues; the concrete\nobject that is used as mediator betweeb working area and repository\nwas first called 'dircache', and now is called 'the index'.\n\nThere was strong push towards replacing 'index' and 'cache' by\n'staging area' (and 'to stage' as verb), but it meets with some\nresistance.\n\n\n> 2. Introduce the alias `git unstage` for `git reset HEAD` in the\n> standard distribution.\n\nThat is IMHO a very good idea. The `git unstage ` form\ndescribes what we want to achieve (user story), while `git reset HEAD\n` requires us to know what operation must we do in order to\nremove staged changes from a file.\n \n> 3. Duplicate various occurences of `cached` flags as `staged` (and\n> change the documentation and man pages accordingly), so as to have,\n> e.g., `git diff --staged`.\n\nNote that it is not as easy as it seems at first glance. There are\n*two* such options, which (as you can read in gitcli(7) manpage) have\nslightly different meaning:\n\n * The `--cached` option is used to ask a command that\n usually works on files in the working tree to *only* work\n with the index. For example, `git grep`, when used\n without a commit to specify from which commit to look for\n strings in, usually works on files in the working tree,\n but with the `--cached` option, it looks for strings in\n the index.\n\n * The `--index` option is used to ask a command that\n usually works on files in the working tree to *also*\n affect the index. For example, `git stash apply` usually\n merges changes recorded in a stash to the working tree,\n but with the `--index` option, it also merges changes to\n the index as well.\n\nSome commands like `git apply` support both (though not at the same\ntime).\n\n\n> git status\n> ----------\n\n[...]\n> 2.\n> Untracked files:\n> (use \"git add ...\" to include in what will be committed)\n> \n> should be\n> \n> Untracked files:\n> (use \"git track \" to track)\n\nTo \"track a file\" means to put a file under version control (to\nversion control the file).\n\nNote also that \"git track \" would be \"git add -N \" \n(where `-N` is `--intent-to-add`), which only marks a file to be\ntracked / versioned, but doesn't stage its contents.\n \n> Adding\n> ------\n> \n> The tutorial tells us that \n> \n> Many revision control systems provide an add command that tells\n> the system to start tracking changes to a new file. Git's add\n> command does something simpler and more powerful: git add is used\n> both for new and newly modified files, and in both cases it takes\n> a snapshot of the given files and stages that content in the\n> index, ready for inclusion in the next commit.\n> \n> This is true, and once you grok how Git actually works it also makes\n> complete sense. `Making the file known to Git' (sometimes called\n> `tracking the file') and `staging for the next commit' result in the\n> exact same operations, from Git’s perspective.\n> \n> But this is a good example of what’s wrong with the way the\n> documentation thinks: Git’s implementation perspective should not\n> define how concepts are explained. In particular, *tracking* (in the\n> sense of making a file known to git) and *staging* are conceptually\n> different things.\n\nBut they are not independent. When you stage contents of a file which\nwas not known to git, it is automatically made \"tracked\" i.e. put\nunder version control. Obvious.\n\n> In fact, the two things remain conceptually\n> different later on: un-tracking (removing the file from Git’s\n> worldview) and un-staging are not the same thing at all, neither\n> conceptually nor implementationally. The opposite of staging is `git\n> reset HEAD ` and the opposite of tracking is -- well, I’m not\n> sure, actually. Maybe `git update-index --force-remove `?\n\n`git rm ` to remove it both from staging area, and working\narea, or `git rm --cached ` to remove it only from staging\narea, which means that it is removed from version control but kept on\ndisk.\n\n[...]\n\n> Fixing this requires no change to the implementation. `git stage` is\n> already a synonym for `git add`. It merely requires discipline in\n> using the terminology of staging. Note that it completely valid to\n> tell the reader, maybe immediately and in a footnote, that `git add`\n> and `git stage` *are* indeed synonyms, because of Git’s elegant\n> model. In fact, given the amount of documentation cruft one can find\n> on the Internet, this would be a welcome footnote.\n> \n> An even more radical suggestion (which would take all of 20 seconds to\n> implement) is to introduce `git track` as another alias for `git\n> add`. (See above under `git status`). This would be especially useful\n> if tracking *branches* no longer existed.\n\nWell, there is different suggestion: make `git stage`, `git track` and\n`git mark-resolved` to be *specializations* of `git add`, with added\nsafety checks: 'git stage' would work only on files known to git /\nunder version control already, 'git track' would work only on\nuntracked files (and do what 'git add -N' does), and 'git mark-resolved'\nwould work only on files which were part of a merge conflict.\n \n> There’s another issue with this, namely that “added files are\n> immediately staged”. In fact, I do understand why Git does that, but\n> conceptually it’s pure evil: one of the conceptual conrnerstones of\n> Git -- that files can be tracked and changed yet not staged, i.e., the\n> staging areas is conceptually a first-class citizen -- is violated\n> every time a new file is “born”. Newborn files are *special* until\n> their first commit, and that’s a shame, because the first thing the\n> new file (and, vicariously, the new user) experiences is an\n> aberration. I admit that I have not thought this through.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"153754","messageId":"20101018224840.GA9729@burratino","threadId":"25473","inReplyTo":"20101018211522.GA7655@burratino","subject":"[RFC/PATCH] reset: accept \"git reset \"","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-18T22:48:40Z","receivedAt":"2010-10-18T22:48:40Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Suppose I try to use \"git reset\" to un-add an new, unwanted file:\n\n\techo hello >foo.c\n\tgit add foo.c\n\trm foo.c; # bad file! bad!\n\tgit reset foo.c\n\nThe file foo.c does not exist on disk, so \"git reset\" rejects the\nrequest with\n\n\tfatal: ambiguous argument 'foo.c': unknown revision or path not in the working tree.\n\tUse '--' to separate paths from revisions\n\nGit can do better: since foo.c is not a revision and has an entry in\nthe index, it is clear the request refers to a path and not a rev.\n\nSigned-off-by: Jonathan Nieder \n---\nJonathan Nieder wrote:\n\n> Ah, this is a kind of obnoxious thing! For a newly added file,\n>\n> \tgit reset -- \n>\n> ought to un-add it, but it doesn't.\n\nErr, yes it does. Probably I was thinking of\n\n\trm \n\tgit reset \n\nproducing an \"ambiguous argument\" message.\n\n builtin/reset.c | 8 +++++++-\n t/t7102-reset.sh | 34 ++++++++++++++++++++++++++++++++--\n 2 files changed, 39 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/reset.c b/builtin/reset.c\nindex 0037be4..7d23d75 100644\n--- a/builtin/reset.c\n+++ b/builtin/reset.c\n@@ -295,7 +295,13 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\t\trev = argv[i++];\n \t\t} else {\n \t\t\t/* Otherwise we treat this as a filename */\n-\t\t\tverify_filename(prefix, argv[i]);\n+\t\t\tconst char *name = argv[i];\n+\t\t\tif (prefix)\n+\t\t\t\tname = prefix_filename(prefix, strlen(prefix), name);\n+\t\t\tif (read_cache() < 0)\n+\t\t\t\tdie(\"Could not read index\");\n+\t\t\tif (cache_name_pos(name, strlen(name)) < 0)\n+\t\t\t\tverify_filename(prefix, argv[i]);\n \t\t}\n \t}\n \ndiff --git a/t/t7102-reset.sh b/t/t7102-reset.sh\nindex b8cf260..69d125e 100755\n--- a/t/t7102-reset.sh\n+++ b/t/t7102-reset.sh\n@@ -5,7 +5,7 @@\n \n test_description='git reset\n \n-Documented tests for git reset'\n+Miscellaneous tests for git reset'\n \n . ./test-lib.sh\n \n@@ -441,6 +441,15 @@ test_expect_success 'disambiguation (1)' '\n \n '\n \n+test_expect_success \"disambiguation (1')\" '\n+\n+\tgit reset --hard &&\n+\tgit reset secondfile &&\n+\tgit diff --exit-code &&\n+\tgit diff --cached --exit-code\n+\n+'\n+\n test_expect_success 'disambiguation (2)' '\n \n \tgit reset --hard &&\n@@ -448,11 +457,18 @@ test_expect_success 'disambiguation (2)' '\n \tgit add secondfile &&\n \trm -f secondfile &&\n \ttest_must_fail git reset secondfile &&\n-\ttest -n \"$(git diff --cached --name-only -- secondfile)\" &&\n+\ttest -z \"$(git diff --cached --name-only)\" &&\n \ttest ! -f secondfile\n \n '\n \n+test_expect_success \"disambiguation (2')\" '\n+\n+\tgit reset --hard &&\n+\ttest_must_fail git reset doesnotexist\n+\n+'\n+\n test_expect_success 'disambiguation (3)' '\n \n \tgit reset --hard &&\n@@ -465,6 +481,13 @@ test_expect_success 'disambiguation (3)' '\n \n '\n \n+test_expect_success \"disambiguation (3')\" '\n+\n+\tgit reset --hard &&\n+\tgit reset HEAD doesnotexist\n+\n+'\n+\n test_expect_success 'disambiguation (4)' '\n \n \tgit reset --hard &&\n@@ -476,4 +499,11 @@ test_expect_success 'disambiguation (4)' '\n \ttest ! -f secondfile\n '\n \n+test_expect_success \"disambiguation (4')\" '\n+\n+\tgit reset --hard &&\n+\tgit reset -- doesnotexist\n+\n+'\n+\n test_done\n-- \n1.7.2.3\n"},{"id":"153757","messageId":"7viq0z2gxj.fsf@alter.siamese.dyndns.org","threadId":"25473","inReplyTo":"20101018224840.GA9729@burratino","subject":"Re: [RFC/PATCH] reset: accept \"git reset \"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-18T23:56:56Z","receivedAt":"2010-10-18T23:56:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Suppose I try to use \"git reset\" to un-add an new, unwanted file:\n>\n> \techo hello >foo.c\n> \tgit add foo.c\n> \trm foo.c; # bad file! bad!\n> \tgit reset foo.c\n>\n> The file foo.c does not exist on disk, so \"git reset\" rejects the\n> request with\n>\n> \tfatal: ambiguous argument 'foo.c': unknown revision or path not in the working tree.\n> \tUse '--' to separate paths from revisions\n>\n> Git can do better: since foo.c is not a revision and has an entry in\n> the index, it is clear the request refers to a path and not a rev.\n>\n> Signed-off-by: Jonathan Nieder \n> ---\n\nThis changes the definition of path/rev disambiguation only for \"reset\"\nand makes things inconsistent. Is it a good thing?\n\nIf a token is not a filename in the working tree, but is a path in the\nindex, and at the same time is a valid ref, wouldn't it make the token\nambiguous with the updated definition of disambiguation code here?\n\n> diff --git a/builtin/reset.c b/builtin/reset.c\n> index 0037be4..7d23d75 100644\n> --- a/builtin/reset.c\n> +++ b/builtin/reset.c\n> @@ -295,7 +295,13 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n> \t\t\trev = argv[i++];\n> \t\t} else {\n> \t\t\t/* Otherwise we treat this as a filename */\n> -\t\t\tverify_filename(prefix, argv[i]);\n> +\t\t\tconst char *name = argv[i];\n> +\t\t\tif (prefix)\n> +\t\t\t\tname = prefix_filename(prefix, strlen(prefix), name);\n> +\t\t\tif (read_cache() < 0)\n> +\t\t\t\tdie(\"Could not read index\");\n> +\t\t\tif (cache_name_pos(name, strlen(name)) < 0)\n> +\t\t\t\tverify_filename(prefix, argv[i]);\n> \t\t}\n> \t}\n\nMakes me wonder\n\n - if we can/want to have a logic like this inside verify_filename();\n\n - if we need a corresponding logic in either the previous else/if cascade\n that calls verify_non_filename(), or in verify_non_filename() itself.\n"},{"id":"153758","messageId":"7vaamb2gm6.fsf@alter.siamese.dyndns.org","threadId":"25473","inReplyTo":"AANLkTimkovH9OysLSxA+=di89Xi+dTCYL5hRPmNaADDH@mail.gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-19T00:03:45Z","receivedAt":"2010-10-19T00:03:45Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sverre Rabbelier writes:\n\n>> More radically, I am sure some head scratching would be able to find\n>> useful terminology for master, origin/master, and origin’s master. I’d\n>> love to see suggestions. As I said, I admire how wonderfully simple\n>> and clean this has been implemented, and the documentation, CLI, and\n>> terminology should reflect that.\n>\n> I don't have any objections to changing these terms, but I don't have\n> any suggestions on what to change them _to_.\n\nI do not think debating on changing the terminology is a particularly\nproductive use of our time. Just like Thore was confused by \"index,\ncache, add, stage\", we would end up adding yet another lingo that cover\nthe same concept, and the problem is that there is _no way_ older words\nwill be forgotten.\n\nBut I think the way the concepts are explained and taught by our\ndocumentation can and should be improved. For example, as I've written\nbefore we use 'tracking' for two quite different purposes, which is a\nmistake and the source confusion.\n\n - A \"remote-tracking branch\" is \"a _thing_ whose purpose is to be used to\n track a branch on the remote side\", and \"fetch\" is how you update it.\n\n - Sometimes people call a local branch whose purpose is to be used to\n build on efforts made on a branch on a remote repository as \"tracking\",\n which is quite incompatible with the above one.\n"},{"id":"153759","messageId":"20101019002349.GB9841@burratino","threadId":"25473","inReplyTo":"7viq0z2gxj.fsf@alter.siamese.dyndns.org","subject":"Re: [RFC/PATCH] reset: accept \"git reset \"","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T00:23:49Z","receivedAt":"2010-10-19T00:23:49Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> Makes me wonder\n>\n> - if we can/want to have a logic like this inside verify_filename();\n\nYes, I think so. I was worried that this would be confusing for some\ncommand that looks to the worktree, like git grep without --cached,\nbut I suspect that worry was unfounded.\n\nThe one case I am worried about is \"git rev-parse\". What is\n\"git rev-parse \" supposed to be used for?\n\n> - if we need a corresponding logic in either the previous else/if cascade\n> that calls verify_non_filename(), or in verify_non_filename() itself.\n\nYes.\n\nIs it safe to load the index so early? I can imagine a person trying\n\"git reset\" to recover from a corrupted index; are we regressing in\nthat respect and how would one check for it?\n"},{"id":"153763","messageId":"buopqv6kcsd.fsf@dhlpc061.dev.necel.com","threadId":"25473","inReplyTo":"vpq8w1v5gce.fsf@bauges.imag.fr","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Miles Bader","fromEmail":"miles@gnu.org","sentAt":"2010-10-19T04:49:06Z","receivedAt":"2010-10-19T04:49:06Z","isPatch":false,"sender":{"key":"miles@gnu.org","avatar":"https://gravatar.com/avatar/01069b69593af7bff28e2f97afeb3644ae6fe2f5f56cb3a8cf34c5fb8c36efe5?d=mp&s=160"},"body":"Matthieu Moy writes:\n> We already came up with a better wording, namely \"upstream\", and used\n> in in \"git push --set-upstream\". Probably a next step would be to\n> deprecate any other occurence of --track meaning the same thing\n\nThat doesn't make much sense to me; \"upstream\" and \"track\" are not\nalternatives; rather, they're complementary: \"upstream\" is a _thing_,\nand \"track\" is an _action_ -- one _tracks_ _upstream_. \"--track\", then,\nmerely implies \"upstream\", which seems fine to me, as I'm not sure\nthere's anything else it could refer to.\n\nI think the original post, while well-meaning is a bit overwrought, and\nreflects the difficulty in learning any new system as much as it does\nany inconsistency in git's terminology[*] -- Git's huge sin, after all\n(judging from most complaints I see about it), is that It Doesn't Use\nExactly The Same Model (and thus Terminology) That CVS Did...\n\n[SVN's great sin, of course, is that It Does (interpret \"CVS\" liberally\nhere).]\n\n[*] Git is certainly guilty of using inconsistent terminology --\ncached/staged/index/yada is my personal complaint -- but I don't think\nto anywhere near the degree implied by that post.\n\n-Miles\n\n-- \nDo not taunt Happy Fun Ball.\n"},{"id":"153773","messageId":"8B950268-7F6E-40E5-9D6C-F150EBEA4F0C@wincent.com","threadId":"25473","inReplyTo":"buopqv6kcsd.fsf@dhlpc061.dev.necel.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2010-10-19T07:19:12Z","receivedAt":"2010-10-19T07:19:12Z","isPatch":false,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 19/10/2010, a las 06:49, Miles Bader escribió:\n\n> I think the original post, while well-meaning is a bit overwrought, and\n> reflects the difficulty in learning any new system as much as it does\n> any inconsistency in git's terminology[*] -- Git's huge sin, after all\n> (judging from most complaints I see about it), is that It Doesn't Use\n> Exactly The Same Model (and thus Terminology) That CVS Did...\n\nI don't think it's overwrought at all. It's just pointing out a couple of obvious road-bumps in the learning curve.\n\nWe should smooth out these road-bumps (in so far as we can, with respect to backward compatibility and such) rather than just hand-waving them away saying that they are a natural consequence of demolishing the CVS world view and replacing it with something better. That's not true at all; mistakes _were_ made with the terminology, and unfortunately we have to live with some of them because they can't be changed in a non-breaking way, but the changes that we _can_ make to remove the confusion, we should make them.\n\nCheers,\nWincent\n"},{"id":"153771","messageId":"AANLkTinb0149C88Mzx6m4_2BdhpW12OwQ+uP6XzQ5yLx@mail.gmail.com","threadId":"25473","inReplyTo":"8B950268-7F6E-40E5-9D6C-F150EBEA4F0C@wincent.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Miles Bader","fromEmail":"miles@gnu.org","sentAt":"2010-10-19T07:48:39Z","receivedAt":"2010-10-19T07:48:39Z","isPatch":false,"sender":{"key":"miles@gnu.org","avatar":"https://gravatar.com/avatar/01069b69593af7bff28e2f97afeb3644ae6fe2f5f56cb3a8cf34c5fb8c36efe5?d=mp&s=160"},"body":"On Tue, Oct 19, 2010 at 4:19 PM, Wincent Colaiuta wrote:\n> We should smooth out these road-bumps (in so far as we can, with respect to backward compatibility and such) rather than just hand-waving them away saying that they are a natural consequence of demolishing the CVS world view and replacing it with something better. That's not true at all; mistakes _were_ made with the terminology, and unfortunately we have to live with some of them because they can't be changed in a non-breaking way, but the changes that we _can_ make to remove the confusion, we should make them.\n\nSure, I'm not claiming that git's perfect or can't be improved. [As I\nnoted, I have my own list of complaints about its terminology.]\n\nHowever, just as it's wrong to ignore all complaints for such reasons,\nit's _equally_ wrong to assume the opposite and think that all such\ncomplaints are justified. Some differences in terminology _are_ due\nto a very different model, and can't simply be papered over. It isn't\n\"hand-waving\" to point this out. They might (and should) be better\ndocumented/explained, but there are definitely terms and concepts\nwhere the only reasonable solution is for newbies to have some\npatience and take some time to learn them.\n\nMy impression of the original post was that it contained a little of both.\n\n-Miles\n\n-- \nCat is power.  Cat is peace.\n"},{"id":"153775","messageId":"6FCE62E3-A27E-43D6-9FDF-0133ABD851C2@wincent.com","threadId":"25473","inReplyTo":"AANLkTinb0149C88Mzx6m4_2BdhpW12OwQ+uP6XzQ5yLx@mail.gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2010-10-19T08:05:05Z","receivedAt":"2010-10-19T08:05:05Z","isPatch":false,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 19/10/2010, a las 09:48, Miles Bader escribió:\n\n> On Tue, Oct 19, 2010 at 4:19 PM, Wincent Colaiuta wrote:\n>> We should smooth out these road-bumps (in so far as we can, with respect to backward compatibility and such) rather than just hand-waving them away saying that they are a natural consequence of demolishing the CVS world view and replacing it with something better. That's not true at all; mistakes _were_ made with the terminology, and unfortunately we have to live with some of them because they can't be changed in a non-breaking way, but the changes that we _can_ make to remove the confusion, we should make them.\n> \n> Sure, I'm not claiming that git's perfect or can't be improved. [As I\n> noted, I have my own list of complaints about its terminology.]\n> \n> However, just as it's wrong to ignore all complaints for such reasons,\n> it's _equally_ wrong to assume the opposite and think that all such\n> complaints are justified. Some differences in terminology _are_ due\n> to a very different model, and can't simply be papered over. It isn't\n> \"hand-waving\" to point this out. They might (and should) be better\n> documented/explained, but there are definitely terms and concepts\n> where the only reasonable solution is for newbies to have some\n> patience and take some time to learn them.\n\nWell, I'm not \"assuming\" that the complaints are justified; I'm talking from 3.5 years of personal experience using Git:\n\n- the concept of the \"index\": learnt it in 30 seconds, and sick of hearing people complain about it\n\n- terminology related to concepts of \"tracking\"/\"remote(s)\": discomfort almost every time I've had to deal with it\n\ngitglossary(7) helps, but no matter how good it is you'll still get confusion unless the terminology is used consistently across the board. Some of this is not actually Git's fault, as a lot of the misuse/abuse of terminology actually comes from people writing blog posts and presentations and not being disciplined about their use of language -- before you know it Google returns mostly garbage results and \"the community\" ends up speaking a corrupted version of the language -- but the stuff that is within the scope of the Git project itself (man pages, official docs, interfaces) really needs to be top notch.\n\nCheers,\nWincent\n"},{"id":"153772","messageId":"20101019080523.GB22067@login.drsnuggles.stderr.nl","threadId":"25473","inReplyTo":"m3ocar5fmo.fsf@localhost.localdomain","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Matthijs Kooijman","fromEmail":"matthijs@stdin.nl","sentAt":"2010-10-19T08:05:23Z","receivedAt":"2010-10-19T08:05:23Z","isPatch":false,"sender":{"key":"matthijs@stdin.nl","avatar":"https://avatars.githubusercontent.com/u/194491?v=4"},"body":"> * The `--cached` option is used to ask a command that\n> usually works on files in the working tree to *only* work\n> with the index. For example, `git grep`, when used\n> without a commit to specify from which commit to look for\n> strings in, usually works on files in the working tree,\n> but with the `--cached` option, it looks for strings in\n> the index.\n> \n> * The `--index` option is used to ask a command that\n> usually works on files in the working tree to *also*\n> affect the index. For example, `git stash apply` usually\n> merges changes recorded in a stash to the working tree,\n> but with the `--index` option, it also merges changes to\n> the index as well.\n\nDoesn't this just offer opportunity for two new options? E.g., --staged\nand --also-staged or --include-staged or something? In the current form,\nthese two options provide a variation of the same concept, using\ncompletely different option names (which could lead people to think\nthat they're really the same option, just inconsistently implemented).\n\nSo, regardless of changing over to --staged, I guess these two options\ncould be made more consistent (though sticking to the \"index\"\nterminology is tricky, since that would require --cached to be become\n--index and --index to become --include--index, which throws away\nbackward compatibility...).\n\nFWIW, I do rather like the \"staging area\" concept, since I feel it\naccurately describes its use (or at least the most common use of the\nstaging area).\n\nGr.\n\nMatthijs\n"},{"id":"153774","messageId":"201010191027.44859.jnareb@gmail.com","threadId":"25473","inReplyTo":"20101019080523.GB22067@login.drsnuggles.stderr.nl","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-10-19T08:27:44Z","receivedAt":"2010-10-19T08:27:44Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Tue, 19 Oct 2010, Matthijs Kooijman wrote:\n\nNote that the excerpt cited (quoted) below is directly from gitcli(7)\nmanpage.\n\n> > * The `--cached` option is used to ask a command that\n> > usually works on files in the working tree to *only* work\n> > with the index. For example, `git grep`, when used\n> > without a commit to specify from which commit to look for\n> > strings in, usually works on files in the working tree,\n> > but with the `--cached` option, it looks for strings in\n> > the index.\n\nMnemonic: operate on _cached_ contents. We could use `--staged`\ninstead of `--cached` here, but for me it doesn't as strong as\n`--cached` this meaning.\n\n> > \n> > * The `--index` option is used to ask a command that\n> > usually works on files in the working tree to *also*\n> > affect the index. For example, `git stash apply` usually\n> > merges changes recorded in a stash to the working tree,\n> > but with the `--index` option, it also merges changes to\n> > the index as well.\n\nMnemonic: include _index_ (the name for concrete implementation of the\nstaging area) in operation. We could use `--stage` here, but it would\nbe confusingly similar to `--staged`. We could use `--include-staged`\nor `--also-staged`, but it is long and unwieldy, and doesn't read as\nnice.\n\n> \n> Doesn't this just offer opportunity for two new options? E.g., --staged\n> and --also-staged or --include-staged or something? In the current form,\n> these two options provide a variation of the same concept, using\n> completely different option names (which could lead people to think\n> that they're really the same option, just inconsistently implemented).\n\nThat's why documentation is for. That is why we have gitcli(7).\n\nSidenote: there were some proposal of including pseudo-ref name for\ncache/index/staging area (and for workdir contents), i.e. to use for\nexample INDEX or STAGE instead of `--cached`... but they fell flat\nbecause `--cached` / STAGE is not exactly like the ref, and it felt\nlike it would contribute to confusion rather than reducing it.\n\n> \n> So, regardless of changing over to --staged, I guess these two options\n> could be made more consistent (though sticking to the \"index\"\n> terminology is tricky, since that would require --cached to be become\n> --index and --index to become --include-index, which throws away\n> backward compatibility...).\n\nBreaking backward compatibility that badly is a big NO.\n\nUnfortunately the need for backward compatibility prevents us from some\nof improvements...\n\n> \n> FWIW, I do rather like the \"staging area\" concept, since I feel it\n> accurately describes its use (or at least the most common use of the\n> staging area).\n\nI also like \"staging area\" concept (and \"to stage\" as a verb), but there\nare some difficulties in applying it thorough and through.\n\n-- \nJakub Narebski\nPoland\n"},{"id":"153791","messageId":"1287499168-26569-1-git-send-email-artagnon@gmail.com","threadId":"25473","inReplyTo":"8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com","subject":"[PATCH v3] Porcelain scripts: Rewrite cryptic \"needs update\" error message","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-10-19T14:39:28Z","receivedAt":"2010-10-19T14:39:28Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Although Git interally has the facility to differentiate between\nporcelain and plubmbing commands and appropriately print errors,\nseveral shell scripts invoke plubming commands triggering cryptic\nplumbing errors to be displayed on a porcelain interface. This patch\nreplaces the \"needs update\" message in git-pull and git-rebase, when\n`git update-index` is run, with a more friendly message.\n\nReported-by: Joshua Jensen \nReported-by: Thore Husfeldt \nSigned-off-by: Ramkumar Ramachandra \n---\n Ref: <1285877017-8060-1-git-send-email-artagnon@gmail.com> for v2.\n Ref: <1285514516-5112-1-git-send-email-artagnon@gmail.com> for v1.\n\n Thanks to Matthieu for reviewing v1 and Junio for reviewing v2: I've\n tried to attack the problem more conservatively in this patch. It\n doesn't list paths, and doesn't print \"generic\" advice.\n\n git-pull.sh | 5 +----\n git-rebase--interactive.sh | 14 +++-----------\n git-rebase.sh | 14 +-------------\n git-sh-setup.sh | 29 +++++++++++++++++++++++++++++\n 4 files changed, 34 insertions(+), 28 deletions(-)\n\ndiff --git a/git-pull.sh b/git-pull.sh\nindex 8eb74d4..20a3bbe 100755\n--- a/git-pull.sh\n+++ b/git-pull.sh\n@@ -201,10 +201,7 @@ test true = \"$rebase\" && {\n \t\t\tdie \"updating an unborn branch with changes added to the index\"\n \t\tfi\n \telse\n-\t\tgit update-index --ignore-submodules --refresh &&\n-\t\tgit diff-files --ignore-submodules --quiet &&\n-\t\tgit diff-index --ignore-submodules --cached --quiet HEAD -- ||\n-\t\tdie \"refusing to pull with rebase: your working tree is not up-to-date\"\n+\t\trequire_clean_work_tree \"pull with rebase\" \"Please commit or stash them.\"\n \tfi\n \toldremoteref= &&\n \t. git-parse-remote &&\ndiff --git a/git-rebase--interactive.sh b/git-rebase--interactive.sh\nindex a27952d..4d8a2a0 100755\n--- a/git-rebase--interactive.sh\n+++ b/git-rebase--interactive.sh\n@@ -153,14 +153,6 @@ run_pre_rebase_hook () {\n \tfi\n }\n \n-require_clean_work_tree () {\n-\t# test if working tree is dirty\n-\tgit rev-parse --verify HEAD > /dev/null &&\n-\tgit update-index --ignore-submodules --refresh &&\n-\tgit diff-files --quiet --ignore-submodules &&\n-\tgit diff-index --cached --quiet HEAD --ignore-submodules -- ||\n-\tdie \"Working tree is dirty\"\n-}\n \n ORIG_REFLOG_ACTION=\"$GIT_REFLOG_ACTION\"\n \n@@ -557,7 +549,7 @@ do_next () {\n \t\t\texit \"$status\"\n \t\tfi\n \t\t# Run in subshell because require_clean_work_tree can die.\n-\t\tif ! (require_clean_work_tree)\n+\t\tif ! (require_clean_work_tree \"rebase\")\n \t\tthen\n \t\t\twarn \"Commit or stash your changes, and then run\"\n \t\t\twarn\n@@ -768,7 +760,7 @@ first and then run 'git rebase --continue' again.\"\n \n \t\trecord_in_rewritten \"$(cat \"$DOTEST\"/stopped-sha)\"\n \n-\t\trequire_clean_work_tree\n+\t\trequire_clean_work_tree \"rebase\"\n \t\tdo_rest\n \t\t;;\n \t--abort)\n@@ -866,7 +858,7 @@ first and then run 'git rebase --continue' again.\"\n \n \t\tcomment_for_reflog start\n \n-\t\trequire_clean_work_tree\n+\t\trequire_clean_work_tree \"rebase\" \"Please commit or stash them.\"\n \n \t\tif test ! -z \"$1\"\n \t\tthen\ndiff --git a/git-rebase.sh b/git-rebase.sh\nindex e5df23b..988b3d8 100755\n--- a/git-rebase.sh\n+++ b/git-rebase.sh\n@@ -416,19 +416,7 @@ else\n \tfi\n fi\n \n-# The tree must be really really clean.\n-if ! git update-index --ignore-submodules --refresh > /dev/null; then\n-\techo >&2 \"cannot rebase: you have unstaged changes\"\n-\tgit diff-files --name-status -r --ignore-submodules -- >&2\n-\texit 1\n-fi\n-diff=$(git diff-index --cached --name-status -r --ignore-submodules HEAD --)\n-case \"$diff\" in\n-?*)\techo >&2 \"cannot rebase: your index contains uncommitted changes\"\n-\techo >&2 \"$diff\"\n-\texit 1\n-\t;;\n-esac\n+require_clean_work_tree \"rebase\" \"Please commit or stash them.\"\n \n if test -z \"$rebase_root\"\n then\ndiff --git a/git-sh-setup.sh b/git-sh-setup.sh\nindex ae031a1..aa16b83 100644\n--- a/git-sh-setup.sh\n+++ b/git-sh-setup.sh\n@@ -145,6 +145,35 @@ require_work_tree () {\n \tdie \"fatal: $0 cannot be used without a working tree.\"\n }\n \n+require_clean_work_tree () {\n+\tgit rev-parse --verify HEAD >/dev/null || exit 1\n+\tgit update-index -q --ignore-submodules --refresh\n+\terr=0\n+\n+\tif ! git diff-files --quiet --ignore-submodules\n+\tthen\n+\t\techo >&2 \"Cannot $1: You have unstaged changes.\"\n+\t\terr=1\n+\tfi\n+\n+\tif ! git diff-index --cached --quiet --ignore-submodules HEAD --\n+\tthen\n+\t\tif [ $err = 0 ]\n+\t\tthen\n+\t\t echo >&2 \"Cannot $1: Your index contains uncommitted changes.\"\n+\t\telse\n+\t\t echo >&2 \"Additionally, your index contains uncommitted changes.\"\n+\t\tfi\n+\t\terr=1\n+\tfi\n+\n+\tif [ $err = 1 ]\n+\tthen\n+\t\ttest -n \"$2\" && echo >&2 \"$2\"\n+\t\texit 1\n+\tfi\n+}\n+\n get_author_ident_from_commit () {\n \tpick_author_script='\n \t/^author /{\n-- \n1.7.2.2.409.gdbb11.dirty\n"},{"id":"153793","messageId":"AANLkTinGuVm8gib9r7omVV9hHw8B-iBQGgsv+b6wb5=Q@mail.gmail.com","threadId":"25473","inReplyTo":"6FCE62E3-A27E-43D6-9FDF-0133ABD851C2@wincent.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Eugene Sajine","fromEmail":"euguess@gmail.com","sentAt":"2010-10-19T15:09:44Z","receivedAt":"2010-10-19T15:09:44Z","isPatch":false,"sender":{"key":"euguess@gmail.com","avatar":null},"body":"> Well, I'm not \"assuming\" that the complaints are justified; I'm talking from 3.5 years of personal experience using Git:\n>\n> - the concept of the \"index\": learnt it in 30 seconds, and sick of hearing people complain about it\n>\n> - terminology related to concepts of \"tracking\"/\"remote(s)\": discomfort almost every time I've had to deal with it\n>\n\nI concur. I 'm working with a couple of dozen of people and helping\nthem to learn git and the most confusing part is the tracking/remote\nbecause of too many meanings of the same words in use.\n\nWe are talking about the tracking branch which is \"local remote\", but\nwe also can create a tracking branch that will track the remote but\nwill be local like:\n$git branch -t dev origin/dev\n\nThere should be some different consistent and not inter-crossing\nnaming for the origin's master branch (on the remote side), for the\nlocal origin/master\nand for local master that is a tracking branch. The only way i found\nso far to explain this is actually via the naming syntax where having\n/ in the name of the branch means remote branch. I was a bit surprised\nthat i can create a local branch with a slash in the name - probably\nit should be prohibited.\n\nIn this light pull command not updating the remote ref, but FETCH_HEAD\nis only adding to the overall confusion (I remember: it is pending\nchange)\n\nThanks,\nEugene\n"},{"id":"153799","messageId":"202EB46D-10D0-4090-A9DA-5796769F61A2@gmail.com","threadId":"25473","inReplyTo":"201010191027.44859.jnareb@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Thore Husfeldt","fromEmail":"thore.husfeldt@gmail.com","sentAt":"2010-10-19T17:30:24Z","receivedAt":"2010-10-19T17:30:24Z","isPatch":false,"sender":{"key":"thore.husfeldt@gmail.com","avatar":"https://gravatar.com/avatar/d09b67dd2db2b4213ff54d74d8db9d0dd2830a92b60bea8828ce3132cdf8b853?d=mp&s=160"},"body":"Thank you all for your many and well-thought out replies. I learned a lot.\n\nJonathan Nieder:\n\n> So what would be a better term [for tracking]?\n\nTrailing is better than tracking, since it hints at some degree of sloth, but I have not thought this through. (I also think that it may be a strategic mistake to advocate looking for a new name; as long as tracking is used consistently the problem with a misleading metaphor is not so big, and the name change alienates a large group of people whose consent is important.)\n\n> How will a person used to e.g. cvs ever adjust if they don't even realize git is different?\n\nThis comment, and similar from others, makes it clear that I made a mistake in taking up staging versus tracking. It sends a wrong signal about my intentions, and is only a minor detail. This was *not* so difficult to understand, so I shouldn’t have included it. My annoyance here is merely aesthetic and pedagogical.\n\nMatthiey Moy:\n\n> Git's huge sin, after all (judging from most complaints I see about it), is that It Doesn't Use Exactly The Same Model (and thus Terminology) That CVS Did...\n\n\nMy analysis of Git’s wickedness is interestingly different. Git has a clean and simple model that should be very easy to understand. Git’s rhetorical traditions prevent that understanding. Git is really, really hard to learn, no matter where you come from, but there is no inherent reason for that.\n\nThe steepness of the learning curve (rather than the divergence from other systems’s terminology) is the single biggest complaint against git, evidenced by my own anecdotal evidence from web surfing, and by the Git user survey. It should be viewed as Git’s biggest current problem by an order of magnitude. It makes me think twice and thrice before asking my colleagues to collaborate with me using Git; I will probably learn Mercurial and advocate using that instead—it’s almost as nice, and I don’t feel embarrassed advocating it. Using git for myself is great (now I understand it) but it is unclear if I should invest social capital to convince others to use it as well. \n\nThe magnitude of how bad this is, and the urgency with which this should be fixed, is clear to everybody—except, naturally, the denizens of this mailing list. Not out of malice or incompetence, but *because of* familiarity.\n\nSverre Rabbelier:\n\n\n> What do you mean with the last part (about `git branch -r`)? The fact\n> that 'refs/remotes' is not immutable?\n\nWell, consider for example the simple obfuscatory mastery of the following line in the user manual:\n\n> $ git branch -r\t\t\t# list all remote branches\n\n\nYes, I get it *now*. And I begin to feel the corruption spreading in my own brain already: I myself start to think of origin/master as a “remote branch”. Give me a few more weeks and I will be completely assimilated in the mindset.\n\n(Note to self: submit a patch about this before my assimilation is complete. I already fixed it and committed to my local branch.)\n\nMattiey again:\n\n> We already came up with a better wording, namely \"upstream\", and used in in \"git push --set-upstream\". \n\nOh, I didn’t know that. I was convinced that “upstream” was cruft from when git was chiefly a tool to help Linus maintain the Linux kernel. Let‘s see if I get this right:\n\nThe remote-tracking branch “origin/master” is *upstream* (the upstream?) of the local branch “master”, and *tracks* the remote origin’s branch “master”? (local) “master” is downstream of “origin/master”?\n\nThis would be useful. And @{u} is good. (Does it have an inverse?)\n\nI’m not sure I like the particular word, but that’s a minor complaint. \n\n( For completeness: A small terminological quibble is that upstream doesn’t verb well. A bigger conceptual quibble is that this decision is not workflow-neutral. It enforces git’s hierarchical linux-kernel development tradition, rather than embracing a truly distributed model where everybody is the same. When I think of distributed version control I like to think of Alice having a remote-tracking bob/master and Bob having a remote-tracking alice/master. Of course, it is still meaningful for Alice to say “the upstream of bobs_latest_crazy_ideas is bob/master”, and for Bob to say “the upstream of alices_inane_ramblings is alice/master”. But it introduces a notion of hierarchy that is inimical to the concept of distribution, and not workflow-neutral. )\n\nOf course, upstream could be called supercalifragilistic and I would still like it. Consistency is more important than having good metaphors. (But good metaphors would be better, all other things being equal.)\n\nJakup Narebski:\n\n> Note that it is not as easy as it seems at first glance. There are *two* such options, which (as you can read in gitcli(7) manpage) have slightly different meaning:\n\nWow. Thanks for pointing this out, I did not know that, and it explains a lot. I must say that to everybody else than a git developer, this state of affairs is a proof that something is wrong, rather than an obstruction for improvement.\n\n> I do not think debating on changing the terminology is a particularly productive use of our time. \n\nI agree in the sense that *how* the words are used is more important than *which* words are used, and I realise that I should not have put “terminology” in the headline, because that makes it about words, not *explanations* or terminological *discipline*. "},{"id":"153801","messageId":"7vk4le13z3.fsf@alter.siamese.dyndns.org","threadId":"25473","inReplyTo":"20101019002349.GB9841@burratino","subject":"Re: [RFC/PATCH] reset: accept \"git reset \"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-19T17:34:24Z","receivedAt":"2010-10-19T17:34:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Junio C Hamano wrote:\n>\n>> Makes me wonder\n>>\n>> - if we can/want to have a logic like this inside verify_filename();\n>\n> Yes, I think so. I was worried that this would be confusing for some\n> command that looks to the worktree, like git grep without --cached,\n> but I suspect that worry was unfounded.\n>\n> The one case I am worried about is \"git rev-parse\". What is\n> \"git rev-parse \" supposed to be used for?\n>\n>> - if we need a corresponding logic in either the previous else/if cascade\n>> that calls verify_non_filename(), or in verify_non_filename() itself.\n>\n> Yes.\n>\n> Is it safe to load the index so early? I can imagine a person trying\n> \"git reset\" to recover from a corrupted index; are we regressing in\n> that respect and how would one check for it?\n\nIt is generally unsafe, I am afraid, and that is one of the reasons why\nverify_filename() does not look in the index (the other one was \"it is\nmerely a safety measure based on heuristics to help users, and no point\nspending extra code nor cycles\", iow, deliberate laziness ;-)), making the\nproposal of this patch under discussion somewhat iffy.\n"},{"id":"153803","messageId":"20101019175103.GA28847@kytes","threadId":"25473","inReplyTo":"AANLkTimkovH9OysLSxA+=di89Xi+dTCYL5hRPmNaADDH@mail.gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-10-19T17:51:12Z","receivedAt":"2010-10-19T17:51:12Z","isPatch":false,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Sverre Rabbelier writes:\n> On Mon, Oct 18, 2010 at 15:45, Thore Husfeldt wrote:\n> > The hyphenated *remote-tracking* is a lot better terminology already\n> > (and sometimes even used in the documentation), because at least it\n> > doesn't pretend to be a remote branch (`git branch -r`, of course,\n> > still does).\n> \n> What do you mean with the last part (about `git branch -r`)? The fact\n> that 'refs/remotes' is not immutable?\n> \n> > So that single hyphen already does some good, and should\n> > be edited for consistency.\n> \n> If we agree that \"remote-tracking\" is the way to go, a patch doing\n> such editing would be very welcome.\n\n-- 8< --\nFrom a863e58d240956191c2fa9cbe992aaca5786730b Mon Sep 17 00:00:00 2001\nFrom: Ramkumar Ramachandra \nDate: Tue, 19 Oct 2010 22:42:05 +0530\nSubject: [PATCH] Documentation: Consistently use the hyphenated \"remote-tracking\"\n\nReplace instances of the term \"remote tracking\" with \"remote-tracking\"\nin the documentation for clarity.\n\nReported-by: Thore Husfeldt \nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/config.txt | 2 +-\n Documentation/fetch-options.txt | 2 +-\n Documentation/git-gc.txt | 2 +-\n Documentation/git-log.txt | 2 +-\n Documentation/git-pull.txt | 2 +-\n Documentation/git-remote.txt | 4 ++--\n Documentation/gittutorial.txt | 6 +++---\n Documentation/rev-list-options.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n 9 files changed, 12 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 71ddb6c..736b22f 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -708,7 +708,7 @@ color.diff.::\n color.decorate.::\n \tUse customized color for 'git log --decorate' output. `` is one\n \tof `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local\n-\tbranches, remote tracking branches, tags, stash and HEAD, respectively.\n+\tbranches, remote-tracking branches, tags, stash and HEAD, respectively.\n \n color.grep::\n \tWhen set to `always`, always highlight matches. When `false` (or\ndiff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\nindex 470ac31..a435c23 100644\n--- a/Documentation/fetch-options.txt\n+++ b/Documentation/fetch-options.txt\n@@ -36,7 +36,7 @@ ifndef::git-pull[]\n \n -p::\n --prune::\n-\tAfter fetching, remove any remote tracking branches which\n+\tAfter fetching, remove any remote-tracking branches which\n \tno longer exist\ton the remote.\n endif::git-pull[]\n \ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 315f07e..d6d6833 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -89,7 +89,7 @@ are not part of the current project most users will want to expire\n them sooner. This option defaults to '30 days'.\n \n The above two configuration variables can be given to a pattern. For\n-example, this sets non-default expiry values only to remote tracking\n+example, this sets non-default expiry values only to remote-tracking\n branches:\n \n ------------\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 6d40f00..ff41784 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -116,7 +116,7 @@ git log --follow builtin-rev-list.c::\n git log --branches --not --remotes=origin::\n \n \tShows all commits that are in any of local branches but not in\n-\tany of remote tracking branches for 'origin' (what you have that\n+\tany of remote-tracking branches for 'origin' (what you have that\n \torigin doesn't).\n \n git log master --not --remotes=*/master::\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex c50f7dc..33e8438 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -26,7 +26,7 @@ With `--rebase`, it runs 'git rebase' instead of 'git merge'.\n should be the name of a remote repository as\n passed to linkgit:git-fetch[1]. can name an\n arbitrary remote ref (for example, the name of a tag) or even\n-a collection of refs with corresponding remote tracking branches\n+a collection of refs with corresponding remote-tracking branches\n (e.g., refs/heads/*:refs/remotes/origin/*), but usually it is\n the name of a branch in the remote repository.\n \ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex aa021b0..3143c89 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -75,7 +75,7 @@ was passed.\n \n 'rename'::\n \n-Rename the remote named to . All remote tracking branches and\n+Rename the remote named to . All remote-tracking branches and\n configuration settings for the remote are updated.\n +\n In case and are the same, and is a file under\n@@ -84,7 +84,7 @@ the configuration file format.\n \n 'rm'::\n \n-Remove the remote named . All remote tracking branches and\n+Remove the remote named . All remote-tracking branches and\n configuration settings for the remote are removed.\n \n 'set-head'::\ndiff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt\nindex 1c16066..0982f74 100644\n--- a/Documentation/gittutorial.txt\n+++ b/Documentation/gittutorial.txt\n@@ -385,7 +385,7 @@ alice$ git fetch bob\n \n Unlike the longhand form, when Alice fetches from Bob using a\n remote repository shorthand set up with 'git remote', what was\n-fetched is stored in a remote tracking branch, in this case\n+fetched is stored in a remote-tracking branch, in this case\n `bob/master`. So after this:\n \n -------------------------------------\n@@ -402,8 +402,8 @@ could merge the changes into her master branch:\n alice$ git merge bob/master\n -------------------------------------\n \n-This `merge` can also be done by 'pulling from her own remote\n-tracking branch', like this:\n+This `merge` can also be done by 'pulling from her own remote-tracking\n+branch', like this:\n \n -------------------------------------\n alice$ git pull . remotes/bob/master\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex ebc0108..052e64f 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -264,7 +264,7 @@ endif::git-rev-list[]\n \n \tPretend as if all the refs in `refs/remotes` are listed\n \ton the command line as ''. If `pattern`is given, limit\n-\tremote tracking branches to ones matching given shell glob.\n+\tremote-tracking branches to ones matching given shell glob.\n \tIf pattern lacks '?', '*', or '[', '/*' at the end is implied.\n \n --glob=glob-pattern::\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 77eb483..cc65077 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1700,7 +1700,7 @@ may wish to check the original repository for updates and merge them\n into your own work.\n \n We have already seen <> with linkgit:git-fetch[1],\n+keep remote-tracking branches up to date>> with linkgit:git-fetch[1],\n and how to merge two branches. So you can merge in changes from the\n original repository's master branch with:\n \n-- \n1.7.2.2.409.gdbb11.dirty\n\n\n> > (Comment: maybe “... but working directory contains untracked files.”\n> > I realise that “directory” is not quite comprehensive here, because\n> > files can reside in subdirectories.\n> \n> We use \"worktree\" elsewhere, how about that?\n\n$ git grep \"worktree\" | wc -l\n281\n$ git grep \"working directory\" | wc -l\n246\n$ git grep \"working tree\" | wc -l\n449\n\nAdditionally, \"working directory\" also really refers to a (current)\nworking *directory* in many places.\n\nI like \"worktree\" too, but for consistency I've replaced the\ninconsistent usage of \"working directory\" in the UI with \"working\ntree\". No, I haven't updated the documentation because it's frankly\ntoo painful.\n\n-- 8< --\nFrom 7422c2af1ef40c922d8f628715ad96172e4a5734 Mon Sep 17 00:00:00 2001\nFrom: Ramkumar Ramachandra \nDate: Tue, 19 Oct 2010 23:16:04 +0530\nSubject: [PATCH] UI: Don't say \"working directory\" when we really mean \"working tree\"\n\nWhile in some places \"working directory\" is used to refer to the\n(current) working directory, it's incorrectly used in places where Git\nactually means \"working tree\" or worktree. Weed out and replace these\ninstances in the UI.\n\nReported-by: Thore Husfeldt \nSigned-off-by: Ramkumar Ramachandra \n---\n builtin/apply.c | 2 +-\n convert.c | 4 ++--\n git-filter-branch.sh | 2 +-\n git-stash.sh | 2 +-\n setup.c | 2 +-\n unpack-trees.c | 2 +-\n wt-status.c | 4 ++--\n 7 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/builtin/apply.c b/builtin/apply.c\nindex 23c18c5..9166320 100644\n--- a/builtin/apply.c\n+++ b/builtin/apply.c\n@@ -2934,7 +2934,7 @@ static int check_to_create_blob(const char *new_name, int ok_if_exists)\n \t\tif (has_symlink_leading_path(new_name, strlen(new_name)))\n \t\t\treturn 0;\n \n-\t\treturn error(\"%s: already exists in working directory\", new_name);\n+\t\treturn error(\"%s: already exists in working tree\", new_name);\n \t}\n \telse if ((errno != ENOENT) && (errno != ENOTDIR))\n \t\treturn error(\"%s: %s\", new_name, strerror(errno));\ndiff --git a/convert.c b/convert.c\nindex 01de9a8..441708e 100644\n--- a/convert.c\n+++ b/convert.c\n@@ -131,7 +131,7 @@ static void check_safe_crlf(const char *path, enum action action,\n \t\t */\n \t\tif (stats->crlf) {\n \t\t\tif (checksafe == SAFE_CRLF_WARN)\n-\t\t\t\twarning(\"CRLF will be replaced by LF in %s.\\nThe file will have its original line endings in your working directory.\", path);\n+\t\t\t\twarning(\"CRLF will be replaced by LF in %s.\\nThe file will have its original line endings in your working tree.\", path);\n \t\t\telse /* i.e. SAFE_CRLF_FAIL */\n \t\t\t\tdie(\"CRLF would be replaced by LF in %s.\", path);\n \t\t}\n@@ -142,7 +142,7 @@ static void check_safe_crlf(const char *path, enum action action,\n \t\t */\n \t\tif (stats->lf != stats->crlf) {\n \t\t\tif (checksafe == SAFE_CRLF_WARN)\n-\t\t\t\twarning(\"LF will be replaced by CRLF in %s.\\nThe file will have its original line endings in your working directory.\", path);\n+\t\t\t\twarning(\"LF will be replaced by CRLF in %s.\\nThe file will have its original line endings in your working tree.\", path);\n \t\t\telse /* i.e. SAFE_CRLF_FAIL */\n \t\t\t\tdie(\"LF would be replaced by CRLF in %s\", path);\n \t\t}\ndiff --git a/git-filter-branch.sh b/git-filter-branch.sh\nindex 962a93b..0ab5551 100755\n--- a/git-filter-branch.sh\n+++ b/git-filter-branch.sh\n@@ -110,7 +110,7 @@ OPTIONS_SPEC=\n if [ \"$(is_bare_repository)\" = false ]; then\n \tgit diff-files --ignore-submodules --quiet &&\n \tgit diff-index --cached --quiet HEAD -- ||\n-\tdie \"Cannot rewrite branch(es) with a dirty working directory.\"\n+\tdie \"Cannot rewrite branch(es) with a dirty working tree.\"\n fi\n \n tempdir=.git-rewrite\ndiff --git a/git-stash.sh b/git-stash.sh\nindex 7561b37..86cf24e 100755\n--- a/git-stash.sh\n+++ b/git-stash.sh\n@@ -179,7 +179,7 @@ save_stash () {\n \n \tgit update-ref -m \"$stash_msg\" $ref_stash $w_commit ||\n \t\tdie \"Cannot save the current status\"\n-\tsay Saved working directory and index state \"$stash_msg\"\n+\tsay Saved working tree and index state \"$stash_msg\"\n \n \tif test -z \"$patch_mode\"\n \tthen\ndiff --git a/setup.c b/setup.c\nindex a3b76de..55f8fe3 100644\n--- a/setup.c\n+++ b/setup.c\n@@ -611,7 +611,7 @@ const char *setup_git_directory(void)\n \t\t\tdie_errno (\"Could not jump back into original cwd\");\n \t\trel = get_relative_cwd(buffer, PATH_MAX, get_git_work_tree());\n \t\tif (rel && *rel && chdir(get_git_work_tree()))\n-\t\t\tdie_errno (\"Could not jump to working directory\");\n+\t\t\tdie_errno (\"Could not jump to working tree\");\n \t\treturn rel && *rel ? strcat(rel, \"/\") : NULL;\n \t}\n \ndiff --git a/unpack-trees.c b/unpack-trees.c\nindex 803445a..a70b57c 100644\n--- a/unpack-trees.c\n+++ b/unpack-trees.c\n@@ -934,7 +934,7 @@ int unpack_trees(unsigned len, struct tree_desc *t, struct unpack_trees_options\n \n \t\t}\n \t\tif (o->result.cache_nr && empty_worktree) {\n-\t\t\tret = unpack_failed(o, \"Sparse checkout leaves no entry on working directory\");\n+\t\t\tret = unpack_failed(o, \"Sparse checkout leaves no entry on working tree\");\n \t\t\tgoto done;\n \t\t}\n \t}\ndiff --git a/wt-status.c b/wt-status.c\nindex fc2438f..89831cb 100644\n--- a/wt-status.c\n+++ b/wt-status.c\n@@ -95,7 +95,7 @@ static void wt_status_print_dirty_header(struct wt_status *s,\n \t\tcolor_fprintf_ln(s->fp, c, \"# (use \\\"git add ...\\\" to update what will be committed)\");\n \telse\n \t\tcolor_fprintf_ln(s->fp, c, \"# (use \\\"git add/rm ...\\\" to update what will be committed)\");\n-\tcolor_fprintf_ln(s->fp, c, \"# (use \\\"git checkout -- ...\\\" to discard changes in working directory)\");\n+\tcolor_fprintf_ln(s->fp, c, \"# (use \\\"git checkout -- ...\\\" to discard changes in working tree)\");\n \tif (has_dirty_submodules)\n \t\tcolor_fprintf_ln(s->fp, c, \"# (commit or discard the untracked or modified content in submodules)\");\n \tcolor_fprintf_ln(s->fp, c, \"#\");\n@@ -690,7 +690,7 @@ void wt_status_print(struct wt_status *s)\n \t\t\t\t? \" (use -u to show untracked files)\" : \"\");\n \t\telse\n \t\t\tprintf(\"nothing to commit%s\\n\", advice_status_hints\n-\t\t\t\t? \" (working directory clean)\" : \"\");\n+\t\t\t\t? \" (working tree clean)\" : \"\");\n \t}\n }\n \n-- \n1.7.2.2.409.gdbb11.dirty\n\n\n> >    Changes to be committed:\n> >    (use \"git reset HEAD ...\" to unstage)\n> >\n> > should be\n> >\n> >    Staged to be committed:\n> >    (use \"git unstage \" to unstage)\n> \n> This would be extra nice since 'git unstage' could also be used in a\n> fresh repository.\n\n[`git unstage` patch still cooking]\n\nSverre: Thanks!\nThore: Thanks for the feedback. Please read\nDocumentation/SubmittingPatches and submit more patches.\n\n-- Ram\n"},{"id":"153806","messageId":"20101019182845.GE25139@burratino","threadId":"25473","inReplyTo":"20101019175103.GA28847@kytes","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T18:28:45Z","receivedAt":"2010-10-19T18:28:45Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n\n> -- \n> 1.7.2.2.409.gdbb11.dirty\n\nPlease, one patch per message in the future.\n\n> Sverre Rabbelier writes:\n>> On Mon, Oct 18, 2010 at 15:45, Thore Husfeldt wrote:\n\n>>>    (use \"git unstage \" to unstage)\n>>\n>> This would be extra nice since 'git unstage' could also be used in a\n>> fresh repository.\n\nMy vague unhappiness at \"git reset\" may have come from this.\n\nWouldn't it make sense to make \"git reset\" basically a synonym for\n\"git rm --cached\" when in the 'branch yet to be born' case?\n\nSigned-off-by: Jonathan Nieder \n---\ndiff --git a/builtin/reset.c b/builtin/reset.c\nindex 0037be4..cde103f 100644\n--- a/builtin/reset.c\n+++ b/builtin/reset.c\n@@ -236,6 +236,7 @@ static void die_if_unmerged_cache(int reset_type)\n int cmd_reset(int argc, const char **argv, const char *prefix)\n {\n \tint i = 0, reset_type = NONE, update_ref_status = 0, quiet = 0;\n+\tint unborn_branch = 0;\n \tint patch_mode = 0;\n \tconst char *rev = \"HEAD\";\n \tunsigned char sha1[20], *orig = NULL, sha1_orig[20],\n@@ -299,13 +300,27 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\t}\n \t}\n \n-\tif (get_sha1(rev, sha1))\n+\tif (!strcmp(rev, \"HEAD\")) {\n+\t\t/* We may be on a branch yet to be born. */\n+\t\tresolve_ref(\"HEAD\", sha1, 0, NULL);\n+\t\tif (is_null_sha1(sha1)) {\n+\t\t\tunborn_branch = 1;\n+\t\t\tcommit = NULL;\n+\t\t\thashcpy(sha1, (const unsigned char *) EMPTY_TREE_SHA1_BIN);\n+\n+\t\t\t/* Only accept \"git reset -- \" form, for now. */\n+\t\t\tif (i == argc || patch_mode)\n+\t\t\t\tdie(\"Failed to resolve 'HEAD' as a valid ref.\");\n+\t\t}\n+\t} else if (get_sha1(rev, sha1))\n \t\tdie(\"Failed to resolve '%s' as a valid ref.\", rev);\n \n-\tcommit = lookup_commit_reference(sha1);\n-\tif (!commit)\n-\t\tdie(\"Could not parse object '%s'.\", rev);\n-\thashcpy(sha1, commit->object.sha1);\n+\tif (!unborn_branch) {\n+\t\tcommit = lookup_commit_reference(sha1);\n+\t\tif (!commit)\n+\t\t\tdie(\"Could not parse object '%s'.\", rev);\n+\t\thashcpy(sha1, commit->object.sha1);\n+\t}\n \n \tif (patch_mode) {\n \t\tif (reset_type != NONE)\n"},{"id":"153807","messageId":"AANLkTi=DXH1WwGJ-h6s3dFfWZZ3tpu_jQgV1Y9O7c6Xf@mail.gmail.com","threadId":"25473","inReplyTo":"20101019182845.GE25139@burratino","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-10-19T18:34:56Z","receivedAt":"2010-10-19T18:34:56Z","isPatch":false,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Tue, Oct 19, 2010 at 13:28, Jonathan Nieder wrote:\n> Wouldn't it make sense to make \"git reset\" basically a synonym for\n> \"git rm --cached\" when in the 'branch yet to be born' case?\n\nYes, definitely!\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"153809","messageId":"0B20EFC4-E613-4D4A-B4F8-8B1750AA8AFD@gmail.com","threadId":"25473","inReplyTo":"AANLkTi=DXH1WwGJ-h6s3dFfWZZ3tpu_jQgV1Y9O7c6Xf@mail.gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Thore Husfeldt","fromEmail":"thore.husfeldt@gmail.com","sentAt":"2010-10-19T18:43:17Z","receivedAt":"2010-10-19T18:43:17Z","isPatch":false,"sender":{"key":"thore.husfeldt@gmail.com","avatar":"https://gravatar.com/avatar/d09b67dd2db2b4213ff54d74d8db9d0dd2830a92b60bea8828ce3132cdf8b853?d=mp&s=160"},"body":"Also, in the user-manual.txt:\n\n> Examining branches from a remote repository\n> -------------------------------------------\n> \n> The \"master\" branch that was created at the time you cloned is a copy\n> of the HEAD in the repository that you cloned from. That repository\n> may also have had other branches, though, and your local repository\n> keeps branches that track each of those remote branches, which you\n> can view using the \"-r\" option to linkgit:git-branch[1]:\n> \n> ------------------------------------------------\n> $ git branch -r\n> origin/HEAD\n> origin/html\n> origin/maint\n> origin/man\n> origin/master\n> origin/next\n> origin/pu\n> origin/todo\n> ------------------------------------------------\n> \n> You cannot check out these remote-tracking branches, but you can\n> examine them on a branch of your own, just as you would a tag:\n\nThat’s just wrong, isn’t it? You absolutely can check out a remote-tracking branch."},{"id":"153813","messageId":"20101019190416.GH25139@burratino","threadId":"25473","inReplyTo":"0B20EFC4-E613-4D4A-B4F8-8B1750AA8AFD@gmail.com","subject":"User manual: \"You cannot check out these remote-tracking branches\"","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T19:04:16Z","receivedAt":"2010-10-19T19:04:16Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thore Husfeldt wrote:\n\n> Also, in the user-manual.txt:\n[...]\n>> origin/todo\n>> ------------------------------------------------\n>> \n>> You cannot check out these remote-tracking branches, but you can\n>> examine them on a branch of your own, just as you would a tag:\n>\n> That’s just wrong, isn’t it?\n\nThat's historical baggage, I'm afraid.\n\nSigned-off-by: Jonathan Nieder \n---\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 77eb483..9f82fa6 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -359,13 +359,16 @@ $ git branch -r\n origin/todo\n ------------------------------------------------\n \n-You cannot check out these remote-tracking branches, but you can\n-examine them on a branch of your own, just as you would a tag:\n+You might want to build on one of these remote-tracking branches\n+on a branch of your own, just as you would a tag:\n \n ------------------------------------------------\n $ git checkout -b my-todo-copy origin/todo\n ------------------------------------------------\n \n+You can also check out \"origin/todo\" directly to examine it or\n+write a one-off patch. See <>.\n+\n Note that the name \"origin\" is just the name that git uses by default\n to refer to the repository that you cloned from.\n \n"},{"id":"153815","messageId":"alpine.LFD.2.00.1010191508370.2764@xanadu.home","threadId":"25473","inReplyTo":"0B20EFC4-E613-4D4A-B4F8-8B1750AA8AFD@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Nicolas Pitre","fromEmail":"nico@fluxnic.net","sentAt":"2010-10-19T19:15:15Z","receivedAt":"2010-10-19T19:15:15Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Tue, 19 Oct 2010, Thore Husfeldt wrote:\n\n> Also, in the user-manual.txt:\n> \n> > Examining branches from a remote repository\n> > -------------------------------------------\n> > \n> > The \"master\" branch that was created at the time you cloned is a copy\n> > of the HEAD in the repository that you cloned from. That repository\n> > may also have had other branches, though, and your local repository\n> > keeps branches that track each of those remote branches, which you\n> > can view using the \"-r\" option to linkgit:git-branch[1]:\n> > \n> > ------------------------------------------------\n> > $ git branch -r\n> > origin/HEAD\n> > origin/html\n> > origin/maint\n> > origin/man\n> > origin/master\n> > origin/next\n> > origin/pu\n> > origin/todo\n> > ------------------------------------------------\n> > \n> > You cannot check out these remote-tracking branches, but you can\n> > examine them on a branch of your own, just as you would a tag:\n> \n> That’s just wrong, isn’t it? You absolutely can check out a remote-tracking branch.--\n\nYes, the above is wrong. But to check out a remote-tracking branch, or \na tag, or a random commit through its SHA1, we do rely on the concept of \na \"detached head\". That term and concept has caused newbies grief in \nthe past as well, despite the fact that seasoned Git users are perfectly \nfine with it.\n\nA detached head is HEAD not being linked to any branch. This is done \nbecause tags and remote-tracking branches are not meant to be altered by \nlocal changes. Hence committing stuff on top of a detached head will \nadvance HEAD, but no actual branch is keeping a record of it.\n\n\nNicolas\n"},{"id":"153816","messageId":"7vhbgiyoo9.fsf@alter.siamese.dyndns.org","threadId":"25473","inReplyTo":"20101019182845.GE25139@burratino","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-19T19:20:54Z","receivedAt":"2010-10-19T19:20:54Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Wouldn't it make sense to make \"git reset\" basically a synonym for\n> \"git rm --cached\" when in the 'branch yet to be born' case?\n\nHmm,...\n\nWhile you are on 'master', shouldn't these behave identically?\n\n $ git reset master -- frotz.c\n $ git reset HEAD -- frotz.c\n $ git reset -- frotz.c\n\nwhile shouldn't this fail if there is no 'naster' branch?\n\n $ git reset naster -- frotz.c\n\nIt is probably Ok to limit the scope of this change to the case without\nany explicit rev, e.g. \"git reset -- frotz.c\", but at that point I somehow\ndon't think it will reduce confusion but rather will make things worse.\n\n> +\tif (!strcmp(rev, \"HEAD\")) {\n\nComparing the address of the \"HEAD\" used for initialization with rev may\nmake sure that the code will catch only \"no explicit rev\" case here, but\nthat is not what is happening here, which is even less consistent.\n"},{"id":"153821","messageId":"vpqy69trjkq.fsf@bauges.imag.fr","threadId":"25473","inReplyTo":"20101019190416.GH25139@burratino","subject":"Re: User manual: \"You cannot check out these remote-tracking branches\"","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-10-19T20:52:53Z","receivedAt":"2010-10-19T20:52:53Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jonathan Nieder writes:\n\n> -You cannot check out these remote-tracking branches, but you can\n> -examine them on a branch of your own, just as you would a tag:\n> +You might want to build on one of these remote-tracking branches\n> +on a branch of your own, just as you would a tag:\n\nShouldn't this be \"just as you would _for_ a tag\"?\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"153822","messageId":"m3k4ldlx56.fsf@localhost.localdomain","threadId":"25473","inReplyTo":"202EB46D-10D0-4090-A9DA-5796769F61A2@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-10-19T20:57:14Z","receivedAt":"2010-10-19T20:57:14Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Re-added (some of) CC list; at least all quoted authors are there.\n\nThore Husfeldt writes:\n\n> Thank you all for your many and well-thought out replies. I learned\n> a lot.\n> \n> Jonathan Nieder:\n> \n> JNi> So what would be a better term [for tracking]?\n> \n> Trailing is better than tracking, since it hints at some degree of\n> sloth, but I have not thought this through. (I also think that it\n> may be a strategic mistake to advocate looking for a new name; as\n> long as tracking is used consistently the problem with a misleading\n> metaphor is not so big, and the name change alienates a large group\n> of people whose consent is important.)\n\nIt is harder to use as adjective though, compare \"remote-tracking\n[branch]\" with \"remote-trailing [branch]\"... or is it just \"trailing\nbranch\"?\n\nBesides I don't think that 'remote-tracking' has to mean\n_automatically_ tracking; it is *used* to track.\n\n> Matthiey Moy:\n> \n> MM> Git's huge sin, after all (judging from most complaints I see\n> MM> about it), is that It Doesn't Use Exactly The Same Model (and\n> MM> thus Terminology) That CVS Did...\n> \n> \n> My analysis of Git’s wickedness is interestingly different. Git has\n> a clean and simple model that should be very easy to\n> understand.\n\nThe unfortunate consequence of this is that many git command and much\nof git documentation is based on this understanding. It would be\nbetter to have documentation centered around 'user stories', not\ntechicalities.\n\nFor example instead of `git unstage `, one has to use \n`git reset -- `; one has to understand how contents is moved\nbetween repository (commits), staging area (index / cache) and\nworktree to arrive at this command. Fortunately `git status`\nand the comments in commit message template help users there,\nbut it would be nice not to have to rely on this.\n\n> Git’s rhetorical traditions prevent that understanding. Git is\n> really, really hard to learn, no matter where you come from, but\n> there is no inherent reason for that.\n\nWell, there is a matter of debate how much of git complexity is\naccidental complexity which should be eliminated, and how much is\nessential complexity.\n\nFor example user-visible staging area[1], or git branching model[2]\ncan be confusing, at least to users coming from other version control\nsystems. Those concepts though are necessary to allow much of power\nof git. In the case of visible staging area dealing with conflicts\nduring merge and choosing piece-by-piece what is to be in next commit.\nIn the case of git branching model, it allows for interacting with\nmultiple multi-branch repositories without worrying about single\nglobal namespace for branch names.\n\n\n[1] Other version control systems have at least a shadow of it,\n because they need to know which files are to be versioned\n (tracked).\n\n[2] I mean here the difference between refs/heads/* and\n refs/remotes//* refs, and mapping between tracked branches\n in remote repository and remote-tracking branches in given\n repository.\n \n> The steepness of the learning curve (rather than the divergence from\n> other systems’s terminology) is the single biggest complaint against\n> git, evidenced by my own anecdotal evidence from web surfing, and by\n> the Git user survey. It should be viewed as Git’s biggest current\n> problem by an order of magnitude. It makes me think twice and thrice\n> before asking my colleagues to collaborate with me using Git; I will\n> probably learn Mercurial and advocate using that instead; it’s\n> almost as nice, and I don’t feel embarrassed advocating it. Using\n> git for myself is great (now I understand it) but it is unclear if I\n> should invest social capital to convince others to use it as well.\n\nI guess that some of _perceived_ ease of use of Mercurial was\ngenerated by the fast that (at least in the past) it had superior\ndocumentation in the form of \"Mercurial: The Definitive Guide\" aka\nhgbook. Though nowadays there is \"Git User's Manual\" and \"Pro Git\",\nit is hard to fight prejudice.\n\n> Sverre Rabbelier:\n> \n> SR> What do you mean with the last part (about `git branch -r`)? The\n> SR> fact that 'refs/remotes' is not immutable?\n> \n> Well, consider for example the simple obfuscatory mastery of the\n> following line in the user manual:\n> \n> > $ git branch -r\t\t\t# list all remote branches\n\nSo you say that it should be instead the following, isn't it?\n\n> $ git branch -r\t\t# list all remote-tracking branches\n\n\n> \n> \n> Yes, I get it *now*. And I begin to feel the corruption spreading in\n> my own brain already: I myself start to think of origin/master as a\n> ``remote branch''. Give me a few more weeks and I will be\n> completely assimilated in the mindset.\n> \n> (Note to self: submit a patch about this before my assimilation is\n> complete. I already fixed it and committed to my local branch.)\n\nThat would be very nice.\n\n> \n> Matthieu again:\n> \n> MM> We already came up with a better wording, namely \"upstream\", and\n> MM> used in in \"git push --set-upstream\".\n> \n> Oh, I didn’t know that. I was convinced that \"upstream\" was\n> cruft from when git was chiefly a tool to help Linus maintain the\n> Linux kernel. Let's see if I get this right:\n> \n> The remote-tracking branch \"origin/master\" is *upstream* (the\n> upstream?) of the local branch \"master\",\n\nRight.\n\n> and [local branch \"master\"] *tracks* the remote origin’s branch\n> \"master\"? (local) \"master\" is downstream of \"origin/master\"?\n\nWith above clarification: right. Though using \"track\" here was\nmistake (\"follows\" or \"is downstream\").\n\n> \n> This would be useful. And @{u} is good. (Does it have an inverse?)\n\nOne branch can have only one \"upstream\" (in old terminology: it can\ntrack only one branch). But the reverse doesn't hold: single\nremote-tracking branch can be upstream for many branches (e.g. many\nfeature branches based on the same long-lived branch). The mapping is\none-to-many, so there is no inverse.\n\n> \n> I’m not sure I like the particular word, but that’s a minor complaint. \n> \n> ( For completeness: A small terminological quibble is that upstream\n> doesn’t verb well.\n\nThat's why git has `--set-upstream` ;-)\n\n> A bigger conceptual quibble is that this decision is not\n> workflow-neutral. It enforces git’s hierarchical linux-kernel\n> development tradition, rather than embracing a truly distributed\n> model where everybody is the same. When I think of distributed\n> version control I like to think of Alice having a remote-tracking\n> bob/master and Bob having a remote-tracking alice/master. Of course,\n> it is still meaningful for Alice to say \"the upstream of\n> bobs_latest_crazy_ideas is bob/master\", and for Bob to say \"the\n> upstream of alices_inane_ramblings is alice/master\". But it\n> introduces a notion of hierarchy that is inimical to the concept of\n> distribution, and not workflow-neutral. )\n\nActually it is inimical to pull-based workflow, not to hierarchical\ndevelopment. \"Upstream\" is where you pull from.\n\nSidenote: having 'canonical' repository that (almost) everybody pulls\nfrom is I think quite common in DVCS-based development, isn't it?\n\n> \n> Of course, upstream could be called supercalifragilistic and I would\n> still like it. Consistency is more important than having good\n> metaphors. (But good metaphors would be better, all other things\n> being equal.)\n> \n> Jakub Narebski:\n> \n> JNa> Note that it is not as easy as it seems at first glance. There\n> JNa> are *two* such options, which (as you can read in gitcli(7)\n> JNa> manpage) have slightly different meaning:\n> \n> Wow. Thanks for pointing this out, I did not know that, and it\n> explains a lot. I must say that to everybody else than a git\n> developer, this state of affairs is a proof that something is wrong,\n> rather than an obstruction for improvement.\n\nWhat I wanted to say that any proposal for replacing 'cache'/'cached'\nand 'index' terms has to take into account that you might want to\noperate on staging area *instead of* default target (`--cached`),\nor *in addition to* default target (`--index`).\n\nThough it is not widespread issue: only git-apply uses both --cached\nand --index, git-stash uses only --index, and all other commands use\nonly --cached (if any).\n\nWell, there is also outlier of `git diff --no-index`, but it is more\nlack of good name for an option :-P\n\n> \n> ??> I do not think debating on changing the terminology is a\n> ??> particularly productive use of our time.\n> \n> I agree in the sense that *how* the words are used is more important\n> than *which* words are used, and I realise that I should not have\n> put \"terminology\" in the headline, because that makes it about\n> words, not *explanations* or terminological *discipline*.\n\nWhat should you put in headline / subject, then?\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"153827","messageId":"1287525214.11155.183.camel@drew-northup.unet.maine.edu","threadId":"25473","inReplyTo":"8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-10-19T21:53:34Z","receivedAt":"2010-10-19T21:53:34Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Mon, 2010-10-18 at 22:45 +0200, Thore Husfeldt wrote:\n> I’ve just learned Git. What a wonderful system, thanks for building\n> it. \n> \n> And what an annoying learning experience. \n\nI have to admit having dealt with quite a few annoyances, but mostly\nbecause I'm attempting to implement new functionality into this\nproject--something that requires minimally groking the sections of code\nthat I propose to change. (Anything less is sheer idiocy--and this is a\ncrowd that would not hesitate to say so.)\n\n> I promised myself to try to remember what made it all so hard, and to\n> write it down in a comprehensive and possibly even constructive\n> fashion. Here it is, for what it’s worth. Read it as the friendly, but\n> somewhat exasparated suggestions of a newcomer. I’d love to help (in\n> the form of submitting patches to the documentation or CLI responses),\n> but I’d like to test the waters first.\n> \n> So, in no particular order, here are the highlights of my former\n> confusion, if only for your entertainment. Comments are welcome, in\n> particular where my suggestions are born out of ignorance.\n\nAs a user and survivor of other source code management, collaboration,\nand versioning systems (not to mention some OS/X Windows/uC/CPU innards)\nI did not find git nearly as jolting as you appear to have. I suspect\nthis will be clear in following discussions.\n\n> Remote (tracking) branches\n> --------------------------\n> \n> There are at least two uses of the word *tracking* in Git's\n> terminology.\n> \n> The first, used in the form “git tracks a file” (in the sense that Git\n> knows about the file) is harmless enough, and is handled under `git\n> add` below.\n> \n> But the real monster is the *tracking branch*, sometimes called the\n> remote branch, the remote-tracking branch, or the remote tracking\n> branch. Boy did that ever confuse me. And, reading the git mailing\n> list and the web, many others. There are so many things wrong with how\n> this simple concept is obfuscated by the documentation that I have a\n> hard time organising my thoughts about writing it down.\n> \n> Please, *please* fix this. It was the single most confusing and\n> annoying part of learning Git.\n> \n> First, the word, “tracking”. These branches don’t track or follow\n> anything. They are standing completely still. Please believe me that\n> when first you are led to believe that origin/master tracks a branch\n> on the remote (like a hound tracks it quarry, or a radar tracks a\n> flight) that it is very difficult to hunt this misunderstanding down:\n> I believed for a long time that the tracking branch stayed in sync,\n> automagically, with a synonymous branch at the remote. The CLI and\n> documentation worked very hard to keep me in that state of\n> ignorance. I *know* that my colleague just updated the remote\n> repository, yet the remote branch (or is the remote tracking branch?\n> or the remote-tracking branch?) is as it always was...? (How could I\n> *ever* believe that? Well, *now* I get it, and have a difficult time\n> recollecting that misunderstanding. *Now* it’s easy.)\n\nTwo things here: \n(1) The meaning of \"tracking\" in context differs from your abstract\nnotion of tracking. Perhaps the metaphor is better seen as the\n\"tracking\" of wild game animals--you follow their footprints, grazing\nmarks, paths, and scat (viewed with gitk ? ;-) ) yet only once in a\nwhile can you reach out and \"pull\" on them (at least one doesn't have to\nshoot things to make git work--although it might help on some days).\n\n(2) Hyphenation should, in theory, be consistent. I do not however\nexpect this to be completely automatic in a population of code authors\nwhich contains a great deal of non-native speakers of English\n(conceivably some people here may even read and write English without\nfeeling competent to speak it out loud). Due to this reality I usually\nkeep my inner \"Grammar Nazi\" in check with free/open software projects.\nThis does not make the documentation any easier to read, it just keeps\nme from breaking things while I do. \nAs an aside, whose \"English\" are we to deem nominally correct--ASE, BSE,\nISE, or perhaps so-called \"Singapore English\" (which is actually spoken\nother places as well)? Just because American Standard English currently\nhas (eroding) hegemony in the software documentation sphere (from my\nperspective) does not grant me some special platform to shove it down\nthe throats of others. Thankfully clarification of hyphenation by\nintroducing consistency is likely to be universally received in a\npositive light.\n\n> Second, the word “remote” as opposed to “local”, a dichotomy enforced\n> by both the documentation and by the output of `git branch -r` (list\n> all remote branches, says user-manual.txt). Things began to dawn on me\n> only when I understood that origin/master is certainly and absolutely\n> a “local” branch, in the sense that it points to a commit in my local\n> repository. (It differs from my other local branches mainly in how it\n> is updated. It’s not committed to, but fetched to. But both are local,\n> and the remote can be many commits ahead of me.)\n> \n> So, remote tracking branches are neither remote (they are *local*\n> copies of how the remote once was) and they stand completely still\n> until you tell them to “fetch”. So remote means local, and tracking\n> means still, “local still-standing” would be a less confusing term\n> that “remote tracking”. Lovely.\n\nThis is one area in which excessive steeping in the handling, care,\nfeeding, and management of other SCM systems would help understand what\ngit is up to.\n\nThe \"origin/master\" is seen semantically as a locally stashed but not\nintended to be used directly \"copy\" of the origin's master--you create a\nlocal branch for that--in your local object store. This apparent copy\ncan be thought of better perhaps as a pointer into the object store to\ncall upon the \"origin/master\" locally-stored state (origin's master as\nyour local object store remembers it). It can be used to follow changes\nmade to the remote--origin's--master (but one is not forced to do so).\nOften times it may be found mirrored in (more correctly, merged into)\nthe local branch named \"master\"--which you created, most likely via\ncloning. Therefore it can be confusing at some level--at first--to\nrealize that \"origin/master\" and \"master\" are not the same thing yet may\nsure appear to be. Once you take the pointer for what it is this makes a\nbit more sense. (This is why you can \"git checkout origin/master\" if you\nwant...)\nTaking this metaphor one step further, we DE-REFERENCE and merge\n\"origin/master\" into \"master\" (or whatever you named your\n\"remote-tracking\" branch) as the last bulk operation when executing a\n\"pull\" on master. This is explained fairly clearly (in my mind) in the\ndocumentation as a convenience melding of a \"git fetch\"--origin's master\n(remote) is copied into the local object store as \"origin/master\"--and a\n\"git merge origin/master\" executed while checked-out as the local copy\nof the branch you are tracking (you probably named it master).\n\n> Tracking branches *track* in the sense that a stuffed Basset Hound\n> tracks. Namely, not. It‘s a dream of what once was.\n\nYES!!! Ok, well, except for the stuffed part. Never have your dog\nstuffed (ask Alan Alda, or read his book of the same name).\n\n> The hyphenated *remote-tracking* is a lot better terminology already\n> (and sometimes even used in the documentation), because at least it\n> doesn't pretend to be a remote branch (`git branch -r`, of course,\n> still does). So that single hyphen already does some good, and should\n> be edited for consistency. (It did take time for me to convince myself\n> during the learning process that “remote tracking” and\n> “remote-tracking” probably are the same thing, and “tracked remote”\n> something else, abandoning and resurrecting these hypetheses several\n> times.)\n\nThis, I'm sure, can be rectified with minimum pain. Recall my note above\nabout non-native speakers. I don't expect them (or for that matter most\nnative speakers) to be in the habit of making use of English punctuation\ntools that most American Language-Arts teachers don't seem to have\nmastered either. Heck, I'll readily admit that I only got a 3 (of 5) on\nthe English Language AP Exam, so there are obviously some aspects of the\n\"official\" language known to the cognoscenti that I still don't grok\neither.\n\n> And *even if* the word was meaningful and consistenly spelt, the\n> documentation uses it to *refer* to different things. Assume that we\n> have the branches master, origin/master, and origin’s master\n> (understanding that they exist, and are different, is another Aha!\n> moment largely prevented by the documentation). For 50 points, which\n> is the remote tracking branch? Or the remote-tracking branch? \n\nLet's not make a big deal about the hyphen in that case for now.\n\n> The remote branch? \n\nThat would be origin's branch (whatever it is named and whoever \"origin\"\nis in this case).\n\n> Which branch tracks which other branch? \n\nOur local origin/ is our local object store's memory of what it\nlast knew origin's branch to look like.\n\n> Does master track anything? \n\nPer-Se, No. Can it be merged with our latest fetch into the object store\nof origin's (origin/...)? Yes. Can it be done with one nice convenient\nwrapper command in the current git? Yes!\n\n> Nobody seems to know, and documentation and CLI\n> include various inconsistent suggestions. (I know there have been\n> long, and inconclusive threads about this on the git mailing list, and\n> I learned a lot from seeing other people’s misconceptions mirror my\n> own.) Granted, I think the term “tracked remote branch” is used with\n> laudable consistentcy to refer to a branch on the remote. And “remote\n> tracking branch” (with our without the hyphen) more often than not\n> refers to origin/master. It may be that terminology is slowly\n> converging. (To something confusing, but still...)\n\nRemember, remote branches other than \"master\" may be tracked. For\ninstance, if you are tracking git with git then you are also tracking\nbranches named html, todo, maint, man, pu, and next--yet you may not\nhave created a local remote-tracking branch for them to reside in\nlocally.\n\n> But to appreciate how incredibly difficult this was to understand,\n> check this, from the Git Community book:\n> \n> A 'tracking branch' in Git is a local branch that is connected to\n> a remote branch.\n> \n> To a new user, who *almost* gets it, this is just a slap in the\n> face. Which one of these is origin/master again? None? (Or rather, it\n> is the confirmation one needs that nobody in the Git community cares\n> much, so the once-believed-to-be-carefully-worded documentation loses\n> some of its authority and therefore the learner can abandon some\n> misunderstandings.)\n\nAgain, the author's sense of \"connected\" and your internal sense of\n\"connected\" did not match--much like \"tracking\" earlier (and below). He\nis not stating that they are bound at the hip, he is merely noting the\npresence of a conceptual relationship between the two. It could have\nbeen stated differently perhaps, but it is not the end of the world.\n\n> There probably is a radical case to be made for abandoning the word\n> “tracking” entirely. First, because tracking branches don’t track, and\n> second because “tracking” already means something else in Git (see\n> below). I realise that this terminology is now so ingrained in Git\n> users that conservatism will probably perpetuate it. But it would be\n> *very* helpful to think this through, and at least agree on who\n> “tracks” what. In the ideal world, origin/master would be something\n> like “the fetching branch” for the origin’s master, or the “snapshot\n> branch” or the “fetched branch”. (I am partial to use “fetching”\n> because it makes that operation a first-class conceptual citizen,\n> rather than pulling, which is another siren that lures newbies into a\n> maelstroem of confusion.)\n\nUmm, NO. Tracking is a term that is used consistently in most places. It\nmeans \"following by collecting information about\" as I noted earlier\nwith my wild game animals example. This is true throughout whether that\nbeing tracked is a file's contents, an entire branch's contents, or the\ncontents of a whole repository. That you have mis-associated the concept\nof tracking with that of fetching the information used to perform that\ntracking (and remembering from where and how to do so) is perhaps\nsomething that can be dealt with but it does not require abandoning what\nis frankly a useful metaphor. (Besides \"fetching\" in isolation begs\nconfusion with other concepts such as a \"comely lass\"--the great wonder\nof the English language indeed.)\n\n> More radically, I am sure some head scratching would be able to find\n> useful terminology for master, origin/master, and origin’s master. I’d\n> love to see suggestions. As I said, I admire how wonderfully simple\n> and clean this has been implemented, and the documentation, CLI, and\n> terminology should reflect that.\n\nI did not find the terminology particularly jarring, but I have used\n(and survived doing so) other SCM software. Perhaps you did not have any\nprevious SCM background? More information as to the source of confusion\nand your perspective when starting out can only help improve the\ndocumentation.\n\n> The staging area\n> ----------------\n> \n> The wonderful and central concept of staging area exists under at\n> least three names in Git terminology. And that’s really, really\n> annoying. The index, the cache, and the staging area are all the same,\n> which is a huge revelation to a newcomer.\n\nNot true. When merging the index may contain multiple staged instances\nof any given content needed to resolve conflicts for instance. Also, the\ncache is stored inside of the index. Therefore while they may at any\ngiven time have exactly the same contents they are not the same things\nnor concepts.\n\n> *Index* would have been a good word for the files known\n> to Git (what is now called, sometimes, “tracked files”)\n\nIndex is used to refer to the mechanism by which the currently operative\nCONTENT known to git. Git does not track files per-se, it tracks\nCONTENT. This is an important distinction to master. It literally\nindexes the contents to be operated upon in the object store. That those\ncontents happen to exist in files is something it keeps track of but it\nreally could care less. So far is it is concerned they could be show\ntunes.\n\n> `git stage` is already part of the distribution. Great.\n> \n> 1. Search for index and cache in the documentation and rephrase any\n> and all their occurences to use “staged” (or, if it can’t be avoided\n> “the staging area”) instead. Say “staged to be committed” often, it’s\n> a strong metaphor.\n\nNo. The documentation should not be made incorrect just to make it sound\nmore consistent.\n\n> 2. Introduce the alias `git unstage` for `git reset HEAD` in the\n> standard distribution.\n\nThis is evidence to me that you have not used other SCM software. The\nidiom \"reset\" is widely used in various SCM implementations.\n\n> 3. Duplicate various occurences of `cached` flags as `staged` (and\n> change the documentation and man pages accordingly), so as to have,\n> e.g., `git diff --staged`.\n\nAgain, cached is not staged and flags should not be made incorrect just\nto cover for the fact that you have not found a use for them separately.\n\n> git status\n> ----------\n> \n> One of the earliest-to-use commands is `git status`, whose message are\n> *wordy*, but were initially completely unhelpful to me. In particular,\n> \n> working directory clean\n> \n> Clean? What’s this now? Clean and dirty are Git slang, and not what I\n> want to meet as a new user. \n\nThis is not git-specific jargon. In fact, it is widely used terminology\nthroughout the computing world in memory management, databases,\nfilesystems, and even other SCM platforms. I have even heard it used by\nnon-computer-oriented people to refer to original and changed states.\n\n> The message should inform me that the\n> untracked files in the working directory are equal to their previous\n> commit. But there are other things wrong with the message. \n\nActually, what it is stating is correct. It knows NOTHING about any\nuntracked files OTHER THAN that they have not changed since the last\ncommit. In other words, the POTENTIAL INDEX is clean of unwritten\nchanges. \n\n> For\n> example, even though there’s nothing to commit: `nothing added to\n> commit but untracked files present (use \"git add\" to track)`? The last\n> paranethesis should set off warning bells already. And what did clean\n> mean with respect to untracked files? And “added to commmit”? That\n> sounds like amending. We add to the index or the staging area, don’t\n> we, “ready to be included in the next commit,” so they aren’t added to\n> that commit quite yet?\n\nThis is analogous to files having been changed inside of an application\nyet the application has not yet requested that such changes be scheduled\nto be committed to the filesystem. You have to request that such changes\nbe added to the filesystem layer's idea of what needs to be committed\nand then it will be written out in due time. The same thing applies to\ngit's index and the object store.\n\n> \n> changed but not updated:\n> \n> I’m still not sure what “update” was ever supposed to mean in this\n> sentence. I just edited the file, so it’s updated, for crying out\n> loud! The message might just say “Changed files, but not staged to be\n> committed.” \n\nIn this case you have already scheduled some changes of a file to be\ncommitted in the index and then have gone and made additional changes\nwithout updating the index. So no, it isn't updated yet--but there are\nchanges staged to be committed for the very same files.\n\n> The meant-to-be helpful “use [...] to update what will be\n> committed” is another can of worms, and I can find at least two ways\n> to completely misunderstand this. Change to “use `git stage ` to\n> stage”. (With the new command name it’s almost superfluous.)\n\nHere is where a proper discussion of why it is called \"git add \"\ncomes into play. When you use the add operation you are literally adding\nhe current status of that file to the index. If you make another change\nto that file before committing you will need to add that new status of\nthe file. In other words, you have staged the changes to the content in\nthat file to be committed twice into the index at two different times\nand with two different change-sets.\n\n> Here are some concrete suggestions:\n> \n> 1.\n> \n> nothing added to commit but untracked files present\n> \n> should be\n> \n> nothing staged to commit, but untracked files present\n> \n> (Comment: maybe “... but working directory contains untracked files.”\n> I realise that “directory” is not quite comprehensive here, because\n> files can reside in subdirectories. But I’d like to be more concrete\n> than “be present”.)\n\nThe concept of \"present\" is fine in this case, just like being present\nat a meeting. The comma is useful perhaps to some but may not be\ngrammatically correct here. As for \"added\" versus \"staged\" that depends\non the circumstances. I am having trouble coming up with an example off\nthe top of my head as to how to explain when \"added\" and \"staged\" differ\nin meaning I am sure the do (perhaps upon the deletion of a tracked\nfile?).\n\n> 2.\n> Untracked files:\n> (use \"git add ...\" to include in what will be committed)\n> \n> should be\n> \n> Untracked files:\n> (use \"git track \" to track)\n\nThis is not helpful. Git does not work the way that Subversion does. In\nother words, each content change must be manually added to the index for\nstaging to build a commit for each and every commit. Files and their\ncontents ARE NOT tracked perpetually (touching on earlier noted\nconfusion about the context-specific meaning of track). We should not\nencourage confusion on this matter.\n\n> 3.\n> \n> Changes to be committed:\n> (use \"git reset HEAD ...\" to unstage)\n> \n> should be\n> \n> Staged to be committed:\t\t \n> (use \"git unstage \" to unstage)\n\nAgain, \"reset\" is a widely used metaphor in SCM software and there is no\ngood reason to abandon it. What you are proposing is not even a 1:1\nreplacement. The original command quite literally does the following\n\"reset index information about to HEAD\" while what you propose\nmerely says \"remove staged change about from the index.\" What if\n has been changed and staged to commit more than once? The\nproposed syntax is ambiguous and therefore is a poor replacement.\n\n> Adding\n> ------\n> \n> The tutorial tells us that \n> \n> Many revision control systems provide an add command that tells\n> the system to start tracking changes to a new file. Git's add\n> command does something simpler and more powerful: git add is used\n> both for new and newly modified files, and in both cases it takes\n> a snapshot of the given files and stages that content in the\n> index, ready for inclusion in the next commit.\n> \n> This is true, and once you grok how Git actually works it also makes\n> complete sense. “Making the file known to Git” (sometimes called\n> “tracking the file”) and “staging for the next commit” result in the\n> exact same operations, from Git’s perspective.\n\nNot exactly. You forget that git is not stateless. A file may be \"known\nto git\" yet not changed (much less staged) since the last commit. Also,\ngit does not track changes perpetually--it only updates it's idea\n(index) of changes to be committed (stages) when asked. It could be said\nthat it tracks changes incrementally upon request.\n\n> But this is a good example of what’s wrong with the way the\n> documentation thinks: Git’s implementation perspective should not\n> define how concepts are explained. In particular, *tracking* (in the\n> sense of making a file known to git) and *staging* are conceptually\n> different things. In fact, the two things remain conceptually\n> different later on: un-tracking (removing the file from Git’s\n> worldview) and un-staging are not the same thing at all, neither\n> conceptually nor implementationally. The opposite of staging is `git\n> reset HEAD ` and the opposite of tracking is -- well, I’m not\n> sure, actually. Maybe `git update-index --force-remove `?\n> But this only strenghtens my point: tracking and staging are different\n> concepts, and therefore deserve different terms in the documentation\n> and (ideally) in the CLI.\n\nAs tracking of changes is in part the art of remembering those changes\nand making such changes available for inspection upon request (see my\n\"wild game\" metaphor above) the way a detective might \"track\" evidence\nthere is no need to conflate the incremental tracking of some changes\nbefore committing them with the list of changes we have tracked into the\nobject store in the past. This is part of the power of git. It tells you\nwhat content changed when and where that change came from. It \"tracked\"\nall of them. It does not \"track\" mere files. It tracks CONTENT. When git\n\"stages\" changes it tracks them in its short-term memory (the index) and\nwhen it commits those staged changes to the object store it allows\nitself to track them for all time (conceptually).\n\n> The entire quoted paragraph in the tutorial can be removed: there’s\n> simply no reason to tell the reader that git behaves differently from\n> other version control systems (indeed, to take some perverse *pride*\n> in that fact). \n\nIn fact it is very worth noting that git works differently from other\nSCM software. Not knowing what is different leads to a series of\nimportant and potentially disastrous misconceptions. It should take\npride in being different, as it implements the holy grail of SCM: being\nable to know who changed what, when, and perhaps even why.\n\n> An even more radical suggestion (which would take all of 20 seconds to\n> implement) is to introduce `git track` as another alias for `git\n> add`. (See above under `git status`). This would be especially useful\n> if tracking *branches* no longer existed.\n\nThis is not appropriate. Git is not Subversion. It does not track files\nfor all time and it is not stateless. Full Stop.\n\n> There’s another issue with this, namely that “added files are\n> immediately staged”. In fact, I do understand why Git does that, but\n> conceptually it’s pure evil: one of the conceptual conrnerstones of\n> Git -- that files can be tracked and changed yet not staged, i.e., the\n> staging areas is conceptually a first-class citizen -- is violated\n> every time a new file is “born”. Newborn files are *special* until\n> their first commit, and that’s a shame, because the first thing the\n> new file (and, vicariously, the new user) experiences is an\n> aberration. I admit that I have not thought this through.--\n\n????? This strikes me as a vast misunderstanding of the mechanism at\nwork. If you could describe the roots of this idea then perhaps it could\nbe addressed. Git is not your filesystem.\n\nHopefully the couple of hours I spent on this helps further this\ndiscussion in a useful manner.\n\n-- \n-Drew Northup\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"153828","messageId":"20101019221005.GC32029@burratino","threadId":"25473","inReplyTo":"7vhbgiyoo9.fsf@alter.siamese.dyndns.org","subject":"[RFC/PATCH 0/4] reset: be more flexible about ","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T22:10:05Z","receivedAt":"2010-10-19T22:10:05Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> It is probably Ok to limit the scope of this change to the case without\n> any explicit rev, e.g. \"git reset -- frotz.c\", but at that point I somehow\n> don't think it will reduce confusion but rather will make things worse.\n\nI wouldn't be surprised to find people using\n\n\tgit reset HEAD \n\njust because '--' did not come to mind quickly enough. For example, I\nhave a faint memory of doing that myself a couple of years ago. Why\nshould Git mind?\n\nPatch 1 below teaches reset -p to accept an arbitrary tree for .\nUnfortunately add--interactive notices but does not error out when\n is a blob; that should be fixed in the add--interactive script\nby checking the exit status of commands it runs, I think (help from\nthose more comfortable in perl would be appreciated).\n\nPatch 2 removes the arbitrary restriction in \"git reset \n\" that be a commit. It also paves the way for writing\npatch 3 more clearly.\n\nPatch 3 is the \"probably Ok\" change you mentioned above. It allows\nuse of \"git reset\" to un-add a file from an unborn branch.\n\nPatch 4 is like patch 3, but for \"git reset HEAD\".\n\nHelp on finishing up patch 1 (or comments to the effect that it is\npointless) would be welcome.\n\nJonathan Nieder (4):\n reset -p: accept \"git reset -p \"\n reset: accept \"git reset \"\n reset: accept \"git reset -- \" from unborn branch\n reset: accept \"git reset HEAD \" from unborn branch\n\n builtin/reset.c | 27 ++++++++++++++++-------\n t/t7102-reset.sh | 31 +++++++++++++++++++++++++++\n t/t7105-reset-patch.sh | 12 ++++++++++\n t/t7106-reset-unborn.sh | 53 +++++++++++++++++++++++++++++++++++++++++++++++\n 4 files changed, 115 insertions(+), 8 deletions(-)\n create mode 100755 t/t7106-reset-unborn.sh\n\n-- \n1.7.2.3\n"},{"id":"153829","messageId":"20101019221147.GD32029@burratino","threadId":"25473","inReplyTo":"20101019221005.GC32029@burratino","subject":"[WIP/PATCH 1/4] reset -p: accept \"git reset -p \"","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T22:11:47Z","receivedAt":"2010-10-19T22:11:47Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"When reset -p was implemented (v1.6.5-rc0~5^2~7, 2009-08-15), it\npiggy-backed on an existing \"git reset\" check to verify that the\n argument represents a valid commit. By dropping that\ncheck, we can use reset -p to apply changes from an arbitrary\ntree; for example, from the linux-2.6 tree:\n\n\tgit reset -p 2.6.11 -- Makefile\n\nadd--interactive already rejects invalid refs.\n\n\t$ git init >dev/null 2>&1; git reset -p HEAD; echo $?\n\tfatal: ambiguous argument 'HEAD': unknown revision or path not in the working tree.\n\tUse '--' to separate paths from revisions\n\t128\n\nUnfortunate side-effect: reset -p will accept a blob for ,\ntoo.\n\n\t$ git reset -p HEAD:git.c; echo $?\n\terror: bad tree object HEAD:git.c\n\tNo changes.\n\t0\n\nSigned-off-by: Jonathan Nieder \n---\n builtin/reset.c | 12 ++++++------\n t/t7105-reset-patch.sh | 12 ++++++++++++\n 2 files changed, 18 insertions(+), 6 deletions(-)\n\ndiff --git a/builtin/reset.c b/builtin/reset.c\nindex 0037be4..a52e6f8 100644\n--- a/builtin/reset.c\n+++ b/builtin/reset.c\n@@ -297,24 +297,24 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\t\t/* Otherwise we treat this as a filename */\n \t\t\tverify_filename(prefix, argv[i]);\n \t\t}\n \t}\n \n+\tif (patch_mode) {\n+\t\tif (reset_type != NONE)\n+\t\t\tdie(\"--patch is incompatible with --{hard,mixed,soft}\");\n+\t\treturn interactive_reset(rev, argv + i, prefix);\n+\t}\n+\n \tif (get_sha1(rev, sha1))\n \t\tdie(\"Failed to resolve '%s' as a valid ref.\", rev);\n \n \tcommit = lookup_commit_reference(sha1);\n \tif (!commit)\n \t\tdie(\"Could not parse object '%s'.\", rev);\n \thashcpy(sha1, commit->object.sha1);\n \n-\tif (patch_mode) {\n-\t\tif (reset_type != NONE)\n-\t\t\tdie(\"--patch is incompatible with --{hard,mixed,soft}\");\n-\t\treturn interactive_reset(rev, argv + i, prefix);\n-\t}\n-\n \t/* git reset tree [--] paths... can be used to\n \t * load chosen paths from the tree into the index without\n \t * affecting the working tree nor HEAD. */\n \tif (i < argc) {\n \t\tif (reset_type == MIXED)\ndiff --git a/t/t7105-reset-patch.sh b/t/t7105-reset-patch.sh\nindex 9891e2c..ba3ff42 100755\n--- a/t/t7105-reset-patch.sh\n+++ b/t/t7105-reset-patch.sh\n@@ -46,10 +46,22 @@ test_expect_success PERL 'git reset -p dir' '\n \t(echo y; echo n) | git reset -p dir &&\n \tverify_state dir/foo work head &&\n \tverify_saved_state bar\n '\n \n+test_expect_success PERL 'git reset -p dir' '\n+\tset_state dir/foo work work &&\n+\t(echo y; echo n) | git reset -p HEAD^{tree} dir &&\n+\tverify_state dir/foo work head &&\n+\tverify_saved_state bar\n+'\n+\n+test_expect_failure PERL 'git reset -p ' '\n+\tset_state dir/foo work work &&\n+\ttest_must_fail git reset -p HEAD:dir/foo\n+'\n+\n test_expect_success PERL 'git reset -p -- foo (inside dir)' '\n \tset_state dir/foo work work\n \t(echo y; echo n) | (cd dir && git reset -p -- foo) &&\n \tverify_state dir/foo work head &&\n \tverify_saved_state bar\n-- \n1.7.2.3\n"},{"id":"153830","messageId":"20101019221244.GE32029@burratino","threadId":"25473","inReplyTo":"20101019221005.GC32029@burratino","subject":"[PATCH 2/4] reset: accept \"git reset \"","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T22:12:44Z","receivedAt":"2010-10-19T22:12:44Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"The argument in\n\n\tgit reset --hard \n\tgit reset --soft \n\nneeds to be a commit to be sensible. But in\n\n\tgit reset -- ...\n\nusing other trees can be useful.\n\nFor example, to apply changes from a branch that has the current\nbranch merged as a subtree:\n\n\tgit reset master:gitk-git -- .\n\nSigned-off-by: Jonathan Nieder \n---\n builtin/reset.c | 11 ++++++-----\n t/t7102-reset.sh | 31 +++++++++++++++++++++++++++++++\n 2 files changed, 37 insertions(+), 5 deletions(-)\n\ndiff --git a/builtin/reset.c b/builtin/reset.c\nindex a52e6f8..2375472 100644\n--- a/builtin/reset.c\n+++ b/builtin/reset.c\n@@ -306,15 +306,10 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t}\n \n \tif (get_sha1(rev, sha1))\n \t\tdie(\"Failed to resolve '%s' as a valid ref.\", rev);\n \n-\tcommit = lookup_commit_reference(sha1);\n-\tif (!commit)\n-\t\tdie(\"Could not parse object '%s'.\", rev);\n-\thashcpy(sha1, commit->object.sha1);\n-\n \t/* git reset tree [--] paths... can be used to\n \t * load chosen paths from the tree into the index without\n \t * affecting the working tree nor HEAD. */\n \tif (i < argc) {\n \t\tif (reset_type == MIXED)\n@@ -323,10 +318,16 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\t\tdie(\"Cannot do %s reset with paths.\",\n \t\t\t\t\treset_type_names[reset_type]);\n \t\treturn read_from_tree(prefix, argv + i, sha1,\n \t\t\t\tquiet ? REFRESH_QUIET : REFRESH_IN_PORCELAIN);\n \t}\n+\n+\tcommit = lookup_commit_reference(sha1);\n+\tif (!commit)\n+\t\tdie(\"Could not parse object '%s'.\", rev);\n+\thashcpy(sha1, commit->object.sha1);\n+\n \tif (reset_type == NONE)\n \t\treset_type = MIXED; /* by default */\n \n \tif (reset_type != SOFT && reset_type != MIXED)\n \t\tsetup_work_tree();\ndiff --git a/t/t7102-reset.sh b/t/t7102-reset.sh\nindex b8cf260..3e95da3 100755\n--- a/t/t7102-reset.sh\n+++ b/t/t7102-reset.sh\n@@ -7,10 +7,18 @@ test_description='git reset\n \n Documented tests for git reset'\n \n . ./test-lib.sh\n \n+test_exit_code () {\n+\techo $1 >expect.code &&\n+\tshift &&\n+\t\"$@\"\n+\techo $? >actual.code &&\n+\ttest_cmp expect.code actual.code\n+}\n+\n test_expect_success 'creating initial files and commits' '\n \ttest_tick &&\n \techo \"1st file\" >first &&\n \tgit add first &&\n \tgit commit -m \"create 1st file\" &&\n@@ -409,17 +417,40 @@ test_expect_success 'test resetting the index at give paths' '\n \ttest_must_fail git diff-index --cached --exit-code \"$T\" &&\n \ttest \"$T\" != \"$U\"\n \n '\n \n+test_expect_success 'reset modified path from tree' '\n+\techo hello >other &&\n+\tgit reset --hard &&\n+\tgit add other &&\n+\tT=$(git write-tree) &&\n+\tgit rm -f other &&\n+\ttest_exit_code 1 git reset $T other &&\n+\tgit diff-index --cached --exit-code \"$T\"\n+'\n+\n+test_expect_success 'try to reset from blob' '\n+\tgit reset --hard &&\n+\tB=$(git rev-parse --verify HEAD:file1) &&\n+\ttest_exit_code 128 git reset $B -- .\n+'\n+\n test_expect_success 'resetting an unmodified path is a no-op' '\n \tgit reset --hard &&\n \tgit reset -- file1 &&\n \tgit diff-files --exit-code &&\n \tgit diff-index --cached --exit-code HEAD\n '\n \n+test_expect_success 'reset unmodified path from tree' '\n+\tgit reset --hard &&\n+\tgit reset HEAD^{tree} -- file1 &&\n+\tgit diff-files --exit-code &&\n+\tgit diff-index --cached --exit-code HEAD\n+'\n+\n cat > expect << EOF\n Unstaged changes after reset:\n M\tfile2\n EOF\n \n-- \n1.7.2.3\n"},{"id":"153831","messageId":"20101019221331.GF32029@burratino","threadId":"25473","inReplyTo":"20101019221005.GC32029@burratino","subject":"[PATCH 3/4] reset: accept \"git reset -- \" from unborn branch","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T22:13:31Z","receivedAt":"2010-10-19T22:13:31Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"A common workflow:\n\n\tgit checkout \n\t... hack hack hack ...\n\tgit add -- \n\tgit reset -- ; # oops, that one isn't ready yet\n\tgit commit\n\nOne might try to use 'git reset' to undo the effect of 'git add' on an\nunborn branch, too, but it doesn't work:\n\n\t... hack hack hack ...\n\t$ git add -- \n\t$ git reset -- \n\tfatal: Failed to resolve 'HEAD' as a valid ref.\n\nIt is obvious that the operator meant to remove the entry for ,\nso just do that.\n\nThis patch only affects the \"git reset \" syntax; explicit\nuse of \"git reset HEAD \" will still error out.\n\nSuggested-by: Sverre Rabbelier \nSigned-off-by: Jonathan Nieder \n---\n builtin/reset.c | 15 ++++++++++++-\n t/t7106-reset-unborn.sh | 50 +++++++++++++++++++++++++++++++++++++++++++++++\n 2 files changed, 63 insertions(+), 2 deletions(-)\n create mode 100755 t/t7106-reset-unborn.sh\n\ndiff --git a/builtin/reset.c b/builtin/reset.c\nindex 2375472..ff57764 100644\n--- a/builtin/reset.c\n+++ b/builtin/reset.c\n@@ -234,12 +234,14 @@ static void die_if_unmerged_cache(int reset_type)\n }\n \n int cmd_reset(int argc, const char **argv, const char *prefix)\n {\n \tint i = 0, reset_type = NONE, update_ref_status = 0, quiet = 0;\n+\tint unborn_branch = 0;\n \tint patch_mode = 0;\n-\tconst char *rev = \"HEAD\";\n+\tconst char *implicit_HEAD = \"HEAD\";\n+\tconst char *rev = implicit_HEAD;\n \tunsigned char sha1[20], *orig = NULL, sha1_orig[20],\n \t\t\t\t*old_orig = NULL, sha1_old_orig[20];\n \tstruct commit *commit;\n \tchar *reflog_action, msg[1024];\n \tconst struct option options[] = {\n@@ -303,11 +305,18 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\tif (reset_type != NONE)\n \t\t\tdie(\"--patch is incompatible with --{hard,mixed,soft}\");\n \t\treturn interactive_reset(rev, argv + i, prefix);\n \t}\n \n-\tif (get_sha1(rev, sha1))\n+\tif (rev == implicit_HEAD) {\n+\t\t/* We may be on a branch yet to be born. */\n+\t\tresolve_ref(\"HEAD\", sha1, 0, NULL);\n+\t\tif (is_null_sha1(sha1)) {\n+\t\t\tunborn_branch = 1;\n+\t\t\thashcpy(sha1, (const unsigned char *) EMPTY_TREE_SHA1_BIN);\n+\t\t}\n+\t} else if (get_sha1(rev, sha1))\n \t\tdie(\"Failed to resolve '%s' as a valid ref.\", rev);\n \n \t/* git reset tree [--] paths... can be used to\n \t * load chosen paths from the tree into the index without\n \t * affecting the working tree nor HEAD. */\n@@ -319,10 +328,12 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\t\t\t\treset_type_names[reset_type]);\n \t\treturn read_from_tree(prefix, argv + i, sha1,\n \t\t\t\tquiet ? REFRESH_QUIET : REFRESH_IN_PORCELAIN);\n \t}\n \n+\tif (unborn_branch)\n+\t\tdie(\"Failed to resolve 'HEAD' as a valid ref.\");\n \tcommit = lookup_commit_reference(sha1);\n \tif (!commit)\n \t\tdie(\"Could not parse object '%s'.\", rev);\n \thashcpy(sha1, commit->object.sha1);\n \ndiff --git a/t/t7106-reset-unborn.sh b/t/t7106-reset-unborn.sh\nnew file mode 100755\nindex 0000000..7baaffd\n--- /dev/null\n+++ b/t/t7106-reset-unborn.sh\n@@ -0,0 +1,50 @@\n+#!/bin/sh\n+\n+test_description='git reset from a branch yet to be born'\n+. ./test-lib.sh\n+\n+>empty\n+\n+index_is_empty () {\n+\tgit ls-files >actual &&\n+\ttest_cmp empty actual\n+}\n+\n+test_expect_success 'reset to remove file' '\n+\techo one >file &&\n+\tgit add file &&\n+\tgit reset file &&\n+\tindex_is_empty\n+'\n+\n+test_expect_success 'reset after rm to remove file' '\n+\techo one >file &&\n+\tgit add file &&\n+\trm file &&\n+\tgit reset -- file &&\n+\tindex_is_empty\n+'\n+\n+test_expect_success 'reset file that does not match index' '\n+\techo one >file &&\n+\tgit add file &&\n+\techo two >file &&\n+\tgit reset -- file &&\n+\tindex_is_empty\n+'\n+\n+test_expect_success 'reset absent file' '\n+\tgit reset -- file &&\n+\tindex_is_empty\n+'\n+\n+test_expect_success 'reset HEAD from unborn branch' '\n+\ttest_must_fail git reset HEAD -- .\n+'\n+\n+test_expect_success 'reset HEAD from unborn branch' '\n+\ttest_must_fail git reset HEAD &&\n+\ttest_must_fail git reset HEAD --\n+'\n+\n+test_done\n-- \n1.7.2.3\n"},{"id":"153832","messageId":"20101019221415.GG32029@burratino","threadId":"25473","inReplyTo":"20101019221005.GC32029@burratino","subject":"[PATCH 4/4] reset: accept \"git reset HEAD \" from unborn branch","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T22:14:15Z","receivedAt":"2010-10-19T22:14:15Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"If I try:\n\n\t... hack hack hack ...\n\tgit add .\n\trm ; # bad file!\n\tgit reset \n\ngit will respond by informing me that this use of is\nambiguous. So I might try to disambiguate:\n\n\tgit reset HEAD \n\nThis works when HEAD represents a branch, but not in the 'new\nrepository' ('branch yet to be born') case.\n\nEven in the unborn branch case, it is clear what the operator meant\nto do (namely, remove the entry for ), so do that.\n\nSigned-off-by: Jonathan Nieder \n---\n builtin/reset.c | 5 ++---\n t/t7106-reset-unborn.sh | 5 ++++-\n 2 files changed, 6 insertions(+), 4 deletions(-)\n\ndiff --git a/builtin/reset.c b/builtin/reset.c\nindex ff57764..d9a5702 100644\n--- a/builtin/reset.c\n+++ b/builtin/reset.c\n@@ -236,12 +236,11 @@ static void die_if_unmerged_cache(int reset_type)\n int cmd_reset(int argc, const char **argv, const char *prefix)\n {\n \tint i = 0, reset_type = NONE, update_ref_status = 0, quiet = 0;\n \tint unborn_branch = 0;\n \tint patch_mode = 0;\n-\tconst char *implicit_HEAD = \"HEAD\";\n-\tconst char *rev = implicit_HEAD;\n+\tconst char *rev = \"HEAD\";\n \tunsigned char sha1[20], *orig = NULL, sha1_orig[20],\n \t\t\t\t*old_orig = NULL, sha1_old_orig[20];\n \tstruct commit *commit;\n \tchar *reflog_action, msg[1024];\n \tconst struct option options[] = {\n@@ -305,11 +304,11 @@ int cmd_reset(int argc, const char **argv, const char *prefix)\n \t\tif (reset_type != NONE)\n \t\t\tdie(\"--patch is incompatible with --{hard,mixed,soft}\");\n \t\treturn interactive_reset(rev, argv + i, prefix);\n \t}\n \n-\tif (rev == implicit_HEAD) {\n+\tif (!strcmp(rev, \"HEAD\")) {\n \t\t/* We may be on a branch yet to be born. */\n \t\tresolve_ref(\"HEAD\", sha1, 0, NULL);\n \t\tif (is_null_sha1(sha1)) {\n \t\t\tunborn_branch = 1;\n \t\t\thashcpy(sha1, (const unsigned char *) EMPTY_TREE_SHA1_BIN);\ndiff --git a/t/t7106-reset-unborn.sh b/t/t7106-reset-unborn.sh\nindex 7baaffd..c03f309 100755\n--- a/t/t7106-reset-unborn.sh\n+++ b/t/t7106-reset-unborn.sh\n@@ -37,11 +37,14 @@ test_expect_success 'reset absent file' '\n \tgit reset -- file &&\n \tindex_is_empty\n '\n \n test_expect_success 'reset HEAD from unborn branch' '\n-\ttest_must_fail git reset HEAD -- .\n+\techo one >file &&\n+\tgit add file &&\n+\tgit reset HEAD -- . &&\n+\tindex_is_empty\n '\n \n test_expect_success 'reset HEAD from unborn branch' '\n \ttest_must_fail git reset HEAD &&\n \ttest_must_fail git reset HEAD --\n-- \n1.7.2.3\n"},{"id":"153833","messageId":"20101019223442.GA5960@burratino","threadId":"25473","inReplyTo":"7vk4le13z3.fsf@alter.siamese.dyndns.org","subject":"Re: [RFC/PATCH] reset: accept \"git reset \"","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T22:34:42Z","receivedAt":"2010-10-19T22:34:42Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> It is generally unsafe, I am afraid, and that is one of the reasons why\n> verify_filename() does not look in the index (the other one was \"it is\n> merely a safety measure based on heuristics to help users, and no point\n> spending extra code nor cycles\", iow, deliberate laziness ;-)), making the\n> proposal of this patch under discussion somewhat iffy.\n\nLet's drop it, then. I'll continue the practice of always including \"--\"\nin examples suggested to new users.\n"},{"id":"153835","messageId":"7vzku9ye5k.fsf@alter.siamese.dyndns.org","threadId":"25473","inReplyTo":"20101019221415.GG32029@burratino","subject":"Re: [PATCH 4/4] reset: accept \"git reset HEAD \" from unborn branch","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-19T23:08:07Z","receivedAt":"2010-10-19T23:08:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> If I try:\n>\n> \t... hack hack hack ...\n> \tgit add .\n> \trm ; # bad file!\n> \tgit reset \n>\n> git will respond by informing me that this use of is\n> ambiguous.\n\nWhich is fixed by 3/4. I think that is probably a sane thing to do.\n\n> ... So I might try to disambiguate:\n>\n> \tgit reset HEAD \n\nI however do not think this is sane, as you are _explicitly_ referring to\nHEAD, saying \"I want to pull this out of the commit pointed by the HEAD\",\nwhile there is _no such commit_. Sounds somewhat insane.\n\nBut why is path1 ambiguous in the first place? It is because it is not\nconsidered to be a pathname, and it is not a valid refname either, right?\n\nDidn't we discuss a separate topic to teach verify_filename/non_filename\nto optionally look into the index? If we did that, perhaps we do not even\nneed 3/4, no?\n\nWe could make it the caller's responsibility to run read_cache() before\ncalling these two functions (verify_filename() and verify_non_filename()\nwill just use active_cache[] without reading the index themselves).\nAlternatively, we could add a new option \"use_index\" (0: do not use index\nat all, 1: run read_cache() to the_index and use it for checking, 2: run\nread_index() on a temporary in-core index, use it for checking and then\ndiscard the temporary in-core index to keep them free of side-effect) to\nthem. I haven't looked at all the call sites of them to see which one is\nbetter, though.\n"},{"id":"153837","messageId":"20101019232647.GA6198@burratino","threadId":"25473","inReplyTo":"7vzku9ye5k.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 4/4] reset: accept \"git reset HEAD \" from unborn branch","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-19T23:26:47Z","receivedAt":"2010-10-19T23:26:47Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n> Jonathan Nieder writes:\n\n>> \tgit add .\n>> \trm ; # bad file!\n>> \tgit reset \n>>\n>> git will respond by informing me that this use of is\n>> ambiguous.\n>\n> Which is fixed by 3/4.\n\nNo, I didn't fix that.\n\nWhat 3/4 allows is\n\n\tgit reset -- \n\nThe explicit \"--\" is required in the case where that file is not\npresent on disk.\n\n>> ... So I might try to disambiguate:\n>>\n>> \tgit reset HEAD \n>\n> I however do not think this is sane, as you are _explicitly_ referring to\n> HEAD, saying \"I want to pull this out of the commit pointed by the HEAD\",\n> while there is _no such commit_. Sounds somewhat insane.\n\nYes, makes sense. I started out thinking of HEAD as a sort of\nabstract symbol (like the occasionally-proposed INDEX) but it probably\nis better to get used to it just being a reference early on.\n\n> But why is path1 ambiguous in the first place? It is because it is not\n> considered to be a pathname, and it is not a valid refname either, right?\n>\n> Didn't we discuss a separate topic to teach verify_filename/non_filename\n> to optionally look into the index? If we did that, perhaps we do not even\n> need 3/4, no?\n\nThat would eliminate the need for 4/4, I think. Thanks for the pointers.\n"},{"id":"153862","messageId":"BED961D6-5C2A-4535-B706-BFB9727CE398@gmail.com","threadId":"25473","inReplyTo":"vpq8w1v5gce.fsf@bauges.imag.fr","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Thore Husfeldt","fromEmail":"thore.husfeldt@gmail.com","sentAt":"2010-10-20T09:53:52Z","receivedAt":"2010-10-20T09:53:52Z","isPatch":false,"sender":{"key":"thore.husfeldt@gmail.com","avatar":"https://gravatar.com/avatar/d09b67dd2db2b4213ff54d74d8db9d0dd2830a92b60bea8828ce3132cdf8b853?d=mp&s=160"},"body":"On 18 Oct 2010, at 23:41, Matthieu Moy wrote:\n\n> We already came up with a better wording, namely \"upstream\", and used\n> in in \"git push --set-upstream\". Probably a next step would be to\n> deprecate any other occurence of --track meaning the same thing (git\n> checkout --track seems to me to be a candidate, git branch has both\n> --track and --set-upstream). One difficulty is to do that with\n> backward compatibility in mind.\n\nI’ve tried to play around with this concept now, *in casu* by trying to edit the Pro Git source.\n\nI’m not sure we all agree on what is what, so let me try to clarify.\n\nIn the following, Alice has bobsstuff, bob/master, and (Bob’s) master, which she got from\n\n> alice% git checkout --track -b bobsstuff bob/master\n\n(Or using `git branch`). Git tells her that\n\n> Branch bobsstuff set up to track remote branch master from bob.\n\n(By the way, I think “remote branch” is useful and correct, here.)\n\nLet me see if I can use the proposed terminology:\n\n1. bob/master *tracks* master.\n2. bob/master is a remote-tracking branch\n3. master is a remote branch\n4. bob/master has been marked as \"upstream\" from bobsstuff \n\nIs master upstream from bobbstuff as well? The man page of `git branch` seems to think so:\n\n> Furthermore, it directs git pull without arguments to pull from the upstream when the new branch is checked out.\n\nSo both bob/master and master are sometimes called \"upstream\", and both bobsstuff and bob/master are sometimes called \"tracking\".\n\nLet‘s try to look at the relevant Pro Git section, to get a feeling for how this terminology work when you actually try to explain something well:\n> \n> ### Tracking Branches ###\n> \n> Checking out a local branch from a remote branch automatically creates what is called a _tracking branch_. Tracking branches are local branches that have a direct relationship to a remote branch. If you’re on a tracking branch and type git push, Git automatically knows which server and branch to push to. Also, running `git pull` while on one of these branches fetches all the remote references and then automatically merges in the corresponding remote branch.\n> \n> When you clone a repository, it generally automatically creates a `master` branch that tracks `origin/master`. That’s why `git push` and `git pull` work out of the box with no other arguments. However, you can set up other tracking branches if you wish — ones that don’t track branches on `origin` and don’t track the `master` branch. The simple case is the example you just saw, running `git checkout -b [branch] [remotename]/[branch]`. If you have Git version 1.6.2 or later, you can also use the `--track` shorthand:\n\nThis is a good section, and explains a lot. But, as with much of the Git documentation, the terminology is undisciplined. Take “tracking branches”. The section is about refs like bobbstuff, which is no longer called tracking, but “a branch that has been configured to set up an upstream relation”. Currently, if I understand the proposed terminology, there is no word for what the Pro Git book calls “tracking branches.” (I’d be happy to be wrong about this.)\n\nLet me try\n\n> ### Upstream branches ###\n> \n> A local branch can be set up in a direct relationship to a remote branch; we say the that the remote branch is _upstream_. In this configuration, if you type `git push`, Git automatically knows which server and branch to push to. Also, running `git pull` on one of these branches fetches all the remote references and then automatically merges in the corresponding remote branch.\n> \n> When you clone a repository, Git automatically creates a `master` branch whose upstream branch is the remote-tracking branch `origin/master`.\n\nThis is not really good, because the immediately preceding section is about “remote-tracking branches” (currently called “remote branches”, by the way). And “remote-tracking branches” and “upstream branches” are the same – they both refer to bob/master, but from different perspectives. Now there are two sections about bob/master, yet the conceptually interesting branches are bobsstuff (sometimes called the “tracking branch”) and master (sometimes called the “remote branch”). bob/master is just an elegant implementation that facilitates the communication between these two branches. (This is not impossible to fix with a good rewrite.)\n\nI’d be really happy to rewrite the documentation about this stuff (including submitting a patch to Pro Git and other useful references), but my enthusiasm is tempered by a nagging suspicion that the full terminological effect of no longer having a word for the kind of branch that bobsstuff is has been fully realised. "},{"id":"153864","messageId":"vpqfww1ksh7.fsf@bauges.imag.fr","threadId":"25473","inReplyTo":"BED961D6-5C2A-4535-B706-BFB9727CE398@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-10-20T11:34:44Z","receivedAt":"2010-10-20T11:34:44Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Thore Husfeldt writes:\n\n>> Branch bobsstuff set up to track remote branch master from bob.\n>\n> (By the way, I think “remote branch” is useful and correct, here.)\n\nBut \"track\" should be \"upstream\" here to be consistant with\n\"--set-upstream\". Maybe:\n\nRemote branch master from bob set as upstream for bobsstuff.\n\n?\n\n> Let me see if I can use the proposed terminology:\n>\n> 1. bob/master *tracks* master.\n> 2. bob/master is a remote-tracking branch\n\nI do like the dash between remote and tracking.\n\nThis is roughly the current terminology, but as you pointed out, it's\nnot used consistantly in the doc.\n\n> 3. master is a remote branch\n> 4. bob/master has been marked as \"upstream\" from bobsstuff \n\nThat's my understanding too.\n\n(no time for more detailed answer, sorry)\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"153868","messageId":"1287583319.16585.4.camel@drew-northup.unet.maine.edu","threadId":"25473","inReplyTo":"vpqfww1ksh7.fsf@bauges.imag.fr","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-10-20T14:01:59Z","receivedAt":"2010-10-20T14:01:59Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Wed, 2010-10-20 at 13:34 +0200, Matthieu Moy wrote:\n> Thore Husfeldt writes:\n\n> > Let me see if I can use the proposed terminology:\n> >\n> > 1. bob/master *tracks* master.\n> > 2. bob/master is a remote-tracking branch\n> \n> I do like the dash between remote and tracking.\n> \n> This is roughly the current terminology, but as you pointed out, it's\n> not used consistantly in the doc.\n\nThe only way in which \"tracking\" is not consistent is in that many\npeople seem to be insisting that one cannot apply the idiom of tracking\nto ALL kinds of tracking that git does. Git tracks changes in CONTENT.\nIt matters not where that content is. It does not track files, branches,\nnor repositories--those are mere containers of CONTENT that git tracks\nthe changes of.\nPerhaps we need to make this more explicit in the documentation?\n\n-- \n-Drew Northup\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"153946","messageId":"4CBFFD79.1010808@alum.mit.edu","threadId":"25473","inReplyTo":"m3ocar5fmo.fsf@localhost.localdomain","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2010-10-21T08:44:41Z","receivedAt":"2010-10-21T08:44:41Z","isPatch":false,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 10/18/2010 11:57 PM, Jakub Narebski wrote:\n> Well, there is different suggestion: make `git stage`, `git track` and\n> `git mark-resolved` to be *specializations* of `git add`, with added\n> safety checks: 'git stage' would work only on files known to git /\n> under version control already, 'git track' would work only on\n> untracked files (and do what 'git add -N' does), and 'git mark-resolved'\n> would work only on files which were part of a merge conflict.\n\nI think that is a great idea. The thing that I found most confusing\nwhen learning git is that variations on a single command often have very\ndifferent effects. My pet peeve is the over-versatile \"git checkout\":\n\ngit checkout BRANCH : Check out a branch. This is the functionality\nthat I would expect from a \"checkout\" command.\n\ngit checkout -b NEWBRANCH OLDBRANCH : For me this was unintuitive,\nbecause (IMO) the main effect of the command is to create a new branch.\n (I consider that more significant than the checkout because it has a\npersistent effect on the repository.) Therefore, I would expect this\nfunctionality to be provided by \"git branch\" (something like \"git branch\n--checkout NEWBRANCH OLDBRANCH\").\n\ngit checkout -b NEWBRANCH : This is even more unintuitive, because no\ncontent is being checked out at all. This should be written \"git branch\n--checkout NEWBRANCH\".\n\ngit checkout -- PATH : To me this is again a totally different\noperation. The other uses of \"git checkout\" are safe; they don't lose\nany information. But this usage discards the working copy changes\nirretrievably. Such a different operation deserves a different command\nwith a \"dangerous-sounding\" name. I think this functionality should be\nmade more easily accessible via \"git reset\", as has been suggested\nelsewhere on this thread. (Unfortunately \"git revert\" is already taken.)\n\ngit checkout BRANCH -- PATH : This is even more perverse. Usually\n\"check out\" makes the working copy more similar to a version in the\nrepository. But this command makes it more different.\n\nMichael\n\n-- \nMichael Haggerty\nmhagger@alum.mit.edu\nhttp://softwareswirl.blogspot.com/\n"},{"id":"153950","messageId":"1287660007.24161.10.camel@drew-northup.unet.maine.edu","threadId":"25473","inReplyTo":"4CBFFD79.1010808@alum.mit.edu","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-10-21T11:20:07Z","receivedAt":"2010-10-21T11:20:07Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Thu, 2010-10-21 at 10:44 +0200, Michael Haggerty wrote:\n> On 10/18/2010 11:57 PM, Jakub Narebski wrote:\n> > Well, there is different suggestion: make `git stage`, `git track` and\n> > `git mark-resolved` to be *specializations* of `git add`, with added\n> > safety checks: 'git stage' would work only on files known to git /\n> > under version control already, 'git track' would work only on\n> > untracked files (and do what 'git add -N' does), and 'git mark-resolved'\n> > would work only on files which were part of a merge conflict.\n> \n> I think that is a great idea. The thing that I found most confusing\n> when learning git is that variations on a single command often have very\n> different effects. \n\nOk, so what will \"git stage\" do when a change of a file is already\nstaged and it is executed again (on new changes)? The point of \"git add\"\nis that it is adding the current state to the index, not that it is\nadding a file to version control (in contrast to most other VCS/SCM).\nAdding a \"git stage\" that acts as if \"git add\" permanently adds a file\nto version control merely confuses this issue in my opinion.\n\n(Comments about checkout will come in another message, granted I come up\nwith the time to write them down...)\n\n-- \n-Drew Northup\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"153952","messageId":"968F09BD-2B2D-44C4-9C0F-BF7BD20041F0@gmail.com","threadId":"25473","inReplyTo":"1287660007.24161.10.camel@drew-northup.unet.maine.edu","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Thore Husfeldt","fromEmail":"thore.husfeldt@gmail.com","sentAt":"2010-10-21T12:31:25Z","receivedAt":"2010-10-21T12:31:25Z","isPatch":false,"sender":{"key":"thore.husfeldt@gmail.com","avatar":"https://gravatar.com/avatar/d09b67dd2db2b4213ff54d74d8db9d0dd2830a92b60bea8828ce3132cdf8b853?d=mp&s=160"},"body":"\nOn 21 Oct 2010, at 13:20, Drew Northup wrote:\n\n> Ok, so what will \"git stage\" do when a change of a file is already\n> staged and it is executed again (on new changes)?\n\nPresumably what it already does: nothing. But one could argue that the more public-relations minded command “git stage” should give better feedback. Like so:\n\n> $ git commit \n> $ ... edit A.txt ...\n> $ git stage B.txt\n> git stage: Did nothing. No uncommitted changes to stage in B.txt.\n> $ git stage A.txt\n> $ git stage A.txt\n> git stage: Did nothing. Changes in A.txt already staged. Use `git diff --staged A.txt` to see them.\n"},{"id":"153957","messageId":"1287665760.24161.33.camel@drew-northup.unet.maine.edu","threadId":"25473","inReplyTo":"968F09BD-2B2D-44C4-9C0F-BF7BD20041F0@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-10-21T12:56:00Z","receivedAt":"2010-10-21T12:56:00Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Thu, 2010-10-21 at 14:31 +0200, Thore Husfeldt wrote:\n> On 21 Oct 2010, at 13:20, Drew Northup wrote:\n> \n> > Ok, so what will \"git stage\" do when a change of a file is already\n> > staged and it is executed again (on new changes)?\n> \n> Presumably what it already does: nothing. But one could argue that the more public-relations minded command “git stage” should give better feedback. Like so:\n> \n> > $ git commit \n> > $ ... edit A.txt ...\n> > $ git stage B.txt\n> > git stage: Did nothing. No uncommitted changes to stage in B.txt.\n> > $ git stage A.txt\n> > $ git stage A.txt\n> > git stage: Did nothing. Changes in A.txt already staged. Use `git diff --staged A.txt` to see them.\n\nThat's not what I asked.\n\n$ git commit\n$ vim A.txt\n$ vim B.txt\n$ git add B.txt\n$ git add A.txt\n$ vim B.txt\n$ git add B.txt\n\nThe above sequence stages two changes on B.txt into the index.\nLiterally, it adds changes to git's knowledge about B.txt twice, but\ndoes not yet commit any of it permanently to the object store.\n\nPresumably, assuming that A.txt and B.txt did not yet exist, you are\nsuggesting the following command sequence:\n\n$ git commit\n$ vim A.txt\n$ vim B.txt\n$ git add B.txt\n$ git add A.txt\n$ vim B.txt\n$ git stage B.txt\n$ vim B.txt\n$ git stage B.txt\n\nThis assumes that git SHOULD act like subversion, and I argue that there\nis no reason that it should. What happens if we continue as follows:\n\n$ vim A.txt\n$ git stage A.txt\n$ git commit\n$ vim C.txt\n$ vim A.txt\n$ git stage A.txt\n$ git stage C.txt\n\nShould the last two commands fail? The earlier discussion seems to\nsuggest that they should. My point is that this does not seem to me to\nbe a useful extension of the idiom. If anything, it seems to confuse the\nmatter. Now, if \"git stage\" were an outright replacement for \"git add\"\nthere might be more use (but I'd still not be happy about the corruption\nof the idiom).\n\n-- \n-Drew Northup\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"153964","messageId":"EE0A3DAA-DFE8-4F70-B321-0B1CA63B1341@gmail.com","threadId":"25473","inReplyTo":"1287665760.24161.33.camel@drew-northup.unet.maine.edu","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Thore Husfeldt","fromEmail":"thore.husfeldt@gmail.com","sentAt":"2010-10-21T14:06:15Z","receivedAt":"2010-10-21T14:06:15Z","isPatch":false,"sender":{"key":"thore.husfeldt@gmail.com","avatar":"https://gravatar.com/avatar/d09b67dd2db2b4213ff54d74d8db9d0dd2830a92b60bea8828ce3132cdf8b853?d=mp&s=160"},"body":"On 21 Oct 2010, at 14:56, Drew Northup wrote:\n\n> That's not what I asked.\n> [... good, concrete example omitted...]\n> \n> $ vim A.txt\n> $ git stage A.txt\n> $ git commit\n> $ vim C.txt\n> $ vim A.txt\n> $ git stage A.txt\n> $ git stage C.txt\n> \n> Should the last two commands fail?\n\nNo, not for me. (Is this in reaction to Jakub’s suggestion that an “untracked file”, like C.txt, cannot be staged before explicitly tracked?)\n\nMaybe this is what should happen:\n\n$ git stage C.txt\ngit stage: Contents of previously untracked file C.txt staged for next commit\n\n> Now, if \"git stage\" were an outright replacement for \"git add\"\n> there might be more use (but I'd still not be happy about the corruption\n> of the idiom).\n\nI tend to agree. But look at, e.g., Figure 2.1 in the Pro Git book http://progit.org/book/ch2-2.html . That view strongly enforces that something special happens to the new “pink” file, different from what happens to a “yellow” file. After this helpful discussion, I don’t like figure 2.1 so much anymore. A red arrow should go from “pink” to “blue” with text “stage the file”."},{"id":"154015","messageId":"1287691602.24161.67.camel@drew-northup.unet.maine.edu","threadId":"25473","inReplyTo":"EE0A3DAA-DFE8-4F70-B321-0B1CA63B1341@gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-10-21T20:06:42Z","receivedAt":"2010-10-21T20:06:42Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Thu, 2010-10-21 at 16:06 +0200, Thore Husfeldt wrote:\n> On 21 Oct 2010, at 14:56, Drew Northup wrote:\n> \n> > That's not what I asked.\n> > [... good, concrete example omitted...]\n> > \n> > $ vim A.txt\n> > $ git stage A.txt\n> > $ git commit\n> > $ vim C.txt\n> > $ vim A.txt\n> > $ git stage A.txt\n> > $ git stage C.txt\n> > \n> > Should the last two commands fail?\n> \n> No, not for me. (Is this in reaction to Jakub’s suggestion that an\n> “untracked file”, like C.txt, cannot be staged before explicitly\n> tracked?)\n\nI hadn't read any of his comments to mean that, but I could be missing\nsomething...\nMore than anything else I was trying to feel out possible workflow\nissues. A lot of people are going to (continue? to) confuse \"git add\"\nand \"svn add\" if we don't make very explicit what we are up to. As you\nare not suggesting we outright replace \"git add\" I wanted to be very\nsure as to what you mean to do.\n\n> Maybe this is what should happen:\n> \n> $ git stage C.txt\n> git stage: Contents of previously untracked file C.txt staged for next commit\n\nThis is reasonable. I would probably say \"...untracked file C.txt added\nto index and staged for next commit\" to emphasize the existing \"git add\"\nidiom, but that may be superfluous.\n\n> > Now, if \"git stage\" were an outright replacement for \"git add\"\n> > there might be more use (but I'd still not be happy about the corruption\n> > of the idiom).\n> \n> I tend to agree. But look at, e.g., Figure 2.1 in the Pro Git book\n> http://progit.org/book/ch2-2.html . That view strongly enforces that\n> something special happens to the new “pink” file, different from what\n> happens to a “yellow” file. After this helpful discussion, I don’t\n> like figure 2.1 so much anymore. A red arrow should go from “pink” to\n> “blue” with text “stage the file”.\n\nI can see why this would get your attention. I have to admit I ignored\nit because it didn't match-up with the bulk of documentation in any way\nI had yet made sense of. Once I had made sense of the idiom and looked\nback at the graphic I shrugged and wondered why the author had chosen to\nillustrate it that way.\n\n-- \n-Drew Northup N1XIM\n AKA RvnPhnx on OPN\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"154093","messageId":"buoeibi6fab.fsf@dhlpc061.dev.necel.com","threadId":"25473","inReplyTo":"1287660007.24161.10.camel@drew-northup.unet.maine.edu","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Miles Bader","fromEmail":"miles@gnu.org","sentAt":"2010-10-22T04:07:56Z","receivedAt":"2010-10-22T04:07:56Z","isPatch":false,"sender":{"key":"miles@gnu.org","avatar":"https://gravatar.com/avatar/01069b69593af7bff28e2f97afeb3644ae6fe2f5f56cb3a8cf34c5fb8c36efe5?d=mp&s=160"},"body":"Drew Northup writes:\n> Ok, so what will \"git stage\" do when a change of a file is already\n> staged and it is executed again (on new changes)?\n\nIt stages the newly updated file?\n\nThis seems entirely obvious and intuitive, far more so than \"git add\"...\n\n-Miles\n\n-- \nHappiness, n. An agreeable sensation arising from contemplating the misery of\nanother.\n"},{"id":"154139","messageId":"1287748264.31218.18.camel@drew-northup.unet.maine.edu","threadId":"25473","inReplyTo":"buoeibi6fab.fsf@dhlpc061.dev.necel.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-10-22T11:51:04Z","receivedAt":"2010-10-22T11:51:04Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Fri, 2010-10-22 at 13:07 +0900, Miles Bader wrote:\n> Drew Northup writes:\n> > Ok, so what will \"git stage\" do when a change of a file is already\n> > staged and it is executed again (on new changes)?\n> \n> It stages the newly updated file?\n> \n> This seems entirely obvious and intuitive, far more so than \"git add\"...\n\nWhether \"git add\" or \"git stage\" makes any sense (or either one more\nthan the other) depends on the user having some specific knowledge of\nhow VCS/SCM works and in particular some knowledge specific to git. For\nme, \"git add\" was virtually automatic having had some exposure to CVS\nand SVN (thankfully CVS only in the past!). Once I got to the part of\nthe instructions where it was made clear that git does not PERPETUALLY\nAND AUTOMATICALLY CAPTURE the state of CONTENT known to it the idiom of\n\"git add\" working to ADD THE CURRENT STATE of content in a file made\nperfect sense to me.\nThe idiom of \"git stage\" is likewise. One must understand that in git\nall changes must be staged to the index manually before they can be\nacted upon in a commit.\nNeither one is particularly obvious to somebody who hasn't attempted to\nunderstand how git works yet--just as the traffic concept of\nright-of-way oft befuddles teenagers as if they were martians visiting\nTimes Square.\n\nWhat I was asking, specifically, was how \"git stage\" was to act in the\ngiven scenario. In particular I wanted to make sure that the workflow of\n\"make known to git, modify, add/stage changes to index, , commit, etc.\" did not change to include some sort of\nPERPETUAL AUTOMATIC TRACKING as done with CVS/SVN (and frankly at times\na rather annoying prospect). Obviously I could not just ask that\noutright and expect to get some idea of what my interlocutor was\nthinking and how he internally conceived the idiom as well as an answer\nto the direct question at hand.\n\nHow's that for a long answer to a seemingly simple question?\n\n-- \n-Drew Northup N1XIM\n AKA RvnPhnx on OPN\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"154203","messageId":"1287778585.2025.14.camel@localhost.localdomain","threadId":"25473","inReplyTo":"AANLkTinGuVm8gib9r7omVV9hHw8B-iBQGgsv+b6wb5=Q@mail.gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Paul Bolle","fromEmail":"pebolle@tiscali.nl","sentAt":"2010-10-22T20:16:25Z","receivedAt":"2010-10-22T20:16:25Z","isPatch":false,"sender":{"key":"pebolle@tiscali.nl","avatar":null},"body":"On Tue, 2010-10-19 at 11:09 -0400, Eugene Sajine wrote:\n> There should be some different consistent and not inter-crossing\n> naming for the origin's master branch (on the remote side), for the\n> local origin/master and for local master that is a tracking branch.\n> The only way i found so far to explain this is actually via the naming\n> syntax where having / in the name of the branch means remote branch. I\n> was a bit surprised that i can create a local branch with a slash in\n> the name - probably it should be prohibited.\n\nAllowing local branches with a slash in their name is a feature I use\nheavily. Ie, in general my local repositories use this scheme:\n\n$ git branch\n* master\n $BRANCH_F00\n $USER/$TOPIC_FOO\n $USER/$TOPIC_BAR\n [...]\n $USER/$TOPIC_BAZ\n\nThis makes it trivial to quickly distinguish my (local) work from other\npeople's (remote) work. Does the benefit of naming clarity justify\nprohibiting that scheme?\n\n\nPaul Bolle\n"},{"id":"154206","messageId":"AANLkTinUc2BW+BOTNMOC1t=3=rYzYgedyS5LFu37J+Yo@mail.gmail.com","threadId":"25473","inReplyTo":"1287778585.2025.14.camel@localhost.localdomain","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Eugene Sajine","fromEmail":"euguess@gmail.com","sentAt":"2010-10-22T21:00:43Z","receivedAt":"2010-10-22T21:00:43Z","isPatch":false,"sender":{"key":"euguess@gmail.com","avatar":null},"body":"On Fri, Oct 22, 2010 at 4:16 PM, Paul Bolle wrote:\n> On Tue, 2010-10-19 at 11:09 -0400, Eugene Sajine wrote:\n>> There should be some different consistent and not inter-crossing\n>> naming for the origin's master branch (on the remote side), for the\n>> local origin/master and for local master that is a tracking branch.\n>> The only way i found so far to explain this is actually via the naming\n>> syntax where having / in the name of the branch means remote branch. I\n>> was a bit surprised that i can create a local branch with a slash in\n>> the name - probably it should be prohibited.\n>\n> Allowing local branches with a slash in their name is a feature I use\n> heavily. Ie, in general my local repositories use this scheme:\n>\n> $ git branch\n> * master\n>  $BRANCH_F00\n>  $USER/$TOPIC_FOO\n>  $USER/$TOPIC_BAR\n>  [...]\n>  $USER/$TOPIC_BAZ\n>\n> This makes it trivial to quickly distinguish my (local) work from other\n> people's (remote) work. Does the benefit of naming clarity justify\n> prohibiting that scheme?\n>\n>\n> Paul Bolle\n>\n>\n\nWell, my approach is to use:\nmaster - local\nmybranch - local\n\nremote from user\n$ git remote add jdoe ~jdoe/project/.git\n\nThen remote-tracking branches will be\njdoe/master\njdoe/featurex\n\nmy local branches tracking remote-tracking branches (automatic push, pull)\njd_master\njd_featurex\n\nin this case there is no confusion between jdoe/master that is a\nremote-tracking branch checkout to which will lead to detached HEAD\nstate and jd_master that is a local branch.\n\nAs in this syntax the slash is that meaningful, i think that reserving\nthis syntax \"remote/branch\" to the remote-tracking branches only makes\nsense.\n\nThanks,\nEugene\n"},{"id":"154211","messageId":"1287783988.819.19.camel@drew-northup.unet.maine.edu","threadId":"25473","inReplyTo":"AANLkTinUc2BW+BOTNMOC1t=3=rYzYgedyS5LFu37J+Yo@mail.gmail.com","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-10-22T21:46:28Z","receivedAt":"2010-10-22T21:46:28Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Fri, 2010-10-22 at 17:00 -0400, Eugene Sajine wrote:\n> On Fri, Oct 22, 2010 at 4:16 PM, Paul Bolle wrote:\n> > On Tue, 2010-10-19 at 11:09 -0400, Eugene Sajine wrote:\n> >> There should be some different consistent and not inter-crossing\n> >> naming for the origin's master branch (on the remote side), for the\n> >> local origin/master and for local master that is a tracking branch.\n> >> The only way i found so far to explain this is actually via the naming\n> >> syntax where having / in the name of the branch means remote branch. I\n> >> was a bit surprised that i can create a local branch with a slash in\n> >> the name - probably it should be prohibited.\n> >\n> > Allowing local branches with a slash in their name is a feature I use\n> > heavily. Ie, in general my local repositories use this scheme:\n> >\n> > $ git branch\n> > * master\n> > $BRANCH_F00\n> > $USER/$TOPIC_FOO\n> > $USER/$TOPIC_BAR\n> > [...]\n> > $USER/$TOPIC_BAZ\n> >\n> > This makes it trivial to quickly distinguish my (local) work from other\n> > people's (remote) work. Does the benefit of naming clarity justify\n> > prohibiting that scheme?\n> >\n> >\n> > Paul Bolle\n> >\n> >\n> \n> Well, my approach is to use:\n> master - local\n> mybranch - local\n> \n> remote from user\n> $ git remote add jdoe ~jdoe/project/.git\n> \n> Then remote-tracking branches will be\n> jdoe/master\n> jdoe/featurex\n> \n> my local branches tracking remote-tracking branches (automatic push, pull)\n> jd_master\n> jd_featurex\n> \n> in this case there is no confusion between jdoe/master that is a\n> remote-tracking branch checkout to which will lead to detached HEAD\n> state and jd_master that is a local branch.\n> \n> As in this syntax the slash is that meaningful, i think that reserving\n> this syntax \"remote/branch\" to the remote-tracking branches only makes\n> sense.\n\nI think that leaving it as is, wherein the \"/\" is not a special\ncharacter that SPECIFICALLY means remote is just fine. If people choose\nto use that by convention that's dandy as well, but I don't see any\npoint in forcing it.\n\n-- \n-Drew Northup N1XIM\n AKA RvnPhnx on OPN\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"154529","messageId":"20101027145548.GA1136@kytes","threadId":"25473","inReplyTo":"1287499168-26569-1-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH v3] Porcelain scripts: Rewrite cryptic \"needs update\" error message","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-10-27T14:55:51Z","receivedAt":"2010-10-27T14:55:51Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\nRamkumar Ramachandra writes:\n> Although Git interally has the facility to differentiate between\n> porcelain and plubmbing commands and appropriately print errors,\n> several shell scripts invoke plubming commands triggering cryptic\n> plumbing errors to be displayed on a porcelain interface. This patch\n> replaces the \"needs update\" message in git-pull and git-rebase, when\n> `git update-index` is run, with a more friendly message.\n> \n> Reported-by: Joshua Jensen \n> Reported-by: Thore Husfeldt \n> Signed-off-by: Ramkumar Ramachandra \n> ---\n> Ref: <1285877017-8060-1-git-send-email-artagnon@gmail.com> for v2.\n> Ref: <1285514516-5112-1-git-send-email-artagnon@gmail.com> for v1.\n> \n> Thanks to Matthieu for reviewing v1 and Junio for reviewing v2: I've\n> tried to attack the problem more conservatively in this patch. It\n> doesn't list paths, and doesn't print \"generic\" advice.\n\nJunio: Is this patch alright?\n\n-- Ram\n"},{"id":"154537","messageId":"20101027150314.GB1136@kytes","threadId":"25473","inReplyTo":"20101019175103.GA28847@kytes","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-10-27T15:03:19Z","receivedAt":"2010-10-27T15:03:19Z","isPatch":false,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\nRamkumar Ramachandra writes:\n> From a863e58d240956191c2fa9cbe992aaca5786730b Mon Sep 17 00:00:00 2001\n> From: Ramkumar Ramachandra \n> Date: Tue, 19 Oct 2010 22:42:05 +0530\n> Subject: [PATCH] Documentation: Consistently use the hyphenated \"remote-tracking\"\n> \n> Replace instances of the term \"remote tracking\" with \"remote-tracking\"\n> in the documentation for clarity.\n> \n> Reported-by: Thore Husfeldt \n> Signed-off-by: Ramkumar Ramachandra \n\nand\n\n> From 7422c2af1ef40c922d8f628715ad96172e4a5734 Mon Sep 17 00:00:00 2001\n> From: Ramkumar Ramachandra \n> Date: Tue, 19 Oct 2010 23:16:04 +0530\n> Subject: [PATCH] UI: Don't say \"working directory\" when we really mean \"working tree\"\n> \n> While in some places \"working directory\" is used to refer to the\n> (current) working directory, it's incorrectly used in places where Git\n> actually means \"working tree\" or worktree. Weed out and replace these\n> instances in the UI.\n> \n> Reported-by: Thore Husfeldt \n> Signed-off-by: Ramkumar Ramachandra \n\nJunio: Are these patches suitable for inclusion?\n\n-- Ram\n"},{"id":"154541","messageId":"1288192595.15518.37.camel@drew-northup.unet.maine.edu","threadId":"25473","inReplyTo":"20101027150314.GB1136@kytes","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-10-27T15:16:35Z","receivedAt":"2010-10-27T15:16:35Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Wed, 2010-10-27 at 20:33 +0530, Ramkumar Ramachandra wrote:\n> Hi,\n> \n> Ramkumar Ramachandra writes:\n> > From a863e58d240956191c2fa9cbe992aaca5786730b Mon Sep 17 00:00:00 2001\n> > From: Ramkumar Ramachandra \n> > Date: Tue, 19 Oct 2010 22:42:05 +0530\n> > Subject: [PATCH] Documentation: Consistently use the hyphenated \"remote-tracking\"\n> > \n> > Replace instances of the term \"remote tracking\" with \"remote-tracking\"\n> > in the documentation for clarity.\n> > \n> > Reported-by: Thore Husfeldt \n> > Signed-off-by: Ramkumar Ramachandra \n> \n> and\n> \n> > From 7422c2af1ef40c922d8f628715ad96172e4a5734 Mon Sep 17 00:00:00 2001\n> > From: Ramkumar Ramachandra \n> > Date: Tue, 19 Oct 2010 23:16:04 +0530\n> > Subject: [PATCH] UI: Don't say \"working directory\" when we really mean \"working tree\"\n> > \n> > While in some places \"working directory\" is used to refer to the\n> > (current) working directory, it's incorrectly used in places where Git\n> > actually means \"working tree\" or worktree. Weed out and replace these\n> > instances in the UI.\n> > \n> > Reported-by: Thore Husfeldt \n> > Signed-off-by: Ramkumar Ramachandra \n> \n> Junio: Are these patches suitable for inclusion?\n> \n> -- Ram\n\nRam,\nMatthieu has been working on a more comprehensive set of documentation\npatches--which I'm pretty sure include all of the changes you just\nmentioned.\n\n\n-- \n-Drew Northup N1XIM\n AKA RvnPhnx on OPN\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"154548","messageId":"vpqwrp3y5wp.fsf@bauges.imag.fr","threadId":"25473","inReplyTo":"1288192595.15518.37.camel@drew-northup.unet.maine.edu","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-10-27T16:08:54Z","receivedAt":"2010-10-27T16:08:54Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Drew Northup writes:\n\n> Matthieu has been working on a more comprehensive set of documentation\n> patches\n\nRight. I had missed your patches and our works overlapped.\n\n> --which I'm pretty sure include all of the changes you just\n> mentioned.\n\nNot all:\n\n>> > Subject: [PATCH] Documentation: Consistently use the hyphenated \"remote-tracking\"\n\nThis (and other \"synonyms\" of remote-tracking) is addressed by my\npatch, but\n\n>> > Subject: [PATCH] UI: Don't say \"working directory\" when we really\n>> > mean \"working tree\"\n\nthis isn't.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"154634","messageId":"20101028152053.GA29091@kytes","threadId":"25473","inReplyTo":"vpqwrp3y5wp.fsf@bauges.imag.fr","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-10-28T15:20:56Z","receivedAt":"2010-10-28T15:20:56Z","isPatch":false,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi Matthieu,\n\nMatthieu Moy writes:\n> Drew Northup writes:\n> \n> > Matthieu has been working on a more comprehensive set of documentation\n> > patches\n> \n> Right. I had missed your patches and our works overlapped.\n\nAh, I saw your huge series on the list. Looks like it needs to be\nre-rolled after the reviews?\n\n> > --which I'm pretty sure include all of the changes you just\n> > mentioned.\n> \n> Not all:\n> \n> >> > Subject: [PATCH] Documentation: Consistently use the hyphenated \"remote-tracking\"\n> \n> This (and other \"synonyms\" of remote-tracking) is addressed by my\n> patch, but\n\nOk, we can drop this patch then- your version is more complete.\n\n> >> > Subject: [PATCH] UI: Don't say \"working directory\" when we really\n> >> > mean \"working tree\"\n> \n> this isn't.\n\nYou might like to include it in your next re-roll or just leave it as\nan independent patch for Junio to pick up.\n\n-- Ram\n"},{"id":"154652","messageId":"vpqvd4mi37s.fsf@bauges.imag.fr","threadId":"25473","inReplyTo":"20101028152053.GA29091@kytes","subject":"Re: Git terminology: remote, add, track, stage, etc.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-10-28T18:25:59Z","receivedAt":"2010-10-28T18:25:59Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Ramkumar Ramachandra writes:\n\n>> >> > Subject: [PATCH] UI: Don't say \"working directory\" when we really\n>> >> > mean \"working tree\"\n>> \n>> this isn't.\n>\n> You might like to include it in your next re-roll or just leave it as\n> an independent patch for Junio to pick up.\n\nI'd rather keep it separate. My patch serie is already large enough\n(and the patches do not really have dependancies, so we can as well\nlet them find their way in pu/next/master separately).\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"155271","messageId":"7v39rfs8f1.fsf@alter.siamese.dyndns.org","threadId":"25473","inReplyTo":"20101027145548.GA1136@kytes","subject":"Re: [PATCH v3] Porcelain scripts: Rewrite cryptic \"needs update\" error message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-11-05T22:38:26Z","receivedAt":"2010-11-05T22:38:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> Ramkumar Ramachandra writes:\n>> Although Git interally has the facility to differentiate between\n>> porcelain and plubmbing commands and appropriately print errors,\n>> several shell scripts invoke plubming commands triggering cryptic\n>> plumbing errors to be displayed on a porcelain interface. This patch\n>> replaces the \"needs update\" message in git-pull and git-rebase, when\n>> `git update-index` is run, with a more friendly message.\n>> \n>> Reported-by: Joshua Jensen \n>> Reported-by: Thore Husfeldt \n>> Signed-off-by: Ramkumar Ramachandra \n>> ---\n>> Ref: <1285877017-8060-1-git-send-email-artagnon@gmail.com> for v2.\n>> Ref: <1285514516-5112-1-git-send-email-artagnon@gmail.com> for v1.\n>> \n>> Thanks to Matthieu for reviewing v1 and Junio for reviewing v2: I've\n>> tried to attack the problem more conservatively in this patch. It\n>> doesn't list paths, and doesn't print \"generic\" advice.\n>\n> Junio: Is this patch alright?\n\nI did not see anything glaringly wrong in the patch offhand. The new\nmessages look a bit too verbose, though.\n\nWill queue and see what people would say.\n"},{"id":"160966","messageId":"AANLkTikuQdJykM7MUV=C5DR7HO5xseBifrY_w2ZWsCiR@mail.gmail.com","threadId":"25473","inReplyTo":"1287499168-26569-1-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH v3] Porcelain scripts: Rewrite cryptic \"needs update\" error message","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2011-02-12T23:14:22Z","receivedAt":"2011-02-12T23:14:22Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Tue, Oct 19, 2010 at 16:39, Ramkumar Ramachandra wrote:\n\n> -               git update-index --ignore-submodules --refresh &&\n> -               git diff-files --ignore-submodules --quiet &&\n> -               git diff-index --ignore-submodules --cached --quiet HEAD -- ||\n> -               die \"refusing to pull with rebase: your working tree is not up-to-date\"\n> +               require_clean_work_tree \"pull with rebase\" \"Please commit or stash them.\"\n\nDoing this sort of thing is basically incompatible with doing\ni18n. I'll work around this when rebasing the ab/i18n series, but in\nthe long term we shouldn't be doing stuff like this.\n"}]}