{"thread":{"id":"30459","subject":"[PATCH] git-svn: clarify documentation of dcommit sub-command","startedAt":"2012-05-07T13:48:47Z","lastAt":"2012-05-10T19:13:41Z","messageCount":3,"participants":["Jon Seymour","Junio C Hamano","Eric Wong"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"190999","messageId":"1336398527-4363-1-git-send-email-jon.seymour@gmail.com","threadId":"30459","inReplyTo":null,"subject":"[PATCH] git-svn: clarify documentation of dcommit sub-command","fromName":"Jon Seymour","fromEmail":"jon.seymour@gmail.com","sentAt":"2012-05-07T13:48:47Z","receivedAt":"2012-05-07T13:48:47Z","isPatch":true,"sender":{"key":"jon.seymour@gmail.com","avatar":"https://avatars.githubusercontent.com/u/207131?v=4"},"body":"Clarify that the optional \"revision or branch\" argument on dcommit sub-command refers to a\ngit branch not an SVN branch.\n\nIf the user's intent is to commit the current series of commits onto a specific SVN branch\nrather than the trunk, the existing wording might lead them to believe that the optional\nargument may be a means to achieve this.\n\nThe rewording clarifies that the optional argument actually refers to the source git\nbranch, not the target svn branch.\n\nSigned-off-by: Jon Seymour \n---\n Documentation/git-svn.txt | 2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 34ee785..c516283 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -197,7 +197,7 @@ and have no uncommitted changes.\n \tpull or merge) your commits against the latest changes in the\n \tSVN repository.\n \tAn optional revision or branch argument may be specified, and\n-\tcauses 'git svn' to do all work on that revision/branch\n+\tcauses 'git svn' to do all work on that git revision/branch\n \tinstead of HEAD.\n \tThis is advantageous over 'set-tree' (below) because it produces\n \tcleaner, more linear history.\n-- \n1.7.9.264.g3fbfe6\n"},{"id":"191201","messageId":"7vpqadtgpj.fsf@alter.siamese.dyndns.org","threadId":"30459","inReplyTo":"1336398527-4363-1-git-send-email-jon.seymour@gmail.com","subject":"Re: [PATCH] git-svn: clarify documentation of dcommit sub-command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-09T17:19:36Z","receivedAt":"2012-05-09T17:19:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jon Seymour writes:\n\n> Clarify that the optional \"revision or branch\" argument on dcommit\n> sub-command refers to a git branch not an SVN branch.\n>\n> If the user's intent is to commit the current series of commits onto a\n> specific SVN branch rather than the trunk, the existing wording might\n> lead them to believe that the optional argument may be a means to\n> achieve this.\n>\n> The rewording clarifies that the optional argument actually refers to\n> the source git branch, not the target svn branch.\n>\n> Signed-off-by: Jon Seymour \n> ---\n> Documentation/git-svn.txt | 2 +-\n> 1 files changed, 1 insertions(+), 1 deletions(-)\n>\n> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\n> index 34ee785..c516283 100644\n> --- a/Documentation/git-svn.txt\n> +++ b/Documentation/git-svn.txt\n> @@ -197,7 +197,7 @@ and have no uncommitted changes.\n> \tpull or merge) your commits against the latest changes in the\n> \tSVN repository.\n> \tAn optional revision or branch argument may be specified, and\n> -\tcauses 'git svn' to do all work on that revision/branch\n> +\tcauses 'git svn' to do all work on that git revision/branch\n> \tinstead of HEAD.\n> \tThis is advantageous over 'set-tree' (below) because it produces\n> \tcleaner, more linear history.\n\nI was going to apply this to my tree and send a \"Thanks\" with Cc: to Eric\nto avoid double-application, but after reading the above again I started\nto have doubt. If the original were \"on that branch\" and the rephrasing\n\"on that git branch\", I wouldn't have had any issue.\n\nWhen a \"git revision\" and not a \"git branch\" is given as an optional\nargument, what does the subcommand do? Detach HEAD at that revision,\nand do the usual \"rebase on top of svn history and push it back\" dance?\nPerhaps \"instead of HEAD\" may want to be further rephrased, as in that\ncase it indeed is working on HEAD; it is just not the original commit your\nHEAD pointed at before you issued the command.\n\nAlso, wouldn't it be easier to the readers if instead of this patch you\nupdated the beginning of the sentence to read \"An optional git revision or\ngit branch name may be specified\"? After all, that is a more prominent\nplace to catch readers' eyes'.\n\nYet another issue. The entire paragraph begins with this:\n\n Commit each diff from a specified head directly to the SVN\n repository, and then rebase or reset (depending on whether or\n not there is a diff between SVN and head).\n\nWhat is \"a specified head\" here? It makes it sound as if the \"optional\nrevision or branch\" is not optional at all and that is what specifies the\n\"head to be worked on\", but that is not what is happening here, right?\n\nPerhaps something like this?\n\n'dcommit'::\n\tCommit each diff from the current branch directly to the SVN\n\trepository, and then rebase or reset (depending on ...\n\t...\n\tWhen an optional git branch name (or a git commit object name)\n\tis given, the subcommand works on the specified branch, not on\n the current branch.\n"},{"id":"191341","messageId":"20120510191341.GB1715@dcvr.yhbt.net","threadId":"30459","inReplyTo":"7vpqadtgpj.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-svn: clarify documentation of dcommit sub-command","fromName":"Eric Wong","fromEmail":"normalperson@yhbt.net","sentAt":"2012-05-10T19:13:41Z","receivedAt":"2012-05-10T19:13:41Z","isPatch":true,"sender":{"key":"e@80x24.org","avatar":null},"body":"Junio C Hamano wrote:\n> Perhaps something like this?\n> \n> 'dcommit'::\n> \tCommit each diff from the current branch directly to the SVN\n> \trepository, and then rebase or reset (depending on ...\n> \t...\n> \tWhen an optional git branch name (or a git commit object name)\n> \tis given, the subcommand works on the specified branch, not on\n> the current branch.\n\nI think that looks good. Using \"revision\" to mean \"git commit object\"\nwas a confusing mistake in the first place.\n"}]}