{"thread":{"id":"10033","subject":"grafts not appearing in manual pages","startedAt":"2007-09-26T20:24:41Z","lastAt":"2007-09-27T07:25:39Z","messageCount":4,"participants":["Mike Hommey","J. Bruce Fields","Johannes Sixt","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"54115","messageId":"20070926202441.GA31848@glandium.org","threadId":"10033","inReplyTo":null,"subject":"grafts not appearing in manual pages","fromName":"Mike Hommey","fromEmail":"mh@glandium.org","sentAt":"2007-09-26T20:24:41Z","receivedAt":"2007-09-26T20:24:41Z","isPatch":false,"sender":{"key":"mh@glandium.org","avatar":"https://avatars.githubusercontent.com/u/1038527?v=4"},"body":"Hi,\n\nThe only occurrence of grafts in the manual pages is in the\ngit-filter-branch one. I somehow feel this is wrong not to see it\ndescribed more \"formally\" in the manual pages.\n\nI wouldn't mind writing a small something, except I have no idea what\nwould be the most appropriate place to talk about it... Does anyone have\nsuch an idea ?\n\nCheers,\n\nMike\n"},{"id":"54117","messageId":"20070926210102.GF26099@fieldses.org","threadId":"10033","inReplyTo":"20070926202441.GA31848@glandium.org","subject":"Re: grafts not appearing in manual pages","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-09-26T21:01:02Z","receivedAt":"2007-09-26T21:01:02Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Wed, Sep 26, 2007 at 10:24:41PM +0200, Mike Hommey wrote:\n> Hi,\n> \n> The only occurrence of grafts in the manual pages is in the\n> git-filter-branch one. I somehow feel this is wrong not to see it\n> described more \"formally\" in the manual pages.\n> \n> I wouldn't mind writing a small something, except I have no idea what\n> would be the most appropriate place to talk about it... Does anyone have\n> such an idea ?\n\nIt could go in Documentation/user-manual.txt, but I don't know where.\nMaybe at the end of the git-concepts chapter? Patches welcomed. I\nguess what's needed (and currently missing) is an overview explaining\nwhat they're actually for, plus some basic setup instructions.\n\nAnd/or maybe a section 5 manual page documenting the format of the\n\"grafts\" file? Maybe that's overkill. There's a paragraph in\nDocumentation/repository-layout.txt. Maybe we need to make it easier to\nfind that file.\n\n--b.\n"},{"id":"54139","messageId":"46FB4C23.8010400@viscovery.net","threadId":"10033","inReplyTo":"20070926210102.GF26099@fieldses.org","subject":"Re: grafts not appearing in manual pages","fromName":"Johannes Sixt","fromEmail":"j.sixt@viscovery.net","sentAt":"2007-09-27T06:22:27Z","receivedAt":"2007-09-27T06:22:27Z","isPatch":false,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"J. Bruce Fields schrieb:\n> On Wed, Sep 26, 2007 at 10:24:41PM +0200, Mike Hommey wrote:\n>> Hi,\n>>\n>> The only occurrence of grafts in the manual pages is in the\n>> git-filter-branch one. I somehow feel this is wrong not to see it\n>> described more \"formally\" in the manual pages.\n>>\n>> I wouldn't mind writing a small something, except I have no idea what\n>> would be the most appropriate place to talk about it... Does anyone have\n>> such an idea ?\n> \n> It could go in Documentation/user-manual.txt, but I don't know where.\n\nIMHO grafts should not be made known to a wide audience until send-pack, \npack-objects, and prune are fixed so that you cannot corrupt your repository \nwhen there are grafts.\n\nSee http://thread.gmane.org/gmane.comp.version-control.git/37744\nin particular http://article.gmane.org/gmane.comp.version-control.git/37866\non a sketch how to fix the issues.\n\n-- Hannes\n"},{"id":"54144","messageId":"7vmyv8wowc.fsf@gitster.siamese.dyndns.org","threadId":"10033","inReplyTo":"46FB4C23.8010400@viscovery.net","subject":"Re: grafts not appearing in manual pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-09-27T07:25:39Z","receivedAt":"2007-09-27T07:25:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt writes:\n\n> J. Bruce Fields schrieb:\n> ...\n>> It could go in Documentation/user-manual.txt, but I don't know where.\n>\n> IMHO grafts should not be made known to a wide audience until\n> send-pack, pack-objects, and prune are fixed so that you cannot\n> corrupt your repository when there are grafts.\n\nI mildly have to disagree.\n\nDocumenting the current semantics (in short, \"grafts are\nstrictly local matter\") and the implications is important.\n\nHere are some of the points you would want to mention:\n\n - if you graft, prune and fsck will honor that fake ancestry,\n\n - if you _add_ parent by grafting you will not lose the history\n that is otherwise disconnected, but on the other hand, once\n having pruned that way and you remove that graft, prune will\n discard that discontiguous history away.\n\n - if you _hide_ parent by grafting, you will be able to lose\n the hidden subbranch away, but you will get complaints from\n fsck if you remove that graft after pruning your history.\n\n - if you try to fetch/push across repositories with different\n notion of ancestry (because of different grafts), things can\n break in expected ways (and you can keep both halves ;-).\n For example, if the sending side has extra parents to a\n commit compared to the receiving side, and if the receiving\n side claims to have that commit, objects reachable from the\n extra parents might be missing from the reciving end but the\n sender will not be able to notice.\n\n> See http://thread.gmane.org/gmane.comp.version-control.git/37744\n> in particular http://article.gmane.org/gmane.comp.version-control.git/37866\n> on a sketch how to fix the issues.\n\nIIRC, there discussions were more about what the issues are and\nwhat the potential semantics could be. First the desired\nsemantics need to be defined.\n"}]}