{"thread":{"id":"10844","subject":"[PATCH] user-manual: Talk about tracking third-party snapshots","startedAt":"2007-11-13T12:29:59Z","lastAt":"2007-11-19T01:17:01Z","messageCount":12,"participants":["Michael Smith","Jakub Narebski","Sergei Organov","Junio C Hamano","Jan Hudec","J. Bruce Fields"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"59662","messageId":"11949569992214-git-send-email-msmith@cbnco.com","threadId":"10844","inReplyTo":null,"subject":"[PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Michael Smith","fromEmail":"msmith@cbnco.com","sentAt":"2007-11-13T12:29:59Z","receivedAt":"2007-11-13T12:29:59Z","isPatch":true,"sender":{"key":"msmith@cbnco.com","avatar":null},"body":"Add some sections about tracking third-party sources to the advanced\nbranching chapter. This might save some guesswork for tasks like\nimporting snapshots and tracking local changes.\n\nSigned-off-by: Michael Smith <msmith@cbnco.com>\n---\n\nYears of heavy CVS abuse left me partly brain damaged, and some things that\nare pretty easy in Git seemed like they should have been more complicated.\nHopefully this should make it painfully obvious how do to the equivalent\nof CVS vendor branches.\n\n Documentation/user-manual.txt |  139 +++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 139 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex d99adc6..942f851 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -2711,6 +2711,145 @@ gitlink:git-config[1].\n See gitlink:git-config[1] for more details on the configuration\n options mentioned above.\n \n+[[tracking-sources]]\n+Tracking local changes to third-party sources\n+---------------------------------------------\n+\n+[[tracking-sources-git]]\n+Tracking changes when the upstream is a Git repository\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+You don't have to do anything special to keep track of your changes to a\n+Git project. All you need is a remote tracking branch for the upstream\n+repository--either one of the remote branches created by\n+gitlink:git-clone[1], or one you created according to\n+<<fetching-individual-branches>>.\n+\n+Given a situation where you've merged the tracking branch's changes into\n+your local branch, then made some more changes, as in the diagram below:\n+\n+................................................\n+ o--o--a--c--e--f--g <-- origin/master (remote tracking branch)\n+        \\     \\\n+         b--d--m--h--i <-- master\n+................................................\n+\n+You can view all your local changes--b, d, h, and i--with the\n+gitlink:git-diff[1] command:\n+\n+------------------------------------------\n+$ git diff origin/master...master\n+------------------------------------------\n+\n+The three-dot `\\...` tells gitlink:git-diff[1] to show the changes on the\n+master branch since the last common ancestor with origin/master. (If you\n+used two dots instead of three, you'd see the entire patch to go from\n+origin/master to master, including reversing commits \"f\" and \"g\".)\n+\n+You can use the gitlink:git-cherry[1] command to display the commit\n+IDs that are only present on your local branch, or only on the remote\n+branch, respectively:\n+\n+------------------------------------------------\n+$ git cherry -v origin/master master\n++ 8ed8ff9315e36824e601659b168bbaad5e4d53ca b\n++ 2bf7cdf2bef8e6f8b213634ce67dd01cc9e145e0 d\n++ 14f97309ca82f742bc42d03fa4619a81973521a9 h\n++ 4497730f04ed9849c807f2a5bf8f097f87636d3f i\n+$ git cherry -v master origin/master\n++ 8cc12a9763279d6f0c913ef47e0a996193aaa1c5 f\n++ c793ea90311db286c0e22d227b494f09620aef3d g\n+------------------------------------------------\n+\n+`git show <commit-id>` can display the full log message and patch for you.\n+\n+[[tracking-sources-snapshots]]\n+Tracking changes when the upstream uses snapshots\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+To track your changes to projects that aren't using Git, you can commit\n+a snapshot or release onto a branch in your repository, then tag it. If\n+you are used to vendor branches in CVS, you'll find this is similar,\n+although CVS combines the commit, tag, and sometimes merge operations\n+into one \"import\" command. Here's an example:\n+\n+------------------------------------------------\n+$ mkdir project\n+$ cd project\n+$ git init\n+$ cp -a ~/src/project-1.0/* .\n+$ git add .\n+$ git commit -m \"Import Project v1.0\"\n+$ git tag v1.0\n+$ git branch upstream\n+------------------------------------------------\n+\n+Make your changes as usual on the \"master\" branch, or on topic branches\n+that you merge to \"master\". For the next import, switch to the\n+\"upstream\" branch, commit the new version, then switch back and merge in\n+the changes:\n+\n+------------------------------------------------\n+$ git checkout upstream\n+$ rm -r *\n+$ cp -a ~/src/project-1.1/* .\n+      # \"git add .\" will catch the added and modified files\n+$ git add .\n+      # the \"-a\" flag will commit file deletions, too\n+$ git commit -a -m \"Import Project v1.1\"\n+$ git tag v1.1\n+$ git checkout master\n+$ git merge upstream\n+------------------------------------------------\n+\n+If you are publishing your repository, you may also want to push the\n+\"upstream\" branch and your tags.\n+\n+[[fixing-branch-ancestry]]\n+Fixing branch ancestry\n+~~~~~~~~~~~~~~~~~~~~~~\n+\n+Git can only do a sensible merge if it knows about a common ancestor\n+between your local changes and the third-party sources. It needs to know\n+the commit where your local changes and the third-party sources began to\n+diverge--in other words, the last time they were merged. There are some\n+cases where Git might not have a record of this merge:\n+\n+1. You imported CVS or Subversion vendor branch history into Git.\n+Sometimes this can produce completely independent master and vendor\n+branches with no merging between the two. All the changes are there,\n+they just aren't linked by a merge. You can see this in `gitk --all` as\n+two parallel development histories.\n+2. You've been importing third-party tarballs or snapshots into Git, but\n+now the upstream has switched to Git and you want to pull from their new\n+repository. As far as Git knows, their branch is completely independent\n+from yours, with no common ancestry.\n+\n+You can fix situations like these by doing a merge that isn't really a\n+merge, using the \"ours\" merge strategy. Look through the history on the\n+third-party branch and try to find the exact commit that matches the\n+last snapshot you imported. Often there's a tag close to the commit, or\n+on the commit, if you're lucky--but don't trust it blindly; check the\n+diffs. Check out your local branch and tell Git about the relationship:\n+\n+------------------------------------------------\n+$ git remote add upstreamgit git://upstream.org/project.git\n+$ git fetch upstreamgit\n+$ git tag\n+v1.0\n+v1.1\n+v1.2\n+$ git checkout master\n+$ git merge --strategy=ours \\\n+    -m \"Tie old v1.1 into our history by merging with strategy=ours.\" \\\n+    v1.1\n+------------------------------------------------\n+\n+You'll see the branches merge together in `gitk --all` or `git\n+show-branch master upstreamgit/master`.  Now you'll be able to merge any\n+changes from the remote branch since v1.1 with `git merge\n+upstreamgit/master`.\n+\n \n [[git-concepts]]\n Git concepts\n-- \n1.5.3.2.102.ge6eb7\n"},{"id":"59664","messageId":"fhcb29$ef$2@ger.gmane.org","threadId":"10844","inReplyTo":"11949569992214-git-send-email-msmith@cbnco.com","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-13T14:07:05Z","receivedAt":"2007-11-13T14:07:05Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Michael Smith wrote:\n\n> +You can use the gitlink:git-cherry[1] command to display the commit\n> +IDs that are only present on your local branch, or only on the remote\n> +branch, respectively:\n\nI think git-cherry is deprecated in favor of \"git log --left-right\" (with\nappropriate format, for example '--abbrev-commit --pretty=oneline')\n\nBTW. that means that git-cherry can be removed from git-help output,\nI think.\n\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"59672","messageId":"87zlxi88op.fsf@osv.gnss.ru","threadId":"10844","inReplyTo":"fhcb29$ef$2@ger.gmane.org","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2007-11-13T15:30:14Z","receivedAt":"2007-11-13T15:30:14Z","isPatch":true,"sender":{"key":"osv@javad.com","avatar":null},"body":"Jakub Narebski <jnareb@gmail.com> writes:\n\n> Michael Smith wrote:\n>\n>> +You can use the gitlink:git-cherry[1] command to display the commit\n>> +IDs that are only present on your local branch, or only on the remote\n>> +branch, respectively:\n>\n> I think git-cherry is deprecated in favor of \"git log --left-right\" (with\n> appropriate format, for example '--abbrev-commit --pretty=oneline')\n>\n> BTW. that means that git-cherry can be removed from git-help output,\n> I think.\n\nAnd from core-tutorial.txt:1567:\n\n4. Use `git cherry origin` to see which ones of your patches\n   were accepted, and/or use `git rebase origin` to port your\n   unmerged changes forward to the updated upstream.\n\n???\n\n-- \nSergei.\n"},{"id":"59673","messageId":"200711131638.50437.jnareb@gmail.com","threadId":"10844","inReplyTo":"87zlxi88op.fsf@osv.gnss.ru","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-13T15:38:50Z","receivedAt":"2007-11-13T15:38:50Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Sergei Organov wrote:\n> Jakub Narebski <jnareb@gmail.com> writes:\n> \n>> Michael Smith wrote:\n>>\n>>> +You can use the gitlink:git-cherry[1] command to display the commit\n>>> +IDs that are only present on your local branch, or only on the remote\n>>> +branch, respectively:\n>>\n>> I think git-cherry is deprecated in favor of \"git log --left-right\" (with\n>> appropriate format, for example '--abbrev-commit --pretty=oneline')\n>>\n>> BTW. that means that git-cherry can be removed from git-help output,\n>> I think.\n> \n> And from core-tutorial.txt:1567:\n> \n> 4. Use `git cherry origin` to see which ones of your patches\n>    were accepted, and/or use `git rebase origin` to port your\n>    unmerged changes forward to the updated upstream.\n> \n> ???\n\nOn one hand, core-tutorial is old documentation, dating before\n--left-right option to git-log.\n\nOn the other hand I have forgot that git-cherry does more throghout\nchecking if patch was accepted upstream (by checking changeset).\n\n\nSorry for the noise...\n-- \nJakub Narebski\nPoland\n"},{"id":"59700","messageId":"7vtznqrlrb.fsf@gitster.siamese.dyndns.org","threadId":"10844","inReplyTo":"11949569992214-git-send-email-msmith@cbnco.com","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-13T19:25:12Z","receivedAt":"2007-11-13T19:25:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael Smith <msmith@cbnco.com> writes:\n\n> +You can fix situations like these by doing a merge that isn't really a\n> +merge, using the \"ours\" merge strategy. Look through the history on the\n> +third-party branch and try to find the exact commit that matches the\n> +last snapshot you imported. Often there's a tag close to the commit, or\n> +on the commit, if you're lucky--but don't trust it blindly; check the\n> +diffs. Check out your local branch and tell Git about the relationship:\n> +\n> +------------------------------------------------\n> +$ git remote add upstreamgit git://upstream.org/project.git\n> +$ git fetch upstreamgit\n> +$ git tag\n> +v1.0\n> +v1.1\n> +v1.2\n> +$ git checkout master\n> +$ git merge --strategy=ours \\\n> +    -m \"Tie old v1.1 into our history by merging with strategy=ours.\" \\\n> +    v1.1\n> +------------------------------------------------\n> +\n> +You'll see the branches merge together in `gitk --all` or `git\n> +show-branch master upstreamgit/master`.  Now you'll be able to merge any\n> +changes from the remote branch since v1.1 with `git merge\n> +upstreamgit/master`.\n> +\n\nThis would work only when your 'master' happens to be at v1.1\n(and identical to it) isn't it?  Which means that as an example\nit will be of very limited scope.\n\nPeople would want to know \"But my 'master' is _not_ at v1.1 but\nis _based_ on v1.1.  How would I handle that case?\" and the\nabove does not answer that question.\n\nEven worse, most people are probably not careful enough to ask\nthe above question, but just say \"Heh, my 'master' is based on\nv1.1, so I'll blindly follow that example to bind the histories\ntogether\".\n\nI did not find any technical problem in the other parts of your\ndescription, but I did not read the resulting document from\ncover to cover, so I do not know if your change fits in the\nentire organization of the document very well.\n"},{"id":"59739","messageId":"Pine.LNX.4.64.0711131617580.4038@juice.ott.cti.com","threadId":"10844","inReplyTo":"7vtznqrlrb.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Michael Smith","fromEmail":"msmith@cbnco.com","sentAt":"2007-11-13T21:37:32Z","receivedAt":"2007-11-13T21:37:32Z","isPatch":true,"sender":{"key":"msmith@cbnco.com","avatar":null},"body":"On Tue, 13 Nov 2007, Junio C Hamano wrote:\n\n> > +$ git checkout master\n> > +$ git merge --strategy=ours \\\n> > +    -m \"Tie old v1.1 into our history by merging with strategy=ours.\" \\\n> > +    v1.1\n\n> This would work only when your 'master' happens to be at v1.1\n> (and identical to it) isn't it?\n> \n> People would want to know \"But my 'master' is _not_ at v1.1 but\n> is _based_ on v1.1.  How would I handle that case?\"\n\nThat was actually my case - my master was based on v1.1. The command \nworked for me - I was able to merge in v1.2 from Git afterward - but maybe \nI just got lucky, so I'd be interested to know the right thing to do.\n\nI think --strategy=ours just leaves the files as is on master and creates \na merge commit with two parents: master and v1.1. So anything between v1.1 \nand v1.2, on the upstream branch, is fair game to be merged next time.\n\nSo, say I started with this:\n\n---------------\nold snapshot branch: snap-v1.0---snap-v1.1\n                       \\           \\\nmaster:                 o---o---o---o--o-o\n\nnew Git upstream: o--o-v1.0-o-o-o-o-o-o-v1.1-o-o-v1.2\n---------------\n\nI could make the merge with --strategy=ours:\n---------------\nold snapshot branch: snap-v1.0---snap-v1.1\n                       \\           \\\nmaster:                 o---o---o---o--o-o--o\n                                           /\nnew Git upstream: o--o-v1.0-o-o-o-o-o-o-v1.1-o-o-v1.2\n---------------\n\n\nThen I'd free to merge in v1.2:\n---------------\nmaster:                 o---o---o---o--o-o--o------o\n                                           /      /\nnew Git upstream: o--o-v1.0-o-o-o-o-o-o-v1.1-o-o-v1.2\n---------------\n\nHmm, looks like a toothbrush. But is it right?\n\nMike\n"},{"id":"60150","messageId":"20071117164501.GB5198@efreet.light.src","threadId":"10844","inReplyTo":"fhcb29$ef$2@ger.gmane.org","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Jan Hudec","fromEmail":"bulb@ucw.cz","sentAt":"2007-11-17T16:45:01Z","receivedAt":"2007-11-17T16:45:01Z","isPatch":true,"sender":{"key":"bulb@ucw.cz","avatar":null},"body":"On Tue, Nov 13, 2007 at 15:07:05 +0100, Jakub Narebski wrote:\n> Michael Smith wrote:\n> \n> > +You can use the gitlink:git-cherry[1] command to display the commit\n> > +IDs that are only present on your local branch, or only on the remote\n> > +branch, respectively:\n> \n> I think git-cherry is deprecated in favor of \"git log --left-right\" (with\n> appropriate format, for example '--abbrev-commit --pretty=oneline')\n\ngit log has such option?\n\n$ man git-log | grep -e --left-right; echo $?\n1\n$ git --version\ngit version 1.5.3.5\n\n-- \n\t\t\t\t\t\t Jan 'Bulb' Hudec <bulb@ucw.cz>\n"},{"id":"60156","messageId":"200711171918.40981.jnareb@gmail.com","threadId":"10844","inReplyTo":"20071117164501.GB5198@efreet.light.src","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-17T18:18:40Z","receivedAt":"2007-11-17T18:18:40Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Sat, Nov 17, 2007, Jan Hudec wrote:\n> On Tue, Nov 13, 2007 at 15:07:05 +0100, Jakub Narebski wrote:\n>> Michael Smith wrote:\n>> \n>>> +You can use the gitlink:git-cherry[1] command to display the commit\n>>> +IDs that are only present on your local branch, or only on the remote\n>>> +branch, respectively:\n>> \n>> I think git-cherry is deprecated in favor of \"git log --left-right\" (with\n>> appropriate format, for example '--abbrev-commit --pretty=oneline')\n\nNot true. git-cherry is more than --left-right, as it checks\nif changesets matches, not if commit id matches.\n\n> git log has such option?\n> \n> $ man git-log | grep -e --left-right; echo $?\n> 1\n> $ git --version\n> git version 1.5.3.5\n\nIt has, although it is hidden in git-rev-list(1) manpage. It is a bit\nobscure corner...\n\n-- \nJakub Narebski\nPoland\n"},{"id":"60160","messageId":"20071117191846.GE5198@efreet.light.src","threadId":"10844","inReplyTo":"200711171918.40981.jnareb@gmail.com","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Jan Hudec","fromEmail":"bulb@ucw.cz","sentAt":"2007-11-17T19:18:46Z","receivedAt":"2007-11-17T19:18:46Z","isPatch":true,"sender":{"key":"bulb@ucw.cz","avatar":null},"body":"On Sat, Nov 17, 2007 at 19:18:40 +0100, Jakub Narebski wrote:\n> On Sat, Nov 17, 2007, Jan Hudec wrote:\n> > On Tue, Nov 13, 2007 at 15:07:05 +0100, Jakub Narebski wrote:\n> >> Michael Smith wrote:\n> >> \n> >>> +You can use the gitlink:git-cherry[1] command to display the commit\n> >>> +IDs that are only present on your local branch, or only on the remote\n> >>> +branch, respectively:\n> >> \n> >> I think git-cherry is deprecated in favor of \"git log --left-right\" (with\n> >> appropriate format, for example '--abbrev-commit --pretty=oneline')\n> \n> Not true. git-cherry is more than --left-right, as it checks\n> if changesets matches, not if commit id matches.\n> \n> > git log has such option?\n> > \n> > $ man git-log | grep -e --left-right; echo $?\n> > 1\n> > $ git --version\n> > git version 1.5.3.5\n> \n> It has, although it is hidden in git-rev-list(1) manpage. It is a bit\n> obscure corner...\n\nI hope the new option parsing ifrastructure will take over quickly and start\nto be used to generate the short help and probably even option section in the\nman pages. It's unfortunately not the only option that is not mentioned in\nthe manual page of a command that has it.\n\n-- \n\t\t\t\t\t\t Jan 'Bulb' Hudec <bulb@ucw.cz>\n"},{"id":"60162","messageId":"200711172054.02746.jnareb@gmail.com","threadId":"10844","inReplyTo":"20071117191846.GE5198@efreet.light.src","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-17T19:54:01Z","receivedAt":"2007-11-17T19:54:01Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jan Hudec wrote:\n> On Sat, Nov 17, 2007 at 19:18:40 +0100, Jakub Narebski wrote:\n>> On Sat, Nov 17, 2007, Jan Hudec wrote:\n\n>>> git log has such option?\n>>> \n>>> $ man git-log | grep -e --left-right; echo $?\n>>> 1\n>>> $ git --version\n>>> git version 1.5.3.5\n>> \n>> It has, although it is hidden in git-rev-list(1) manpage. It is a bit\n>> obscure corner...\n> \n> I hope the new option parsing ifrastructure will take over quickly and start\n> to be used to generate the short help and probably even option section in the\n> man pages. It's unfortunately not the only option that is not mentioned in\n> the manual page of a command that has it.\n\nTruth to be told _this_ one option I don't mean it is only\nin git-rev-parse (which git-log references, together with git-diff)\n\n-- \nJakub Narebski\nPoland\n"},{"id":"60259","messageId":"20071119004828.GB23671@fieldses.org","threadId":"10844","inReplyTo":"11949569992214-git-send-email-msmith@cbnco.com","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-11-19T00:48:28Z","receivedAt":"2007-11-19T00:48:28Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Tue, Nov 13, 2007 at 07:29:59AM -0500, Michael Smith wrote:\n> +You can view all your local changes--b, d, h, and i--with the\n> +gitlink:git-diff[1] command:\n> +\n> +------------------------------------------\n> +$ git diff origin/master...master\n> +------------------------------------------\n> +\n> +The three-dot `\\...` tells gitlink:git-diff[1] to show the changes on the\n> +master branch since the last common ancestor with origin/master. (If you\n> +used two dots instead of three, you'd see the entire patch to go from\n> +origin/master to master, including reversing commits \"f\" and \"g\".)\n\nI missed the \"...\" thing when on my first attempt at the manual.  It\nreally should be mentioned in the \"Generating diffs\" section; I've added\nthe following to my\n\n\tgit://linux-nfs.org/~bfields/git.git maint\n\n--b.\n\n>From 5b98d9bca16e19710380d2d03f704de9eb98621d Mon Sep 17 00:00:00 2001\nFrom: J. Bruce Fields <bfields@citi.umich.edu>\nDate: Sun, 18 Nov 2007 19:18:27 -0500\nSubject: [PATCH] user-manual: mention \"...\" in \"Generating diffs\", etc.\n\nWe should mention the use of the \"...\" syntax for git-diff here.  The\nnote about the difference between diff and the combined output of\ngit-format-patch then no longer fits so well, so remove it.  Add a\nreference to the git-format-patch[1] manpage.\n\nSigned-off-by: J. Bruce Fields <bfields@citi.umich.edu>\n---\n Documentation/user-manual.txt |   15 +++++++++++----\n 1 files changed, 11 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex e399685..c027353 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -658,16 +658,23 @@ gitlink:git-diff[1]:\n $ git diff master..test\n -------------------------------------------------\n \n-Sometimes what you want instead is a set of patches:\n+That will produce the diff between the tips of the two branches.  If\n+you'd prefer to find the diff from their common ancestor to test, you\n+can use three dots instead of two:\n+\n+-------------------------------------------------\n+$ git diff master...test\n+-------------------------------------------------\n+\n+Sometimes what you want instead is a set of patches; for this you can\n+use gitlink:git-format-patch[1]:\n \n -------------------------------------------------\n $ git format-patch master..test\n -------------------------------------------------\n \n will generate a file with a patch for each commit reachable from test\n-but not from master.  Note that if master also has commits which are\n-not reachable from test, then the combined result of these patches\n-will not be the same as the diff produced by the git-diff example.\n+but not from master.\n \n [[viewing-old-file-versions]]\n Viewing old file versions\n-- \n1.5.3.5.561.g140d\n"},{"id":"60261","messageId":"20071119011701.GC23671@fieldses.org","threadId":"10844","inReplyTo":"7vtznqrlrb.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] user-manual: Talk about tracking third-party snapshots","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-11-19T01:17:01Z","receivedAt":"2007-11-19T01:17:01Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Tue, Nov 13, 2007 at 11:25:12AM -0800, Junio C Hamano wrote:\n> Michael Smith <msmith@cbnco.com> writes:\n> \n> > +You can fix situations like these by doing a merge that isn't really a\n> > +merge, using the \"ours\" merge strategy. Look through the history on the\n> > +third-party branch and try to find the exact commit that matches the\n> > +last snapshot you imported. Often there's a tag close to the commit, or\n> > +on the commit, if you're lucky--but don't trust it blindly; check the\n> > +diffs. Check out your local branch and tell Git about the relationship:\n> > +\n> > +------------------------------------------------\n> > +$ git remote add upstreamgit git://upstream.org/project.git\n> > +$ git fetch upstreamgit\n> > +$ git tag\n> > +v1.0\n> > +v1.1\n> > +v1.2\n> > +$ git checkout master\n> > +$ git merge --strategy=ours \\\n> > +    -m \"Tie old v1.1 into our history by merging with strategy=ours.\" \\\n> > +    v1.1\n> > +------------------------------------------------\n> > +\n> > +You'll see the branches merge together in `gitk --all` or `git\n> > +show-branch master upstreamgit/master`.  Now you'll be able to merge any\n> > +changes from the remote branch since v1.1 with `git merge\n> > +upstreamgit/master`.\n> > +\n> \n> This would work only when your 'master' happens to be at v1.1\n> (and identical to it) isn't it?  Which means that as an example\n> it will be of very limited scope.\n> \n> People would want to know \"But my 'master' is _not_ at v1.1 but\n> is _based_ on v1.1.  How would I handle that case?\" and the\n> above does not answer that question.\n> \n> Even worse, most people are probably not careful enough to ask\n> the above question, but just say \"Heh, my 'master' is based on\n> v1.1, so I'll blindly follow that example to bind the histories\n> together\".\n> \n> I did not find any technical problem in the other parts of your\n> description, but I did not read the resulting document from\n> cover to cover, so I do not know if your change fits in the\n> entire organization of the document very well.\n\nA mention of git-cherry or --left-right someplace might make sense,\nmaybe in chapter 2 somewhere (maybe in \"Browsing revisions\"?), but it\nmight also be useful to discuss this kind of stuff in the \"sharing\ndevelopment with others\" section.  (E.g. at the end of \"Submitting\npatches to a project\", it might help to have some hints about how to\nrecognize when they've been accepted and what to do then.)\n\nThe trick of using a merge (possibly with -s ours) to tie together two\nindependent paths to the same state is more generally useful.  (I've\nbeen using it sometimes to keep track of the revision history of a patch\nseries, for example).  I'm not sure where that should go.\n\nI like the tips on importing snapshots or other history.  I've long been\nwanting an \"interoperating with other SCM's\" section (rough beginnings\nat git://linux-nfs.org/~bfields/git.git docwork-foreign-scms), and maybe\nsome of this would fit here.\n\nAll of these things seem more generally useful even to an audience that\nhasn't worked with CVS vendor branches before, so I'd prefer\nexplanations that didn't reference the CVS stuff.  (With CVS-specific\nstuff moved somewhere else, maybe to cvs-migration.txt.)\n\n--b.\n"}]}