{"thread":{"id":"17096","subject":"[RFC PATCH 2/3] Add specification of git-vcs helpers","startedAt":"2009-01-11T20:12:08Z","lastAt":"2009-01-12T17:46:21Z","messageCount":5,"participants":["Daniel Barkalow","Junio C Hamano","Johannes Sixt"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"99994","messageId":"alpine.LNX.1.00.0901110334350.19665@iabervon.org","threadId":"17096","inReplyTo":null,"subject":"[RFC PATCH 2/3] Add specification of git-vcs helpers","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2009-01-11T20:12:08Z","receivedAt":"2009-01-11T20:12:08Z","isPatch":true,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"So far, I've actually used list and import; I've also implemented an \nexport, but haven't figured out exactly how the user should cause it to be \nused.\n\nSigned-off-by: Daniel Barkalow \n---\n Documentation/git-vcs.txt | 93 +++++++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 93 insertions(+), 0 deletions(-)\n create mode 100644 Documentation/git-vcs.txt\n\ndiff --git a/Documentation/git-vcs.txt b/Documentation/git-vcs.txt\nnew file mode 100644\nindex 0000000..fa02b76\n--- /dev/null\n+++ b/Documentation/git-vcs.txt\n@@ -0,0 +1,93 @@\n+git-vcs-*(1)\n+============\n+\n+NAME\n+----\n+git-vcs-* - Helper programs for interoperation with foreign systems\n+\n+SYNOPSIS\n+--------\n+'git vcs-' [options] [arguments]\n+\n+DESCRIPTION\n+-----------\n+\n+These programs are normally not used directly by end users, but are\n+invoked by various git programs that interact with remote repositories\n+when the repository they would operate on is part of a foreign\n+system.\n+\n+Each 'git vcs-' is a helper for interoperating with a\n+particular version control system. Different helpers have different\n+capabilities (limited both be the particular helper and by the\n+capabilities of the system they connect to), and they report what\n+capabilities they support.\n+\n+In general, these programs interact with a portion of the refs\n+namespace that isn't used by the rest of git. The configuration will\n+then (generally) map these refs into the remotes namespace. This\n+allows the importer to do whatever it wants with its refs without\n+affecting the state visible to normal git programs.\n+\n+COMMANDS\n+--------\n+\n+'capabilities'::\n+\tPrints the capabilities of the helper, one per line. These are:\n+\t - import: the basic import command\n+\t - marks: import should be done with a saved marks file\n+\t - find-new-branches: detect new branches\n+\t - export: the general export command\n+\t - fork: create a new branch and export to it\n+\t - anonymous-fork: make commits on a branch without an inherent name\n+\t - merge: merge branches (of whatever type the system supports)\n+\n+\tIf the helper doesn't support \"merge\", the default for pull is\n+\tto rebase instead of merging.\n+\n+'list'::\n+\tTakes the remote name, and outputs the names of refs. These\n+\tmay be followed, after a single space, by \"changed\" or\n+\t\"unchanged\", indicating whether the foreign repository has\n+\tchanged from the state in the ref. If the helper doesn't know,\n+\tit doesn't have to provide a value. (In particular, it\n+\tshouldn't do expensive operations, such as importing the\n+\tcontent, to see whether it matches.)\n+\n+'import'::\n+\tTakes the remote name and a list of names of refs, and imports\n+\twhatever it describes, by outputting it in git-fast-import\n+\tformat.\n+\n+'export'::\n+\tSends the branch to the foreign system and reimports it in\n+\tfast-import format.\n+\n+\tReads a list of commits from stdin, where each commit has no\n+\tparents which were neither produced by an earlier import nor\n+\tappearing earlier in the list, where some commit has the old\n+\tvalue of the branch as a parent, and where all commits listed\n+\tare ancestors of the last one. Furthermore:\n+\n+\t - if the system doesn't support merges, each of these commits\n+\t has only a single parent;\n+\n+\t - if the system doesn't support anonymous branches, the first\n+\t commit has the old value of the branch as a parent (if the\n+\t branch already had a value), and all parents are either the\n+\t commit listed immediately before or produced by an earlier\n+\t import;\n+\n+\t - if the system doesn't support many-way merges, each commit\n+\t has at most two parents.\n+\n+\texport produces output in fast-import format giving the\n+\tcontent after a round-trip through the foreign system. This\n+\talso contains extra headers to report the mapping of original\n+\tgit commits to reimported git commits (to facilitate rewriting\n+\tlocal branches to use the history-as-reimported instead of the\n+\tgit-only version).\n+\n+\texport reports how much it managed to export by producing\n+\tcommits in the fast-import stream that replace the listed\n+\titems that were successfully exported.\n-- \n1.6.0.6\n"},{"id":"100048","messageId":"7vk591mhwj.fsf@gitster.siamese.dyndns.org","threadId":"17096","inReplyTo":"alpine.LNX.1.00.0901110334350.19665@iabervon.org","subject":"Re: [RFC PATCH 2/3] Add specification of git-vcs helpers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-01-12T01:29:00Z","receivedAt":"2009-01-12T01:29:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Daniel Barkalow writes:\n\n> So far, I've actually used list and import; I've also implemented an \n> export, but haven't figured out exactly how the user should cause it to be \n> used.\n> ...\n> +'capabilities'::\n> +\tPrints the capabilities of the helper, one per line. These are:\n> +\t - import: the basic import command\n> +\t - marks: import should be done with a saved marks file\n> +\t - find-new-branches: detect new branches\n> +\t - export: the general export command\n> +\t - fork: create a new branch and export to it\n> +\t - anonymous-fork: make commits on a branch without an inherent name\n> +\t - merge: merge branches (of whatever type the system supports)\n> +\n> +\tIf the helper doesn't support \"merge\", the default for pull is\n> +\tto rebase instead of merging.\n\nHave you tried formatting this to both html and man? I think you need to\ndedent the second paragraph, and have '+' as the sole character on a line\nimmediately before, without any blank lines. The formatted output of the\ndescription of 'export' is probably more troublesome as it is much longer.\n\nThis list feels like overengineered yet without enough thinking behind it.\n\nYour 'list' allows to list what can become branches on the git end, so as\nlong as you have tracking information on the git side, find-new-branches\nseems unnecessary, for examle. Worse, find-new-branches needs its own\ntracking mechansim anyway, but that means how the namespace for remote\ntracking branches is managed is left to the vcs backends, even though that\nnamespace is directly visiblt to git --- my gut feeling is that it would\nprobably better to arrange things similar to what git native transport\ndoes already. 'list' would say \"The remote has what can become refs on\nthe git end and calls them A, B, C\", and the built-in code, using ref\nmapping specification, maps them to refs/remotes/somename/{A,B,C}. You do\nit again and if you see the remote has D but does not have B anymore, you\nknow D is a new branch and B was deleted.\n\nWhat does 'merge' mean? It cannot mean to fetch their changes from\nforeign vcs and create a merge locally (you only need import from the\nbackend, and merge will be a usual git merge). Perhaps you meant if you\ncan export a merge back? Some foreign systems may support importing\nmerges but not octopus, so it may not be just a black-or-white boolean.\n\nAlso \"the default is to rebase instead of merge\" is probably too weak.\nYou would want to error out if the user tried to merge, wouldn't you?\n\n> +'list'::\n> +\tTakes the remote name, and outputs the names of refs. These\n> +\tmay be followed, after a single space, by \"changed\" or\n> +\t\"unchanged\", indicating whether the foreign repository has\n> +\tchanged from the state in the ref. If the helper doesn't know,\n> +\tit doesn't have to provide a value. (In particular, it\n> +\tshouldn't do expensive operations, such as importing the\n> +\tcontent, to see whether it matches.)\n\nI am guessing by 'a value' you mean 'changed/unchanged', iow you are not\nsaying if the helper does not know it can omit such refs from the list,\nbut it is unclear.\n"},{"id":"100056","messageId":"alpine.LNX.1.00.0901112033070.19665@iabervon.org","threadId":"17096","inReplyTo":"7vk591mhwj.fsf@gitster.siamese.dyndns.org","subject":"Re: [RFC PATCH 2/3] Add specification of git-vcs helpers","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2009-01-12T02:03:45Z","receivedAt":"2009-01-12T02:03:45Z","isPatch":true,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Sun, 11 Jan 2009, Junio C Hamano wrote:\n\n> Daniel Barkalow writes:\n> \n> > So far, I've actually used list and import; I've also implemented an \n> > export, but haven't figured out exactly how the user should cause it to be \n> > used.\n> > ...\n> > +'capabilities'::\n> > +\tPrints the capabilities of the helper, one per line. These are:\n> > +\t - import: the basic import command\n> > +\t - marks: import should be done with a saved marks file\n> > +\t - find-new-branches: detect new branches\n> > +\t - export: the general export command\n> > +\t - fork: create a new branch and export to it\n> > +\t - anonymous-fork: make commits on a branch without an inherent name\n> > +\t - merge: merge branches (of whatever type the system supports)\n> > +\n> > +\tIf the helper doesn't support \"merge\", the default for pull is\n> > +\tto rebase instead of merging.\n> \n> Have you tried formatting this to both html and man? I think you need to\n> dedent the second paragraph, and have '+' as the sole character on a line\n> immediately before, without any blank lines. The formatted output of the\n> description of 'export' is probably more troublesome as it is much longer.\n\nNope, I've just been referring to it in the original text, so I've been \ncareless with markup.\n\n> This list feels like overengineered yet without enough thinking behind it.\n\nYeah, I haven't really nailed this one down; it's hard to get really right \nwithout having a bunch of different helpers which can do different amounts \nof stuff and need different git-side help.\n\n> Your 'list' allows to list what can become branches on the git end, so as\n> long as you have tracking information on the git side, find-new-branches\n> seems unnecessary, for examle.\n\nI was unclear about what that one meant, I guess. It's supposed to handle \nsystems where it's possible to create things that work like branches but \nare hard to find. If a helper doesn't report the capability, then the user \nmay need to say, \"I also want some/branch/location\", or the helper \nwouldn't know that's a branch.\n\nFor example, in order to find all of the branches in Perforce, you have \nto figure out both directions of integration, in order to find branches \nthat haven't been integrated back into the location you know about, and \nthat's kind of expensive to determine and a bit tricky to parse.\n\nIt's not intended to indicate that the helper will tell you which ones are \nnew or not, just that, if the helper doesn't have it, it will only tell \nyou about branches that it's been told about.\n\n> What does 'merge' mean? It cannot mean to fetch their changes from\n> foreign vcs and create a merge locally (you only need import from the\n> backend, and merge will be a usual git merge). Perhaps you meant if you\n> can export a merge back? Some foreign systems may support importing\n> merges but not octopus, so it may not be just a black-or-white boolean.\n\nIf the helper supports \"merge\", it means that it is able to create a merge \nin the foreign vcs. You're right about needing to separately list an \n\"octopus\" capability, and maybe further refinements.\n\n> Also \"the default is to rebase instead of merge\" is probably too weak.\n> You would want to error out if the user tried to merge, wouldn't you?\n\nI think users should be able to create merges in git if they want to, but \nthey'd have to linearize the history in order to push it back. Hopefully, \nat some point, we'll have a tool to help with this (which would be helpful \nfor generating patch series, anyway).\n\n> > +'list'::\n> > +\tTakes the remote name, and outputs the names of refs. These\n> > +\tmay be followed, after a single space, by \"changed\" or\n> > +\t\"unchanged\", indicating whether the foreign repository has\n> > +\tchanged from the state in the ref. If the helper doesn't know,\n> > +\tit doesn't have to provide a value. (In particular, it\n> > +\tshouldn't do expensive operations, such as importing the\n> > +\tcontent, to see whether it matches.)\n> \n> I am guessing by 'a value' you mean 'changed/unchanged', iow you are not\n> saying if the helper does not know it can omit such refs from the list,\n> but it is unclear.\n\nYeah, that's what I meant.\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"100080","messageId":"496AFB8D.4000803@viscovery.net","threadId":"17096","inReplyTo":"alpine.LNX.1.00.0901110334350.19665@iabervon.org","subject":"Re: [RFC PATCH 2/3] Add specification of git-vcs helpers","fromName":"Johannes Sixt","fromEmail":"j.sixt@viscovery.net","sentAt":"2009-01-12T08:13:01Z","receivedAt":"2009-01-12T08:13:01Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Daniel Barkalow schrieb:\n> +NAME\n> +----\n> +git-vcs-* - Helper programs for interoperation with foreign systems\n> +\n> +SYNOPSIS\n> +--------\n> +'git vcs-' [options] [arguments]\n\nThe current rule is that helper programs have double-dash in the name:\ngit-rebase--interactive, git-web--browse, etc.\n\n-- Hannes\n"},{"id":"100143","messageId":"alpine.LNX.1.00.0901121228331.19665@iabervon.org","threadId":"17096","inReplyTo":"496AFB8D.4000803@viscovery.net","subject":"Re: [RFC PATCH 2/3] Add specification of git-vcs helpers","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2009-01-12T17:46:21Z","receivedAt":"2009-01-12T17:46:21Z","isPatch":true,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Mon, 12 Jan 2009, Johannes Sixt wrote:\n\n> Daniel Barkalow schrieb:\n> > +NAME\n> > +----\n> > +git-vcs-* - Helper programs for interoperation with foreign systems\n> > +\n> > +SYNOPSIS\n> > +--------\n> > +'git vcs-' [options] [arguments]\n> \n> The current rule is that helper programs have double-dash in the name:\n> git-rebase--interactive, git-web--browse, etc.\n\nI'm not entirely sure if these are helper programs in that sense, or \nreally what the distinction is between these and regular plumbing. \nMultiple programs will be calling them, and they'll have a specified API, \nin any case. (I think the double-dash programs are ones where all of the \ncall sites are internal, so both the API and all the users can be changed \ntogether.)\n\n\t-Daniel\n*This .sig left intentionally blank*\n"}]}