{"thread":{"id":"25626","subject":"[PATCH] Documentation: fix misnested -l and --contains in git-tag synopsis","startedAt":"2010-11-03T11:17:09Z","lastAt":"2010-11-05T16:51:54Z","messageCount":4,"participants":["Philip Jägenstedt","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"155042","messageId":"1288783029-11226-1-git-send-email-philip@foolip.org","threadId":"25626","inReplyTo":null,"subject":"[PATCH] Documentation: fix misnested -l and --contains in git-tag synopsis","fromName":"Philip Jägenstedt","fromEmail":"philip@foolip.org","sentAt":"2010-11-03T11:17:09Z","receivedAt":"2010-11-03T11:17:09Z","isPatch":true,"sender":{"key":"philip@foolip.org","avatar":"https://avatars.githubusercontent.com/u/498917?v=4"},"body":"This has been broken since the --contains option was added in\ncommit 32c35cfb1e9c8523b9d60e5095f1c49ebaef0279\n\nSigned-off-by: Philip Jägenstedt \n---\n Documentation/git-tag.txt | 2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 31c78a8..8ad89d7 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git tag' [-a | -s | -u ] [-f] [-m | -F ]\n \t [ | ]\n 'git tag' -d ...\n-'git tag' [-n[]] -l [--contains ] []\n+'git tag' [-n[]] -l [] [--contains ]\n 'git tag' -v ...\n \n DESCRIPTION\n-- \n1.7.1\n"},{"id":"155197","messageId":"7vmxpovq0r.fsf@alter.siamese.dyndns.org","threadId":"25626","inReplyTo":"1288783029-11226-1-git-send-email-philip@foolip.org","subject":"Re: [PATCH] Documentation: fix misnested -l and --contains in git-tag synopsis","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-11-04T19:37:40Z","receivedAt":"2010-11-04T19:37:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Jägenstedt writes:\n\n> This has been broken since the --contains option was added in\n> commit 32c35cfb1e9c8523b9d60e5095f1c49ebaef0279\n>\n> Signed-off-by: Philip Jägenstedt \n> ---\n> Documentation/git-tag.txt | 2 +-\n> 1 files changed, 1 insertions(+), 1 deletions(-)\n>\n> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\n> index 31c78a8..8ad89d7 100644\n> --- a/Documentation/git-tag.txt\n> +++ b/Documentation/git-tag.txt\n> @@ -12,7 +12,7 @@ SYNOPSIS\n> 'git tag' [-a | -s | -u ] [-f] [-m | -F ]\n> \t [ | ]\n> 'git tag' -d ...\n> -'git tag' [-n[]] -l [--contains ] []\n> +'git tag' [-n[]] -l [] [--contains ]\n> 'git tag' -v ...\n\nI do not think there is any \"mis\" nor \"nesting\" here. The -l option can\nbe used to tell the command to operate in \"list tags\" mode, and in that\nmode it can use a pattern to limit the output (with or without --contains\n). All of these are supported:\n\n git tag -l --contains v1.7.0 v\\*\n git tag -l v\\*\n git tag --contains v1.7.0 -l v\\*\n git tag -l v\\* --contains v1.7.0\n\nIOW, is _not_ an optional argument to the -l option. In fact, I\nthink we should support more than one patterns, even though currently this\nseems to silently ignore k\\*:\n\n git tag --contains v1.7.0 -l v\\* k\\*\n\nAs I tend to consider that \"limit by pattern\" is like pathspecs (in this\ncase, it is _not_ a pathspec, though), having the pattern at the end looks\nthe most natural, but it may be just me. And that is why I think we ought\nto accept and apply more than one patterns here.\n\nI would further say that \"git tag -l --contains \" should\nbe an error, even though the command currently seems to take it; perhaps\nparameter reordering is in effect? I didn't look closely enough.\n"},{"id":"155255","messageId":"AANLkTikXM4BjRHOeS=3mirr9=YRW8sdaHFt05D-9BDxL@mail.gmail.com","threadId":"25626","inReplyTo":"7vmxpovq0r.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: fix misnested -l and --contains in git-tag synopsis","fromName":"Philip Jägenstedt","fromEmail":"philip@foolip.org","sentAt":"2010-11-05T09:28:12Z","receivedAt":"2010-11-05T09:28:12Z","isPatch":true,"sender":{"key":"philip@foolip.org","avatar":"https://avatars.githubusercontent.com/u/498917?v=4"},"body":"On Thu, Nov 4, 2010 at 20:37, Junio C Hamano wrote:\n> Philip Jägenstedt writes:\n>\n>> This has been broken since the --contains option was added in\n>> commit 32c35cfb1e9c8523b9d60e5095f1c49ebaef0279\n>>\n>> Signed-off-by: Philip Jägenstedt \n>> ---\n>>  Documentation/git-tag.txt |    2 +-\n>>  1 files changed, 1 insertions(+), 1 deletions(-)\n>>\n>> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\n>> index 31c78a8..8ad89d7 100644\n>> --- a/Documentation/git-tag.txt\n>> +++ b/Documentation/git-tag.txt\n>> @@ -12,7 +12,7 @@ SYNOPSIS\n>>  'git tag' [-a | -s | -u ] [-f] [-m | -F ]\n>>       [ | ]\n>>  'git tag' -d ...\n>> -'git tag' [-n[]] -l [--contains ] []\n>> +'git tag' [-n[]] -l [] [--contains ]\n>>  'git tag' -v ...\n>\n> I do not think there is any \"mis\" nor \"nesting\" here.  The -l option can\n> be used to tell the command to operate in \"list tags\" mode, and in that\n> mode it can use a pattern to limit the output (with or without --contains\n> ).  All of these are supported:\n>\n>    git tag -l --contains v1.7.0 v\\*\n>    git tag -l v\\*\n>    git tag --contains v1.7.0 -l v\\*\n>    git tag -l v\\* --contains v1.7.0\n>\n> IOW, is _not_ an optional argument to the -l option.  In fact, I\n> think we should support more than one patterns, even though currently this\n> seems to silently ignore k\\*:\n>\n>    git tag --contains v1.7.0 -l v\\* k\\*\n>\n> As I tend to consider that \"limit by pattern\" is like pathspecs (in this\n> case, it is _not_ a pathspec, though), having the pattern at the end looks\n> the most natural, but it may be just me.  And that is why I think we ought\n> to accept and apply more than one patterns here.\n>\n> I would further say that \"git tag -l --contains \" should\n> be an error, even though the command currently seems to take it; perhaps\n> parameter reordering is in effect?  I didn't look closely enough.\n>\n\nFrom the documentation it's not clear that -l and --contains are\nrelated at all, they look (and behave?) like orthogonal options. If\nthey do in fact interact in some non-obvious way or if -l \n--contains means something different from -l --contains\n , it would be great if that were made more clear. (I\nwouldn't have expected the later to work at all, thus my assumption\nthat there was a typo in the documentation.)\n\n-- \nPhilip Jägenstedt\n"},{"id":"155263","messageId":"7vzktnu311.fsf@alter.siamese.dyndns.org","threadId":"25626","inReplyTo":"AANLkTikXM4BjRHOeS=3mirr9=YRW8sdaHFt05D-9BDxL@mail.gmail.com","subject":"Re: [PATCH] Documentation: fix misnested -l and --contains in git-tag synopsis","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-11-05T16:51:54Z","receivedAt":"2010-11-05T16:51:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Jägenstedt writes:\n\n> ... they do in fact interact in some non-obvious way or if -l \n> --contains means something different from -l --contains\n> , it would be great if that were made more clear.\n\nThere is no difference; at least there shouldn't be any, and if there are,\nyou found a bug in the implementation.\n\nLet's try to see if I can explain it better.\n\n\"git tag\" command operates in four modes:\n\n - \"Creating\" is the default mode.\n - \"Verifying\" is triggered with the -v option.\n - \"Deleting\" is triggered with the -d option.\n - \"Listing\" is triggered with the -l option.\n\nIn \"Listing\" mode, you can limit which ones are shown by adding \nat the end [*1*]; \"--contains \" can also be used to limit. You\ncan change how tags are shown by \"-n \" option.\n\nAbsense of -v, -d, or -l options does not automatically mean \"Creating\"\nmode; when it is clear from other options that \"Listing\" is requested, we\ndo so without \"-l\". When you have \"--contains \", for example, it\nis obvious that you want a listing. The same if you have \"-n1\".\n\n[Footnote]\n\n*1* I think allowing anywhere on the command line but at the end\nis actually a bug.\n\nEven though it can be argued that it does not _hurt_ not to refuse such a\ncommand line (i.e. the command would do something useful), it appears to\nme that it did hurt in this particular case by giving a false impression\nthat somehow \"-l\" takes an optional argument by allowing other\noptions after \"-l \" is given.\n\nArguably, it is the same kind of \"usability measure\" as our dwimming into\nlisting mode without \"-l\" when we can infer the intent of the user from\nother options, but I think we sometimes overdo usability measures to the\npoint that they negatively affect the learning curve of users.\n\nI also think allowing only one is a bug. The command should\nfilter the tags by union of s, just like how pathspec works.\n"}]}