{"thread":{"id":"31207","subject":"[PATCH] Documentation: list git-credential in plumbing commands","startedAt":"2012-08-08T07:58:27Z","lastAt":"2012-08-09T08:02:38Z","messageCount":21,"participants":["Matthieu Moy","Junio C Hamano","Jeff King","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"196644","messageId":"1344412707-22356-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"31207","inReplyTo":null,"subject":"[PATCH] Documentation: list git-credential in plumbing commands","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-08-08T07:58:27Z","receivedAt":"2012-08-08T07:58:27Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Commit e30b2feb1b (Jun 24 2012, add 'git credential' plumbing command)\nforgot to add git-credential to command-list.txt, hence the command was\nnot appearing in the documentation, making it hard for users to discover\nit.\n\nWhile we're there, capitalize the description line for git-crendential\nfor consistancy with other commands.\n\nSigned-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>\n---\n Documentation/git-credential.txt | 2 +-\n command-list.txt                 | 1 +\n 2 files changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\nindex 53adee3..810e957 100644\n--- a/Documentation/git-credential.txt\n+++ b/Documentation/git-credential.txt\n@@ -3,7 +3,7 @@ git-credential(1)\n \n NAME\n ----\n-git-credential - retrieve and store user credentials\n+git-credential - Retrieve and store user credentials\n \n SYNOPSIS\n --------\ndiff --git a/command-list.txt b/command-list.txt\nindex 14ea67a..ec64cac 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -25,6 +25,7 @@ git-commit                              mainporcelain common\n git-commit-tree                         plumbingmanipulators\n git-config                              ancillarymanipulators\n git-count-objects                       ancillaryinterrogators\n+git-credential                          purehelpers\n git-cvsexportcommit                     foreignscminterface\n git-cvsimport                           foreignscminterface\n git-cvsserver                           foreignscminterface\n-- \n1.7.12.rc1.183.gb94da76\n"},{"id":"196674","messageId":"7vmx25tj5y.fsf@alter.siamese.dyndns.org","threadId":"31207","inReplyTo":"1344412707-22356-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH] Documentation: list git-credential in plumbing commands","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-08T16:58:33Z","receivedAt":"2012-08-08T16:58:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy <Matthieu.Moy@imag.fr> writes:\n\n> Commit e30b2feb1b (Jun 24 2012, add 'git credential' plumbing command)\n> forgot to add git-credential to command-list.txt, hence the command was\n> not appearing in the documentation, making it hard for users to discover\n> it.\n>\n> While we're there, capitalize the description line for git-crendential\n> for consistancy with other commands.\n\nconsistency?\n\n>\n> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>\n\nThanks.\n\nThere really should be an easier way for the maintainer to notice\nthis kind of glitch without being told (better yet, the submitter of\na new command to notice it).  Perhaps the check-docs target in the\nMakefile needs some updating?\n"},{"id":"196677","messageId":"1344445989-2923-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"31207","inReplyTo":"7vmx25tj5y.fsf@alter.siamese.dyndns.org","subject":"[PATCH v2] Documentation: list git-credential in plumbing commands","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-08-08T17:13:09Z","receivedAt":"2012-08-08T17:13:09Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Commit e30b2feb1b (Jun 24 2012, add 'git credential' plumbing command)\nforgot to add git-credential to command-list.txt, hence the command was\nnot appearing in the documentation, making it hard for users to discover\nit.\n\nWhile we're there, capitalize the description line for git-crendential\nfor consistency with other commands.\n\nSigned-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>\n---\n> > for consistancy with other commands.\n> \n> consistency?\n\nYes, sorry. This one should be OK.\n\n Documentation/git-credential.txt | 2 +-\n command-list.txt                 | 1 +\n 2 files changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\nindex 53adee3..810e957 100644\n--- a/Documentation/git-credential.txt\n+++ b/Documentation/git-credential.txt\n@@ -3,7 +3,7 @@ git-credential(1)\n \n NAME\n ----\n-git-credential - retrieve and store user credentials\n+git-credential - Retrieve and store user credentials\n \n SYNOPSIS\n --------\ndiff --git a/command-list.txt b/command-list.txt\nindex 14ea67a..ec64cac 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -25,6 +25,7 @@ git-commit                              mainporcelain common\n git-commit-tree                         plumbingmanipulators\n git-config                              ancillarymanipulators\n git-count-objects                       ancillaryinterrogators\n+git-credential                          purehelpers\n git-cvsexportcommit                     foreignscminterface\n git-cvsimport                           foreignscminterface\n git-cvsserver                           foreignscminterface\n-- \n1.7.12.rc1.183.gb94da76\n"},{"id":"196683","messageId":"20120808183132.GA24550@sigill.intra.peff.net","threadId":"31207","inReplyTo":"7vmx25tj5y.fsf@alter.siamese.dyndns.org","subject":"[PATCH 0/4] update \"make check-docs\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T18:31:32Z","receivedAt":"2012-08-08T18:31:32Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 08, 2012 at 09:58:33AM -0700, Junio C Hamano wrote:\n\n> There really should be an easier way for the maintainer to notice\n> this kind of glitch without being told (better yet, the submitter of\n> a new command to notice it).  Perhaps the check-docs target in the\n> Makefile needs some updating?\n\nHmm. We have a check-docs command? :)\n\nThis patch series at least brings that up to date. It goes on top of\nMatthieu's patch.\n\n  [1/4]: check-docs: mention gitweb specially\n  [2/4]: check-docs: update non-command documentation list\n  [3/4]: command-list: add git-sh-i18n\n  [4/4]: command-list: mention git-credential-* helpers\n\n-Peff\n"},{"id":"196684","messageId":"20120808183236.GA24574@sigill.intra.peff.net","threadId":"31207","inReplyTo":"20120808183132.GA24550@sigill.intra.peff.net","subject":"[PATCH 1/4] check-docs: mention gitweb specially","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T18:32:37Z","receivedAt":"2012-08-08T18:32:37Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"Like gitk, gitweb is not listed in the usual Makefile\nvariables and must be fed to check-docs specially. Otherwise\ncheck-docs thinks it is documented but removed.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Makefile | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex 15d1319..5e773cd 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2805,7 +2805,7 @@ endif\n ### Check documentation\n #\n check-docs::\n-\t@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk; \\\n+\t@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb; \\\n \tdo \\\n \t\tcase \"$$v\" in \\\n \t\tgit-merge-octopus | git-merge-ours | git-merge-recursive | \\\n@@ -2855,7 +2855,7 @@ check-docs::\n \t\tdocumented,gitworkflows | \\\n \t\tsentinel,not,matching,is,ok ) continue ;; \\\n \t\tesac; \\\n-\t\tcase \" $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk \" in \\\n+\t\tcase \" $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb \" in \\\n \t\t*\" $$cmd \"*)\t;; \\\n \t\t*) echo \"removed but $$how: $$cmd\" ;; \\\n \t\tesac; \\\n-- \n1.7.12.rc2.2.g584e0d9\n"},{"id":"196686","messageId":"20120808183433.GB24574@sigill.intra.peff.net","threadId":"31207","inReplyTo":"20120808183132.GA24550@sigill.intra.peff.net","subject":"[PATCH 2/4] check-docs: update non-command documentation list","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T18:34:33Z","receivedAt":"2012-08-08T18:34:33Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"The check-docs target looks at Documentation/git*txt and\ncomplains if any entry does not have a matching command.\nTherefore we need to explicitly ignore any entries which are\nnot meant to describe a command (like gitattributes.txt).\nThis list has grown stale over time, so let's bring it up to\ndate.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\nI really wonder if we would do better to match git-*.txt, since most of\nthe ignores are gitfoo(7) types of pages. We'd probably want to add back\nin \"git\", \"gitweb\" and \"gitk\" explicitly, but they are already handled\nspecially above and below.\n\n Makefile | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Makefile b/Makefile\nindex 5e773cd..41d9db8 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2853,6 +2853,9 @@ check-docs::\n \t\tdocumented,git-bisect-lk2009 | \\\n \t\tdocumented,git-remote-helpers | \\\n \t\tdocumented,gitworkflows | \\\n+\t\tdocumented,gitcredentials | \\\n+\t\tdocumented,gitnamespaces | \\\n+\t\tdocumented,gitweb.conf | \\\n \t\tsentinel,not,matching,is,ok ) continue ;; \\\n \t\tesac; \\\n \t\tcase \" $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb \" in \\\n-- \n1.7.12.rc2.2.g584e0d9\n"},{"id":"196687","messageId":"20120808183439.GC24574@sigill.intra.peff.net","threadId":"31207","inReplyTo":"20120808183132.GA24550@sigill.intra.peff.net","subject":"[PATCH 3/4] command-list: add git-sh-i18n","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T18:34:39Z","receivedAt":"2012-08-08T18:34:39Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"This is in the same category as git-sh-setup.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n command-list.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex ec64cac..1da8f0d 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -114,6 +114,7 @@ git-show                                mainporcelain common\n git-show-branch                         ancillaryinterrogators\n git-show-index                          plumbinginterrogators\n git-show-ref                            plumbinginterrogators\n+git-sh-i18n                             purehelpers\n git-sh-setup                            purehelpers\n git-stash                               mainporcelain\n git-status                              mainporcelain common\n-- \n1.7.12.rc2.2.g584e0d9\n"},{"id":"196688","messageId":"20120808183449.GD24574@sigill.intra.peff.net","threadId":"31207","inReplyTo":"20120808183132.GA24550@sigill.intra.peff.net","subject":"[PATCH 4/4] command-list: mention git-credential-* helpers","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T18:34:49Z","receivedAt":"2012-08-08T18:34:49Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"These commands were never added to the command-list. Adding\nthem makes \"make check-docs\" run without complaint.\nWhile we're at it, let's capitalize the first letter of\ntheir one-line summaries to match the rest of the git\nmanpages.\n\nThe credential-cache--daemon command is somewhat special. It\nis already ignored by check-docs because it contains a \"--\",\nmarking it as a non-interesting implementation detail. It\nis, in fact, documented, but since the documentation\nbasically just redirects you to a more appropriate command\nanyway, let's explicitly omit it so it is not mentioned in\ngit(1).\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Documentation/git-credential-cache--daemon.txt | 2 +-\n Documentation/git-credential-cache.txt         | 2 +-\n Documentation/git-credential-store.txt         | 2 +-\n command-list.txt                               | 2 ++\n 4 files changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt\nindex 11edc5a..d15db42 100644\n--- a/Documentation/git-credential-cache--daemon.txt\n+++ b/Documentation/git-credential-cache--daemon.txt\n@@ -3,7 +3,7 @@ git-credential-cache--daemon(1)\n \n NAME\n ----\n-git-credential-cache--daemon - temporarily store user credentials in memory\n+git-credential-cache--daemon - Temporarily store user credentials in memory\n \n SYNOPSIS\n --------\ndiff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt\nindex f3d09c5..eeff5fa 100644\n--- a/Documentation/git-credential-cache.txt\n+++ b/Documentation/git-credential-cache.txt\n@@ -3,7 +3,7 @@ git-credential-cache(1)\n \n NAME\n ----\n-git-credential-cache - helper to temporarily store passwords in memory\n+git-credential-cache - Helper to temporarily store passwords in memory\n \n SYNOPSIS\n --------\ndiff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt\nindex 3109346..b27c03c 100644\n--- a/Documentation/git-credential-store.txt\n+++ b/Documentation/git-credential-store.txt\n@@ -3,7 +3,7 @@ git-credential-store(1)\n \n NAME\n ----\n-git-credential-store - helper to store credentials on disk\n+git-credential-store - Helper to store credentials on disk\n \n SYNOPSIS\n --------\ndiff --git a/command-list.txt b/command-list.txt\nindex 1da8f0d..7e8cfec 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -26,6 +26,8 @@ git-commit-tree                         plumbingmanipulators\n git-config                              ancillarymanipulators\n git-count-objects                       ancillaryinterrogators\n git-credential                          purehelpers\n+git-credential-cache                    purehelpers\n+git-credential-store                    purehelpers\n git-cvsexportcommit                     foreignscminterface\n git-cvsimport                           foreignscminterface\n git-cvsserver                           foreignscminterface\n-- \n1.7.12.rc2.2.g584e0d9\n"},{"id":"196690","messageId":"7v1ujhtcxk.fsf@alter.siamese.dyndns.org","threadId":"31207","inReplyTo":"20120808183132.GA24550@sigill.intra.peff.net","subject":"Re: [PATCH 0/4] update \"make check-docs\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-08T19:13:11Z","receivedAt":"2012-08-08T19:13:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> On Wed, Aug 08, 2012 at 09:58:33AM -0700, Junio C Hamano wrote:\n>\n>> There really should be an easier way for the maintainer to notice\n>> this kind of glitch without being told (better yet, the submitter of\n>> a new command to notice it).  Perhaps the check-docs target in the\n>> Makefile needs some updating?\n>\n> Hmm. We have a check-docs command? :)\n\nYes, and there also is a check-builtins target.  Perhaps the default\nbuild target should depend on them, as they are fairly lightweight?\n\n> This patch series at least brings that up to date. It goes on top of\n> Matthieu's patch.\n>\n>   [1/4]: check-docs: mention gitweb specially\n>   [2/4]: check-docs: update non-command documentation list\n>   [3/4]: command-list: add git-sh-i18n\n>   [4/4]: command-list: mention git-credential-* helpers\n\nThanks.\n"},{"id":"196692","messageId":"7vwr19rxua.fsf@alter.siamese.dyndns.org","threadId":"31207","inReplyTo":"20120808183433.GB24574@sigill.intra.peff.net","subject":"Re: [PATCH 2/4] check-docs: update non-command documentation list","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-08T19:24:29Z","receivedAt":"2012-08-08T19:24:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> The check-docs target looks at Documentation/git*txt and\n> complains if any entry does not have a matching command.\n> Therefore we need to explicitly ignore any entries which are\n> not meant to describe a command (like gitattributes.txt).\n> This list has grown stale over time, so let's bring it up to\n> date.\n>\n> Signed-off-by: Jeff King <peff@peff.net>\n> ---\n> I really wonder if we would do better to match git-*.txt, since most of\n> the ignores are gitfoo(7) types of pages. We'd probably want to add back\n> in \"git\", \"gitweb\" and \"gitk\" explicitly, but they are already handled\n> specially above and below.\n\nQuite possibly, yes.\n\nAlso \"git gitk gitweb\" may want to be made into a Makefile variable\nto be shared in the \"above\" and \"below\" (I do not know what to call\nthem offhand---they are programs with special build rules that are\nnot covered by ALL/SCRIPT_LIB/BUILTIN).\n\nBy the way, do we have a documentation for git-gui?  Perhaps it may\nwant to be added to that \"git gitk gitweb\" list as a reminder that\nit lacks documentation.  One of the goals of the person who runs\n\"make check-docs\" should be to reduce the special case that appears\nat the beginning of that case statement.\n\nI also wonder why \"help\" is not treated as a built-in?  Perhaps we\nshould throw it in to \"git gitk gitweb\" list?  After all, it is a\ncommand that is available in \"git foo\" form, is documented, and is\nlisted in the command-list.txt file.\n\nThanks.\n"},{"id":"196696","messageId":"20120808201013.GA29528@sigill.intra.peff.net","threadId":"31207","inReplyTo":"7v1ujhtcxk.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 0/4] update \"make check-docs\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T20:10:14Z","receivedAt":"2012-08-08T20:10:14Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 08, 2012 at 12:13:11PM -0700, Junio C Hamano wrote:\n\n> > Hmm. We have a check-docs command? :)\n> \n> Yes, and there also is a check-builtins target.  Perhaps the default\n> build target should depend on them, as they are fairly lightweight?\n\nI think they would want some refactoring. Right now the target does not\nfail if there are errors. Any output it generates would typically scroll\nby in the mass of other build data, so it would be easy to miss.\n\n-Peff\n"},{"id":"196701","messageId":"20120808205456.GB29528@sigill.intra.peff.net","threadId":"31207","inReplyTo":"7vwr19rxua.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/4] check-docs: update non-command documentation list","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T20:54:56Z","receivedAt":"2012-08-08T20:54:56Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 08, 2012 at 12:24:29PM -0700, Junio C Hamano wrote:\n\n> Jeff King <peff@peff.net> writes:\n> \n> > The check-docs target looks at Documentation/git*txt and\n> > complains if any entry does not have a matching command.\n> > Therefore we need to explicitly ignore any entries which are\n> > not meant to describe a command (like gitattributes.txt).\n> > This list has grown stale over time, so let's bring it up to\n> > date.\n> >\n> > Signed-off-by: Jeff King <peff@peff.net>\n> > ---\n> > I really wonder if we would do better to match git-*.txt, since most of\n> > the ignores are gitfoo(7) types of pages. We'd probably want to add back\n> > in \"git\", \"gitweb\" and \"gitk\" explicitly, but they are already handled\n> > specially above and below.\n> \n> Quite possibly, yes.\n\nActually, my \"already handled specially\" is not quite accurate. That\nspecial list is \"things that are commands but are not necessarily\nmentioned in the Makefile variables\". But this list is \"things that are\ndocumented but do not begin with git-\". The two should mostly be the\nsame, but the whole point of this exercise is to make sure they _are_\nthe same.\n\nA better solution is to simply ask the Documentation directory what the\ncommands are, since it already knows (in the form of MAN1_TXT).\n\n> Also \"git gitk gitweb\" may want to be made into a Makefile variable\n> to be shared in the \"above\" and \"below\" (I do not know what to call\n> them offhand---they are programs with special build rules that are\n> not covered by ALL/SCRIPT_LIB/BUILTIN).\n\nI couldn't think of a special name, either, but I think it is sufficient\nto just create a new ALL_COMMANDS variable that includes those other\nthings, and then add to it.\n\n> By the way, do we have a documentation for git-gui?  Perhaps it may\n> want to be added to that \"git gitk gitweb\" list as a reminder that\n> it lacks documentation.  One of the goals of the person who runs\n> \"make check-docs\" should be to reduce the special case that appears\n> at the beginning of that case statement.\n\nYes, it should be checked (and git-citool, too).\n\n> I also wonder why \"help\" is not treated as a built-in?  Perhaps we\n> should throw it in to \"git gitk gitweb\" list?  After all, it is a\n> command that is available in \"git foo\" form, is documented, and is\n> listed in the command-list.txt file.\n\nHistorically it was part of git.c, but these days it is a built-in and\ndoes not need any special treatment from check-docs.\n\nPatches for all to follow (on top of my previous 4).\n\n  [5/4]: check-docs: factor out command-list\n  [6/4]: check-docs: list git-gui as a command\n  [7/4]: check-docs: drop git-help special-case\n  [8/4]: check-docs: get documented command list from Makefile\n\n-Peff\n"},{"id":"196702","messageId":"20120808205604.GA12838@sigill.intra.peff.net","threadId":"31207","inReplyTo":"20120808205456.GB29528@sigill.intra.peff.net","subject":"[PATCH 5/4] check-docs: factor out command-list","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T20:56:04Z","receivedAt":"2012-08-08T20:56:04Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"The check-docs command list is composed from several\nMakefile variables plus some special cases. Let's make the\nmeaning of the list more obvious and avoid repeating\nourselves by factoring it out.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Makefile | 8 ++++++--\n 1 file changed, 6 insertions(+), 2 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex 41d9db8..6ae868d 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2804,8 +2804,12 @@ endif\n \n ### Check documentation\n #\n+ALL_COMMANDS = $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS)\n+ALL_COMMANDS += git\n+ALL_COMMANDS += gitk\n+ALL_COMMANDS += gitweb\n check-docs::\n-\t@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb; \\\n+\t@(for v in $(ALL_COMMANDS); \\\n \tdo \\\n \t\tcase \"$$v\" in \\\n \t\tgit-merge-octopus | git-merge-ours | git-merge-recursive | \\\n@@ -2858,7 +2862,7 @@ check-docs::\n \t\tdocumented,gitweb.conf | \\\n \t\tsentinel,not,matching,is,ok ) continue ;; \\\n \t\tesac; \\\n-\t\tcase \" $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk gitweb \" in \\\n+\t\tcase \" $(ALL_COMMANDS) \" in \\\n \t\t*\" $$cmd \"*)\t;; \\\n \t\t*) echo \"removed but $$how: $$cmd\" ;; \\\n \t\tesac; \\\n-- \n1.7.12.rc2.36.gb1dc81b\n"},{"id":"196703","messageId":"20120808205642.GB12838@sigill.intra.peff.net","threadId":"31207","inReplyTo":"20120808205456.GB29528@sigill.intra.peff.net","subject":"[PATCH 6/4] check-docs: list git-gui as a command","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T20:56:42Z","receivedAt":"2012-08-08T20:56:42Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"git-gui is already documented and mentioned in command-list,\nbut adding it to the Makefile makes sure it is so. We also\nadd its alias git-citool (which is also documented).\n\nAs a result, we can drop them from the special case\nstatement that avoids them being listed as \"documented but\ndoes not exist\".\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Makefile | 3 +--\n 1 file changed, 1 insertion(+), 2 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex 6ae868d..4b3c366 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2808,6 +2808,7 @@ ALL_COMMANDS = $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS)\n ALL_COMMANDS += git\n ALL_COMMANDS += gitk\n ALL_COMMANDS += gitweb\n+ALL_COMMANDS += git-gui git-citool\n check-docs::\n \t@(for v in $(ALL_COMMANDS); \\\n \tdo \\\n@@ -2837,8 +2838,6 @@ check-docs::\n \t) | while read how cmd; \\\n \tdo \\\n \t\tcase \"$$how,$$cmd\" in \\\n-\t\t*,git-citool | \\\n-\t\t*,git-gui | \\\n \t\t*,git-help | \\\n \t\tdocumented,gitattributes | \\\n \t\tdocumented,gitignore | \\\n-- \n1.7.12.rc2.36.gb1dc81b\n"},{"id":"196704","messageId":"20120808205713.GC12838@sigill.intra.peff.net","threadId":"31207","inReplyTo":"20120808205456.GB29528@sigill.intra.peff.net","subject":"[PATCH 7/4] check-docs: drop git-help special-case","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T20:57:13Z","receivedAt":"2012-08-08T20:57:13Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"The check-docs target special-cases git-help to avoid\nmentioning it as \"documented but removed\". This dates back\nto the early implementation of git-help, when its code was\nsimply included inside git.c.\n\nThese days it is a full-fledged builtin (in builtin/help.c)\nand does not need special-casing.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Makefile | 1 -\n 1 file changed, 1 deletion(-)\n\ndiff --git a/Makefile b/Makefile\nindex 4b3c366..b9da511 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2838,7 +2838,6 @@ check-docs::\n \t) | while read how cmd; \\\n \tdo \\\n \t\tcase \"$$how,$$cmd\" in \\\n-\t\t*,git-help | \\\n \t\tdocumented,gitattributes | \\\n \t\tdocumented,gitignore | \\\n \t\tdocumented,gitmodules | \\\n-- \n1.7.12.rc2.36.gb1dc81b\n"},{"id":"196706","messageId":"20120808205752.GD12838@sigill.intra.peff.net","threadId":"31207","inReplyTo":"20120808205456.GB29528@sigill.intra.peff.net","subject":"[PATCH 8/4] check-docs: get documented command list from Makefile","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-08-08T20:57:52Z","receivedAt":"2012-08-08T20:57:52Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"The current code tries to get a list of documented commands\nby doing \"ls Documentation/git*txt\" and culling a bunch of\nspecial cases from the result. Looking for \"git-*.txt\" would\nbe more accurate, but would miss a few commands like\n\"gitweb\" and \"gitk\".\n\nFortunately, Documentation/Makefile already knows what this\nlist is, so we can just ask it. Annoyingly, we still have to\npost-process its output a little, since make will print\nextra cruft like \"GIT-VERSION-FILE is up to date\" to stdout.\n\nNow that our list is accurate, we can remove all of the ugly\nspecial-cases.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Documentation/Makefile |  3 +++\n Makefile               | 26 ++------------------------\n 2 files changed, 5 insertions(+), 24 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 063fa69..cf5916f 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -344,4 +344,7 @@ require-htmlrepo::\n quick-install-html: require-htmlrepo\n \t'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir)\n \n+print-man1:\n+\t@for i in $(MAN1_TXT); do echo $$i; done\n+\n .PHONY: FORCE\ndiff --git a/Makefile b/Makefile\nindex b9da511..51b3c6f 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2832,34 +2832,12 @@ check-docs::\n \t\tsed -e '/^#/d' \\\n \t\t    -e 's/[ \t].*//' \\\n \t\t    -e 's/^/listed /' command-list.txt; \\\n-\t\tls -1 Documentation/git*txt | \\\n+\t\t$(MAKE) -C Documentation print-man1 | \\\n+\t\tgrep '\\.txt$$' | \\\n \t\tsed -e 's|Documentation/|documented |' \\\n \t\t    -e 's/\\.txt//'; \\\n \t) | while read how cmd; \\\n \tdo \\\n-\t\tcase \"$$how,$$cmd\" in \\\n-\t\tdocumented,gitattributes | \\\n-\t\tdocumented,gitignore | \\\n-\t\tdocumented,gitmodules | \\\n-\t\tdocumented,gitcli | \\\n-\t\tdocumented,git-tools | \\\n-\t\tdocumented,gitcore-tutorial | \\\n-\t\tdocumented,gitcvs-migration | \\\n-\t\tdocumented,gitdiffcore | \\\n-\t\tdocumented,gitglossary | \\\n-\t\tdocumented,githooks | \\\n-\t\tdocumented,gitrepository-layout | \\\n-\t\tdocumented,gitrevisions | \\\n-\t\tdocumented,gittutorial | \\\n-\t\tdocumented,gittutorial-2 | \\\n-\t\tdocumented,git-bisect-lk2009 | \\\n-\t\tdocumented,git-remote-helpers | \\\n-\t\tdocumented,gitworkflows | \\\n-\t\tdocumented,gitcredentials | \\\n-\t\tdocumented,gitnamespaces | \\\n-\t\tdocumented,gitweb.conf | \\\n-\t\tsentinel,not,matching,is,ok ) continue ;; \\\n-\t\tesac; \\\n \t\tcase \" $(ALL_COMMANDS) \" in \\\n \t\t*\" $$cmd \"*)\t;; \\\n \t\t*) echo \"removed but $$how: $$cmd\" ;; \\\n-- \n1.7.12.rc2.36.gb1dc81b\n"},{"id":"196710","messageId":"7vwr19qd79.fsf@alter.siamese.dyndns.org","threadId":"31207","inReplyTo":"20120808205752.GD12838@sigill.intra.peff.net","subject":"Re: [PATCH 8/4] check-docs: get documented command list from Makefile","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-08T21:35:38Z","receivedAt":"2012-08-08T21:35:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> The current code tries to get a list of documented commands\n> by doing \"ls Documentation/git*txt\" and culling a bunch of\n> special cases from the result. Looking for \"git-*.txt\" would\n> be more accurate, but would miss a few commands like\n> \"gitweb\" and \"gitk\".\n>\n> Fortunately, Documentation/Makefile already knows what this\n> list is, so we can just ask it. Annoyingly, we still have to\n> post-process its output a little, since make will print\n> extra cruft like \"GIT-VERSION-FILE is up to date\" to stdout.\n\nYeah, traditional way to do this is to give special markers around\nwhat you want your Makefile to tell you, e.g.\n\n\tsayit:\n        \techo \"@@@ $(FOO) ###\"\n\tuseit:\n        \t$(MAKE) sayit | \\\n                sed -ne 's/^@@@ \\(.*\\) ###$/\\1/p' | \\\n                ... use it ...\n\nbut in this case we know we want \"*.txt\", so the way you filtered\nthe output is sufficient.\n\n> Now that our list is accurate, we can remove all of the ugly\n> special-cases.\n>\n> Signed-off-by: Jeff King <peff@peff.net>\n> ---\n>  Documentation/Makefile |  3 +++\n>  Makefile               | 26 ++------------------------\n\nYay, maintainability comes with a large line reduction bonus ;-)\n\nThanks.\n"},{"id":"196713","messageId":"C64F75694EC040349CFE91CD69EDB2DC@PhilipOakley","threadId":"31207","inReplyTo":"20120808205456.GB29528@sigill.intra.peff.net","subject":"Re: [PATCH 2/4] check-docs: update non-command documentation list","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-08-08T22:11:44Z","receivedAt":"2012-08-08T22:11:44Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"----- Original Message ----- \nFrom: \"Jeff King\" <peff@peff.net>\nTo: \"Junio C Hamano\" <gitster@pobox.com>\nCc: \"Matthieu Moy\" <Matthieu.Moy@imag.fr>; <git@vger.kernel.org>\nSent: Wednesday, August 08, 2012 9:54 PM\nSubject: Re: [PATCH 2/4] check-docs: update non-command documentation \nlist\n\n\n> On Wed, Aug 08, 2012 at 12:24:29PM -0700, Junio C Hamano wrote:\n>\n>> Jeff King <peff@peff.net> writes:\n>>\n>> > The check-docs target looks at Documentation/git*txt and\n>> > complains if any entry does not have a matching command.\n>> > Therefore we need to explicitly ignore any entries which are\n>> > not meant to describe a command (like gitattributes.txt).\n>> > This list has grown stale over time, so let's bring it up to\n>> > date.\n>> >\n>> > Signed-off-by: Jeff King <peff@peff.net>\n>> > ---\n>> > I really wonder if we would do better to match git-*.txt, since \n>> > most of\n>> > the ignores are gitfoo(7) types of pages. We'd probably want to add \n>> > back\n>> > in \"git\", \"gitweb\" and \"gitk\" explicitly, but they are already \n>> > handled\n>> > specially above and below.\n>>\n>> Quite possibly, yes.\n>\n> Actually, my \"already handled specially\" is not quite accurate. That\n> special list is \"things that are commands but are not necessarily\n> mentioned in the Makefile variables\". But this list is \"things that \n> are\n> documented but do not begin with git-\". The two should mostly be the\n> same, but the whole point of this exercise is to make sure they _are_\n> the same.\n>\n> A better solution is to simply ask the Documentation directory what \n> the\n> commands are, since it already knows (in the form of MAN1_TXT).\n>\n>> Also \"git gitk gitweb\" may want to be made into a Makefile variable\n>> to be shared in the \"above\" and \"below\" (I do not know what to call\n>> them offhand---they are programs with special build rules that are\n>> not covered by ALL/SCRIPT_LIB/BUILTIN).\n>\n> I couldn't think of a special name, either, but I think it is \n> sufficient\n> to just create a new ALL_COMMANDS variable that includes those other\n> things, and then add to it.\n>\n>> By the way, do we have a documentation for git-gui?  Perhaps it may\n>> want to be added to that \"git gitk gitweb\" list as a reminder that\n>> it lacks documentation.  One of the goals of the person who runs\n>> \"make check-docs\" should be to reduce the special case that appears\n>> at the beginning of that case statement.\n>\n> Yes, it should be checked (and git-citool, too).\n>\n>> I also wonder why \"help\" is not treated as a built-in?  Perhaps we\n>> should throw it in to \"git gitk gitweb\" list?  After all, it is a\n>> command that is available in \"git foo\" form, is documented, and is\n>> listed in the command-list.txt file.\n\nOne issue I notice a few weeks ago is that `git help --all` does not \nlist all of the available git help pages, rather it just limits itself \nto the available command pages.\n\nThis means that new users can't discover those additional help pages in \nany easy manner.\n\nI had an initial look at what might be involved in adding a --guides \noption, shifting the current --all to --cmd (or --command) and then \nmake --all list both commands and guides.\n\nThe need for help to list all the guides is parallel to these patches. I \ndidn't get that far in working out how to approach such a patch which \nwould discovere the available guides - I'm on GfW-msysgit which normally \nuses web display.\n\n>\n> Historically it was part of git.c, but these days it is a built-in and\n> does not need any special treatment from check-docs.\n>\n> Patches for all to follow (on top of my previous 4).\n>\n>  [5/4]: check-docs: factor out command-list\n>  [6/4]: check-docs: list git-gui as a command\n>  [7/4]: check-docs: drop git-help special-case\n>  [8/4]: check-docs: get documented command list from Makefile\n>\n> -Peff\n> --\n"},{"id":"196716","messageId":"7v1ujhq9om.fsf@alter.siamese.dyndns.org","threadId":"31207","inReplyTo":"C64F75694EC040349CFE91CD69EDB2DC@PhilipOakley","subject":"Re: [PATCH 2/4] check-docs: update non-command documentation list","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-08T22:51:37Z","receivedAt":"2012-08-08T22:51:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" <philipoakley@iee.org> writes:\n\n> One issue I notice a few weeks ago is that `git help --all` does not\n> list all of the available git help pages, rather it just limits itself\n> to the available command pages.\n>\n> This means that new users can't discover those additional help pages\n> in any easy manner.\n\nThat would be a problem _only_ if these \"additional help pages\" are\nof importance for new users.  I do not think things that come from\nDocumentation/technical and ARTICLES (in Documentation/Makefile)\nqualify as such.\n\nI'd be perfectly happy as long as all documents are reachable from\ngit.html in html-fied documentation (the man pages have equivalent\ncross references, I think).\n"},{"id":"196724","messageId":"676126318BF8488DBB65458177CBAC46@PhilipOakley","threadId":"31207","inReplyTo":"7v1ujhq9om.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/4] check-docs: update non-command documentation list","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-08-09T06:34:08Z","receivedAt":"2012-08-09T06:34:08Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" <gitster@pobox.com>\n> \"Philip Oakley\" <philipoakley@iee.org> writes:\n>\n>> One issue I notice a few weeks ago is that `git help --all` does not\n>> list all of the available git help pages, rather it just limits \n>> itself\n>> to the available command pages.\n>>\n>> This means that new users can't discover those additional help pages\n>> in any easy manner.\n>\n> That would be a problem _only_ if these \"additional help pages\" are\n> of importance for new users.  I do not think things that come from\n> Documentation/technical and ARTICLES (in Documentation/Makefile)\n> qualify as such.\n\nI'd generally agree with that. I wasn't aware of ARTICLES (in \nDocumentation/Makefile), so that's something to I'll need to look at.\n\n>\n> I'd be perfectly happy as long as all documents are reachable from\n> git.html in html-fied documentation (the man pages have equivalent\n> cross references, I think).\n>\n\nThat is generally the tack I was looking of taking. Part of the task is \nmaking sure the 'right' pages are found from the 'right' places. So \nthat, for the beginner needing help (git help --all),  even the \n'everyday  git in 20 commands' and 'User manual' would be listed in the \navailable guides section.\n\n>\n> -----\n"},{"id":"196729","messageId":"vpq7gt8biht.fsf@bauges.imag.fr","threadId":"31207","inReplyTo":"20120808183449.GD24574@sigill.intra.peff.net","subject":"Re: [PATCH 4/4] command-list: mention git-credential-* helpers","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-08-09T08:02:38Z","receivedAt":"2012-08-09T08:02:38Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jeff King <peff@peff.net> writes:\n\n> These commands were never added to the command-list. Adding\n> them makes \"make check-docs\" run without complaint.\n> While we're at it, let's capitalize the first letter of\n> their one-line summaries to match the rest of the git\n> manpages.\n\nYou may want to squash my patch in this one, since they really do the\nsame thing.\n\nIn any case, thanks for taking care of this, the patches sound good.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"}]}