{"thread":{"id":"28993","subject":"[PATCH] Documentation update for 'git branch --list'","startedAt":"2011-11-21T14:33:20Z","lastAt":"2011-11-30T05:54:38Z","messageCount":6,"participants":["Vincent van Ravesteijn","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"179784","messageId":"1321886000-4163-1-git-send-email-vfr@lyx.org","threadId":"28993","inReplyTo":null,"subject":"[PATCH] Documentation update for 'git branch --list'","fromName":"Vincent van Ravesteijn","fromEmail":"vfr@lyx.org","sentAt":"2011-11-21T14:33:20Z","receivedAt":"2011-11-21T14:33:20Z","isPatch":true,"sender":{"key":"vfr@lyx.org","avatar":"https://avatars.githubusercontent.com/u/687868?v=4"},"body":"Indicate that the ... argument is only valid when using --list.\nOtherwise a branch with the name will be created. The current\nsynopsis also suggests that 'git branch -d ...' would be a valid\ncommand.\n\nMinor changes:\n- add a period to a sentence,\n- change tag into branch.\n\nSigned-off-by: Vincent van Ravesteijn \n---\n Documentation/git-branch.txt | 11 ++++++-----\n 1 files changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex f46013c..9f49db4 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -9,8 +9,9 @@ SYNOPSIS\n --------\n [verse]\n 'git branch' [--color[=] | --no-color] [-r | -a]\n-\t[--list] [-v [--abbrev= | --no-abbrev]]\n-\t[(--merged | --no-merged | --contains) []] [...]\n+\t[-v [--abbrev= | --no-abbrev]]\n+\t[(--merged | --no-merged | --contains) []]\n+\t[--list [...]]\n 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] []\n 'git branch' (-m | -M) [] \n 'git branch' (-d | -D) [-r] ...\n@@ -23,8 +24,8 @@ be highlighted with an asterisk. Option `-r` causes the remote-tracking\n branches to be listed, and option `-a` shows both. This list mode is also\n activated by the `--list` option (see below).\n restricts the output to matching branches, the pattern is a shell\n-wildcard (i.e., matched using fnmatch(3))\n-Multiple patterns may be given; if any of them matches, the tag is shown.\n+wildcard (i.e., matched using fnmatch(3)).\n+Multiple patterns may be given; if any of them matches, the branch is shown.\n \n With `--contains`, shows only the branches that contain the named commit\n (in other words, the branches whose tip commits are descendants of the\n@@ -114,7 +115,7 @@ OPTIONS\n --all::\n \tList both remote-tracking branches and local branches.\n \n---list::\n+--list [...]::\n \tActivate the list mode. `git branch ` would try to create a branch,\n \tuse `git branch --list ` to list matching branches.\n \n-- \n1.7.4.1\n"},{"id":"179785","messageId":"4ECA678B.5050508@lyx.org","threadId":"28993","inReplyTo":"1321886000-4163-1-git-send-email-vfr@lyx.org","subject":"Re: [PATCH] Documentation update for 'git branch --list'","fromName":"Vincent van Ravesteijn","fromEmail":"vfr@lyx.org","sentAt":"2011-11-21T15:00:27Z","receivedAt":"2011-11-21T15:00:27Z","isPatch":true,"sender":{"key":"vfr@lyx.org","avatar":"https://avatars.githubusercontent.com/u/687868?v=4"},"body":"\n> The current synopsis also suggests that 'git branch -d...'\n> would be a valid command.\n\nWell.. that's a lie.\n\nVincent\n"},{"id":"179794","messageId":"7v7h2tgyw6.fsf@alter.siamese.dyndns.org","threadId":"28993","inReplyTo":"1321886000-4163-1-git-send-email-vfr@lyx.org","subject":"Re: [PATCH] Documentation update for 'git branch --list'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-11-21T17:37:29Z","receivedAt":"2011-11-21T17:37:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Vincent van Ravesteijn writes:\n\n> Indicate that the ... argument is only valid when using --list.\n> Otherwise a branch with the name will be created.\n\nI actually think there are some bugs in the implementation along that line\nand the way forward is to fix the implementation, instead of documenting\nthe buggy behaviour.\n\nIt is natural to expect \"git branch --merged pu vr/\\*\" to list branches\nthat are contained in 'pu' whose names match the given pattern, but it\nseems to try creating a branch called \"vr/*\" and fails, for example.\n\n> The current\n> synopsis also suggests that 'git branch -d ...' would be a valid\n> command.\n\nThat is not how I read the current synopsis for -d; doesn't it avoid using\n and explicitly say ?\n\n> Signed-off-by: Vincent van Ravesteijn \n> ---\n> Documentation/git-branch.txt | 11 ++++++-----\n> 1 files changed, 6 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index f46013c..9f49db4 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -9,8 +9,9 @@ SYNOPSIS\n> --------\n> [verse]\n> 'git branch' [--color[=] | --no-color] [-r | -a]\n> -\t[--list] [-v [--abbrev= | --no-abbrev]]\n> -\t[(--merged | --no-merged | --contains) []] [...]\n> +\t[-v [--abbrev= | --no-abbrev]]\n> +\t[(--merged | --no-merged | --contains) []]\n> +\t[--list [...]]\n> 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] []\n> 'git branch' (-m | -M) [] \n> 'git branch' (-d | -D) [-r] ...\n> @@ -23,8 +24,8 @@ be highlighted with an asterisk. Option `-r` causes the remote-tracking\n> branches to be listed, and option `-a` shows both. This list mode is also\n> activated by the `--list` option (see below).\n> restricts the output to matching branches, the pattern is a shell\n> -wildcard (i.e., matched using fnmatch(3))\n> -Multiple patterns may be given; if any of them matches, the tag is shown.\n> +wildcard (i.e., matched using fnmatch(3)).\n> +Multiple patterns may be given; if any of them matches, the branch is shown.\n> \n> With `--contains`, shows only the branches that contain the named commit\n> (in other words, the branches whose tip commits are descendants of the\n> @@ -114,7 +115,7 @@ OPTIONS\n> --all::\n> \tList both remote-tracking branches and local branches.\n> \n> ---list::\n> +--list [...]::\n> \tActivate the list mode. `git branch ` would try to create a branch,\n> \tuse `git branch --list ` to list matching branches.\n"},{"id":"179815","messageId":"4ECB43E4.7030607@lyx.org","threadId":"28993","inReplyTo":"7v7h2tgyw6.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation update for 'git branch --list'","fromName":"Vincent van Ravesteijn","fromEmail":"vfr@lyx.org","sentAt":"2011-11-22T06:40:36Z","receivedAt":"2011-11-22T06:40:36Z","isPatch":true,"sender":{"key":"vfr@lyx.org","avatar":"https://avatars.githubusercontent.com/u/687868?v=4"},"body":"Op 21-11-2011 18:37, Junio C Hamano schreef:\n> Vincent van Ravesteijn writes:\n>\n>> Indicate that the... argument is only valid when using --list.\n>> Otherwise a branch with the name will be created.\n> I actually think there are some bugs in the implementation along that line\n> and the way forward is to fix the implementation, instead of documenting\n> the buggy behaviour.\n>\n> It is natural to expect \"git branch --merged pu vr/\\*\" to list branches\n> that are contained in 'pu' whose names match the given pattern, but it\n> seems to try creating a branch called \"vr/*\" and fails, for example.\n\nIf this is what you naturally would expect, I would expect the following \n\"git branch vr/*\" to work as well.\n\nWhat would you say if we try to interpret the argument as a pattern when \nthe argument is not a valid ref name ? This includes all arguments \ncontaining '*'. In case of confusion we can demand the \"--list\" \nparameter to make clear what we mean.\n\nAnother thing is noticed is that the pattern use is different for 'git \nfor-each-ref ' and 'git branch --list '.\n\nTwo examples:\n\n> c:\\Users\\Vincent\\Documents\\git\\git>git for-each-ref refs/heads/\n> f56ef114eeefee755f422e6cbef2d83974cb90f1 commit refs/heads/master\n> c2ee0c73bcb4d1980e5d0bb0d20912b565d8ae38 commit refs/heads/next\n> e341d009b2e0374520ac72973c6e98d315218624 commit refs/heads/pu\n> 5fd37a7da3df644a85887051ae36117c732d1781 commit refs/heads/vr/fix-crashes\n> cec815158934d82cdef815ea1342be2c3edbc5c8 commit \n> refs/heads/vr/msvc-compile-fix\n> 777963bd4a9f41ac3eae8de2a7b7177917d127e6 commit \n> refs/heads/vr/msvc-compile-fix-poll\n>\n> c:\\Users\\Vincent\\Documents\\git\\git>git branch --list refs/heads/\n>\n> c:\\Users\\Vincent\\Documents\\git\\git>\n\nand\n\n> c:\\Users\\Vincent\\Documents\\git\\git>git branch --list v*\n> vr/fix-crashes\n> vr/msvc-compile-fix\n> vr/msvc-compile-fix-poll\n>\n> c:\\Users\\Vincent\\Documents\\git\\git>git for-each-ref v*\n>\n> c:\\Users\\Vincent\\Documents\\git\\git>\n\n\nVincent\n"},{"id":"179843","messageId":"7vobw4doey.fsf@alter.siamese.dyndns.org","threadId":"28993","inReplyTo":"4ECB43E4.7030607@lyx.org","subject":"Re: [PATCH] Documentation update for 'git branch --list'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-11-22T18:04:21Z","receivedAt":"2011-11-22T18:04:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Vincent van Ravesteijn writes:\n\n> Op 21-11-2011 18:37, Junio C Hamano schreef:\n> ...\n>> It is natural to expect \"git branch --merged pu vr/\\*\" to list branches\n>> that are contained in 'pu' whose names match the given pattern, but it\n>> seems to try creating a branch called \"vr/*\" and fails, for example.\n>\n> If this is what you naturally would expect, I would expect the\n> following \"git branch vr/*\" to work as well.\n> What would you say if we try to interpret the argument as a pattern\n> when the argument is not a valid ref name?\n\nWe don't, as that is inviting mistakes. \"git branch vr/*\" if you have a\nvr/ directory in your working tree may create vr/a branch from where the\ntip of vr/b points at by mistake.\n\nThe \"--merged\" option is an explicit clue that the user is not interested\nin creating new branch, and the string being a pattern is additional clue.\nThe \"--list\" option was recently added for the explicit purpose of giving\nsuch a clue as safety measure.\n"},{"id":"180131","messageId":"4ED5C51E.5070404@lyx.org","threadId":"28993","inReplyTo":"7vobw4doey.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation update for 'git branch --list'","fromName":"Vincent van Ravesteijn","fromEmail":"vfr@lyx.org","sentAt":"2011-11-30T05:54:38Z","receivedAt":"2011-11-30T05:54:38Z","isPatch":true,"sender":{"key":"vfr@lyx.org","avatar":"https://avatars.githubusercontent.com/u/687868?v=4"},"body":"Op 22-11-2011 19:04, Junio C Hamano schreef:\n> Vincent van Ravesteijn writes:\n>\n>> Op 21-11-2011 18:37, Junio C Hamano schreef:\n>> ...\n>>> It is natural to expect \"git branch --merged pu vr/\\*\" to list branches\n>>> that are contained in 'pu' whose names match the given pattern, but it\n>>> seems to try creating a branch called \"vr/*\" and fails, for example.\n>> If this is what you naturally would expect, I would expect the\n>> following \"git branch vr/*\" to work as well.\n>> What would you say if we try to interpret the argument as a pattern\n>> when the argument is not a valid ref name?\n> We don't, as that is inviting mistakes. \"git branch vr/*\" if you have a\n> vr/ directory in your working tree may create vr/a branch from where the\n> tip of vr/b points at by mistake.\n>\n> The \"--merged\" option is an explicit clue that the user is not interested\n> in creating new branch, and the string being a pattern is additional clue.\n> The \"--list\" option was recently added for the explicit purpose of giving\n> such a clue as safety measure.\n\nWell, that was the answer that I foresaw.\n\nI will compose a patch implementing an at least consistent behaviour.\n\nVincent\n"}]}