{"thread":{"id":"2525","subject":"[RFC] Add support for short help to Cogito commands","startedAt":"2005-11-15T12:55:16Z","lastAt":"2005-11-16T17:18:45Z","messageCount":3,"participants":["Jonas Fonseca","Petr Baudis"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"11894","messageId":"20051115125516.GD13925@diku.dk","threadId":"2525","inReplyTo":null,"subject":"[RFC] Add support for short help to Cogito commands","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2005-11-15T12:55:16Z","receivedAt":"2005-11-15T12:55:16Z","isPatch":false,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Hi,\n\nI hope I am not the only one feeling that -h can sometimes be a little\ntoo verbose when you want to have a quick overview of a Cogito command.\nI'd like to make -h show only a short summary of the available options\nand keep the longer help text for --help. I have attached a patch that\ndoes something like this. Example:\n\n  $ cg diff -h\n  Usage: cg-diff [-c] [-m] [-s] [-p] [-r FROM_ID[..TO_ID]] [FILE]...\n\n  Options:\n    -c                   Colorize the diff output\n    -p                   Use parent commit to specified ID\n    -s                   Summarize the diff\n    -r FROM_ID[..TO_ID]  Specify the revisions to diff\n    -m                   Base the diff at the merge base of specified revision\n    -h                   Print short usage help\n    --help               Print long usage help\n\nIf something like this is acceptable, I'd like to know how to proceed\nwith improving the option captions. I've considered two possibilities:\n\n - Get the caption from the first line of the option description.  This\n   is similar to what the patch does (it also roughly removes everything\n   after the first punctuation char). But it will require that all\n   option descriptions are changed to have a one line caption at the\n   start. Example:\n\n\t# ...\n\t#\n\t# -r FROM_ID[..TO_ID]::\n\t#\tSpecify revisions to diff. Revisions can be specified\n\t#\tusing either '-r rev1 ...\n\n - Add a special line with the caption. Since we already 'filters' the\n   help text in the script headers this could go after the '::'.\n   Example:\n\n\t# ...\n\t#\n\t# -r FROM_ID[..TO_ID]:: Specify revisions to diff\n\t#\tSpecify the revisions to diff using either '-r rev1\n\t#\t...\n\n   So that it will be easy to remove from the --help output and from the\n   generated manpages.\n\nThe last option is less intrusive, but does make the syntax of the\nscript headers less clean. Comments?\n\ndiff --git a/cg-Xlib b/cg-Xlib\nindex fa3a059..a1c89dc 100755\n--- a/cg-Xlib\n+++ b/cg-Xlib\n@@ -347,18 +347,39 @@ deprecated_alias()\n \n print_help()\n {\n-\twhich \"cg-$1\" >/dev/null 2>&1 || exit 1\n+\twhich \"cg-$2\" >/dev/null 2>&1 || exit 1\n \tsed -n '/^USAGE=/,0s/.*\"\\(.*\\)\"/Usage: \\1/p;\n-\t        /^deprecated_alias/,0s/^deprecated_alias \\([^ ]*\\)/\\1 is the new name for/p' < $(which cg-$1) \n+\t        /^deprecated_alias/,0s/^deprecated_alias \\([^ ]*\\)/\\1 is the new name for/p' < $(which cg-$2) \n \techo\n-\tsed -n '3,/^$/s/^# *//p' < $(which cg-$1)\n+\tif [ x\"$1\" = xshort ]; then\n+\t\techo \"Options:\"\n+\t\t_cg_fmt=\"  %-20s %s\\n\"\n+\t\tsed -n '/# \\(-.*::\\)/,/^#/s/#//p' < $(which cg-$2) | while read line; do\n+\t\t\tcase \"$line\" in\n+\t\t\t-*::)\n+\t\t\t\t_cg_option=\"$(echo -n \" $line\" | sed 's/ \\(-.*\\)::/\\1/')\"\n+\t\t\t\t;;\n+\t\t\t*)\n+\t\t\t\tprintf \"$_cg_fmt\" \"$_cg_option\" \\\n+\t\t\t\t\t\"$(echo \"$line\" | sed 's/\\([^-][^.,]*\\)[.,].*/\\1/')\"\n+\t\t\t\t_cg_option=\n+\t\t\t\t;;\n+\t\t\tesac\n+\t\tdone\n+\t\tprintf \"$_cg_fmt\" \"-h\" \"Print short usage help\"\n+\t\tprintf \"$_cg_fmt\" \"--help\" \"Print long usage help\"\n+\telse\n+\t\tsed -n '3,/^$/s/^# *//p' < $(which cg-$2)\n+\tfi\n \texit\n }\n \n for option in \"$@\"; do\n \t[ x\"$option\" = x-- ] && break\n-\tif [ x\"$option\" = x\"-h\" -o x\"$option\" = x\"--help\" ]; then\n-\t\tprint_help ${_cg_cmd##cg-}\n+\tif [ x\"$option\" = x\"-h\" ]; then\n+\t\tprint_help short ${_cg_cmd##cg-}\n+\telif [ x\"$option\" = x\"--help\" ]; then\n+\t\tprint_help long ${_cg_cmd##cg-}\n \tfi\n done\n \n-- \nJonas Fonseca\n"},{"id":"11944","messageId":"20051115221756.GX30496@pasky.or.cz","threadId":"2525","inReplyTo":"20051115125516.GD13925@diku.dk","subject":"Re: [RFC] Add support for short help to Cogito commands","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2005-11-15T22:17:56Z","receivedAt":"2005-11-15T22:17:56Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"  Hi,\n\nDear diary, on Tue, Nov 15, 2005 at 01:55:16PM CET, I got a letter\nwhere Jonas Fonseca <fonseca@diku.dk> said that...\n> I hope I am not the only one feeling that -h can sometimes be a little\n> too verbose when you want to have a quick overview of a Cogito command.\n> I'd like to make -h show only a short summary of the available options\n> and keep the longer help text for --help. I have attached a patch that\n> does something like this. Example:\n\nGood idea. Perhaps even make this default for --help as well and offer\n--long-help. cg-help would still default to the long help, unless -s or\nsomething would be passed to it.\n\n>  - Add a special line with the caption. Since we already 'filters' the\n>    help text in the script headers this could go after the '::'.\n>    Example:\n> \n> \t# ...\n> \t#\n> \t# -r FROM_ID[..TO_ID]:: Specify revisions to diff\n> \t#\tSpecify the revisions to diff using either '-r rev1\n> \t#\t...\n> \n>    So that it will be easy to remove from the --help output and from the\n>    generated manpages.\n> \n> The last option is less intrusive, but does make the syntax of the\n> script headers less clean. Comments?\n\nI prefer the second option and don't think it's much less clean. I think\nit would be actually uglier the other way - strange without separating\nempty line, too long with the separating line.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nVI has two modes: the one in which it beeps and the one in which\nit doesn't.\n"},{"id":"12020","messageId":"20051116171845.GA15533@diku.dk","threadId":"2525","inReplyTo":"20051115221756.GX30496@pasky.or.cz","subject":"[PATCH] Add short help to Cogito commands","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2005-11-16T17:18:45Z","receivedAt":"2005-11-16T17:18:45Z","isPatch":true,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Captions for all 74 Cogito options are added to the script headers on\nthe same line as the option being documented. The preferred syntax is\nnow:\n\n\t# <option>:: <caption>\n\t#\t<description>\n\nThe old help message (the complete user manual) is moved to --long-help\nand -h and --help both will now show the short help message. Output of\ncg-help <cmd> is untouched. In the progress, rewrite cg-Xlib's\nprint_help to use one built-in type -P instead of multiple which's.\n\nDocumentation scripts (to generate cg-manpages and the long help\nmessages) has been updated to ignore the option captions.\n\nMissing description of cg-admin-ls -t option was added.\n\nSigned-off-by: Jonas Fonseca <fonseca@diku.dk>\n\n---\nPetr Baudis <pasky@suse.cz> wrote Tue, Nov 15, 2005:\n>   Hi,\n> \n> Dear diary, on Tue, Nov 15, 2005 at 01:55:16PM CET, I got a letter\n> where Jonas Fonseca <fonseca@diku.dk> said that...\n> > I hope I am not the only one feeling that -h can sometimes be a little\n> > too verbose when you want to have a quick overview of a Cogito command.\n> > I'd like to make -h show only a short summary of the available options\n> > and keep the longer help text for --help. I have attached a patch that\n> > does something like this. Example:\n> \n> Good idea. Perhaps even make this default for --help as well and offer\n> --long-help. cg-help would still default to the long help, unless -s or\n> something would be passed to it.\n\nAgree, I didn't do the cg-help -s switch. The patch is overloaded as it\nis. ;)\n\n> >  - Add a special line with the caption. Since we already 'filters' the\n> >    help text in the script headers this could go after the '::'.\n> >    Example:\n> > \n> > \t# ...\n> > \t#\n> > \t# -r FROM_ID[..TO_ID]:: Specify revisions to diff\n> > \t#\tSpecify the revisions to diff using either '-r rev1\n> > \t#\t...\n> > \n> >    So that it will be easy to remove from the --help output and from the\n> >    generated manpages.\n> > \n> > The last option is less intrusive, but does make the syntax of the\n> > script headers less clean. Comments?\n> \n> I prefer the second option and don't think it's much less clean. I think\n> it would be actually uglier the other way - strange without separating\n> empty line, too long with the separating line.\n\nIt is easier to sed out too. Although it would be nice for it to \"fall\nback\" to what ever was on the first line if somebody didn't write an\noption caption. Sort of the best of both. Anyway here goes...\n\ndiff --git a/Documentation/make-cg-asciidoc b/Documentation/make-cg-asciidoc\nindex 7ea5c23..00e4ce7 100755\n--- a/Documentation/make-cg-asciidoc\n+++ b/Documentation/make-cg-asciidoc\n@@ -42,7 +42,7 @@ CAPTION=$(echo \"$HEADER\" | head -n 1 | t\n # were referenced as \"`cg-command`\". This way references from cg-* combos in\n # code listings will be ignored.\n BODY=$(echo \"$HEADER\" | sed '0,/^$/d' \\\n-\t\t      | sed 's/`\\(cg-[a-z-]\\+\\)`/gitlink:\\1[1]/')\n+\t\t      | sed 's/`\\(cg-[a-z-]\\+\\)`/gitlink:\\1[1]/;s/^\\(-.*\\)::.*/\\1::/')\n \n DESCRIPTION=\n OPTIONS=\n@@ -100,7 +100,10 @@ OPTIONS\n $OPTIONS\n \n -h, --help::\n-\tPrint usage help.\n+\tPrint usage summary.\n+\n+--long-help::\n+\tPrint user manual. The same as found in $TITLE.\n \n $MISC\n \ndiff --git a/Documentation/make-cogito-asciidoc b/Documentation/make-cogito-asciidoc\nindex fbd88ff..3bd0e9f 100755\n--- a/Documentation/make-cogito-asciidoc\n+++ b/Documentation/make-cogito-asciidoc\n@@ -83,7 +83,7 @@ individual commands, do e.g.\n \n or\n \n-\tcg-log --help\n+\tcg-log --long-help\n \n Regular commands\n ~~~~~~~~~~~~~~~~\ndiff --git a/cg b/cg\nindex f501fb4..08aaf22 100755\n--- a/cg\n+++ b/cg\n@@ -18,7 +18,7 @@\n #\n # OPTIONS\n # -------\n-# --version::\n+# --version:: Show the Cogito toolkit version\n #\tShow the version of the Cogito toolkit. Equivalent to the output\n #\tof `cg-version`.\n \ndiff --git a/cg-Xlib b/cg-Xlib\nindex fa3a059..dedbb62 100755\n--- a/cg-Xlib\n+++ b/cg-Xlib\n@@ -347,18 +347,41 @@ deprecated_alias()\n \n print_help()\n {\n-\twhich \"cg-$1\" >/dev/null 2>&1 || exit 1\n+\t_cg_cmd=$(type -P \"cg-$2\")\n+\t[ -n \"$_cg_cmd\" ] || exit 1\n+\n \tsed -n '/^USAGE=/,0s/.*\"\\(.*\\)\"/Usage: \\1/p;\n-\t        /^deprecated_alias/,0s/^deprecated_alias \\([^ ]*\\)/\\1 is the new name for/p' < $(which cg-$1) \n+\t        /^deprecated_alias/,0s/^deprecated_alias \\([^ ]*\\)/\\1 is the new name for/p' < \"$_cg_cmd\"\n \techo\n-\tsed -n '3,/^$/s/^# *//p' < $(which cg-$1)\n+\tif [ x\"$1\" = xlong ]; then\n+\t\t# TODO: Reduce this to just one sed if possible.\n+\t\tsed -n '3,/^$/s/^# *//p' < \"$_cg_cmd\" | sed 's/^\\(-.*\\)::.*/\\1::/'\n+\t\texit\n+\tfi\n+\n+\techo \"Options:\"\n+\t_cg_fmt=\"  %-20s %s\\n\"\n+\tsed -n 's/# \\(-.*\\)::[^A-Za-z0-9]\\(.*\\)/\\1\\n\\2/p' < \"$_cg_cmd\" | while read line; do\n+\t\tcase \"$line\" in\n+\t\t-*)\n+\t\t\t_cg_option=\"$line\"\n+\t\t\t;;\n+\t\t*)\n+\t\t\tprintf \"$_cg_fmt\" \"$_cg_option\" \"$line\"\n+\t\t\t;;\n+\t\tesac\n+\tdone\n+\tprintf \"$_cg_fmt\" \"-h, --help\" \"Print usage summary\"\n+\tprintf \"$_cg_fmt\" \"--long-help\" \"Print user manual\"\n \texit\n }\n \n for option in \"$@\"; do\n \t[ x\"$option\" = x-- ] && break\n-\tif [ x\"$option\" = x\"-h\" -o x\"$option\" = x\"--help\" ]; then\n-\t\tprint_help ${_cg_cmd##cg-}\n+\tif [ x\"$option\" = x\"-h\" ] || [ x\"$option\" = x\"--help\" ]; then\n+\t\tprint_help short ${_cg_cmd##cg-}\n+\telif [ x\"$option\" = x\"--long-help\" ]; then\n+\t\tprint_help long ${_cg_cmd##cg-}\n \tfi\n done\n \ndiff --git a/cg-add b/cg-add\nindex fda4500..a50c0ac 100755\n--- a/cg-add\n+++ b/cg-add\n@@ -17,11 +17,12 @@\n #\n # OPTIONS\n # -------\n-# -N::\n+# -N::\tUpdate the lowlevel cache file\n #\tOnly update the cache: do not copy the data into the object database.\n #\tThis is for special purposes when you might not actually _have_ any\n #\tobject database. This option is normally not interesting.\n-# -r::\n+#\n+# -r::\tAdd files recursively\n #\tIf you pass cg-add this flag and any directory names, it will try\n #\tto add files in those directories recursively (with regard to your\n #\tignore rules - see cg-status documentation for more detailed\ndiff --git a/cg-admin-cat b/cg-admin-cat\nindex 8435bf2..89016d9 100755\n--- a/cg-admin-cat\n+++ b/cg-admin-cat\n@@ -8,7 +8,7 @@\n #\n # OPTIONS\n # -------\n-# -r TREE_ID::\n+# -r TREE_ID:: Look for file in the given revision or tree\n #\tID of the revision or tree where to look for the file, instead of\n #\tHEAD.\n \ndiff --git a/cg-admin-ls b/cg-admin-ls\nindex 57e3ffb..240d927 100755\n--- a/cg-admin-ls\n+++ b/cg-admin-ls\n@@ -6,6 +6,13 @@\n # Optionally takes a commit or tree ID as a parameter, defaulting to\n # 'HEAD'.\n #\n+# OPTIONS\n+# -------\n+# -t TREE_ID:: List content of the given TREE_ID\n+#\tList the content of the given TREE_ID.\n+#\n+# OUTPUT FORMAT\n+# -------------\n # Each line in the output has the following format:\n #\n #\t<mode>\t<type>\t<sha1>\t<name>\ndiff --git a/cg-admin-setuprepo b/cg-admin-setuprepo\nindex 5affa7f..34d387f 100755\n--- a/cg-admin-setuprepo\n+++ b/cg-admin-setuprepo\n@@ -28,7 +28,7 @@\n #\n # OPTIONS\n # -------\n-# -g GROUP::\n+# -g GROUP:: Specify group ownership for the repository \n #\tName of the UNIX group covering the users authorized to push into\n #\tthe repository. If unspecified, only you (who ran this command) will\n #\thave write (push) access.\ndiff --git a/cg-admin-uncommit b/cg-admin-uncommit\nindex 9357394..cc67ec2 100755\n--- a/cg-admin-uncommit\n+++ b/cg-admin-uncommit\n@@ -11,7 +11,7 @@\n #\n # OPTIONS\n # -------\n-# -t::\n+# -t:: Restore the working copy of the previous commit\n #\tThis optional parameter makes `cg-admin-uncommit` to roll back\n #\tthe tree as well to the previous commit. Without this option\n #\t(by default) 'Cogito' keeps the tree in its current state,\ndiff --git a/cg-clean b/cg-clean\nindex 1cc1ae8..6e2d1df 100755\n--- a/cg-clean\n+++ b/cg-clean\n@@ -9,16 +9,16 @@\n #\n # OPTIONS\n # -------\n-# -d::\n+# -d:: Clean directories\n #\tAlso clean directories and their contents.\n #\n-# -D::\n+# -D:: Clean directories more thoroughly\n #\tSame as -d but try harder (change permissions first).\n #\n-# -q::\n+# -q:: Silence progress reporting\n #\tQuiet - don't report what's being cleaned.\n #\n-# -x::\n+# -x:: Clean files ignored by cg-status\n #\tAlso clean files ignored by cg-status, such as object files.\n \n USAGE=\"cg-clean [-d] [-D] [-q] [-x]\"\ndiff --git a/cg-clone b/cg-clone\nindex c677ecd..f9f3f22 100755\n--- a/cg-clone\n+++ b/cg-clone\n@@ -13,7 +13,7 @@\n #\n # OPTIONS\n # -------\n-# -l::\n+# -l::\tSymlink the object database when cloning locally\n #\tSymlink the object database when cloning locally, instead of\n #\thardlinking all the objects. This is suitable for very fast\n #\tcloning of arbitrarily big repositories, but might be a trouble\n@@ -23,7 +23,8 @@\n #\tas well. The choice is yours.\n #\tNote that you MUST NOT prune repository containing a symlink\n #\tor being symlinked to.\n-# -s::\n+#\n+# -s::\tClone into the current directory\n #\tClone in the current directory instead of creating a new one.\n #\tSpecifying both -s and a destination directory makes no sense.\n \ndiff --git a/cg-commit b/cg-commit\nindex 33bb17d..f413396 100755\n--- a/cg-commit\n+++ b/cg-commit\n@@ -17,44 +17,44 @@\n #\n # OPTIONS\n # -------\n-# -c COMMIT_ID::\n+# -c COMMIT_ID:: Copy author info and commit message from COMMIT_ID\n #\tCopy the commit from a given commit ID (that is the author information\n #\tand the commit message - NOT committer information). This option\n #\tis typically used when replaying commits from one lineage or\n #\trepository to another.\n #\n-# -C::\n+# -C:: Ignore cache\n #\tMake `cg-commit` ignore the cache and just commit the thing as-is.\n #\tNote, this is used internally by 'Cogito' when merging, and it is\n #\talso useful when you are performing the initial commit manually. This\n #\toption does not make sense when files are given on the command line.\n #\n-# -m MESSAGE::\n+# -m MESSAGE:: Specify commit message\n #\tSpecify the commit message, which is used instead of starting\n #\tup an editor (if the input is not `stdin`, the input is appended\n #\tafter all the '-m' messages). Multiple '-m' parameters are appended\n #\tto a single commit message, each as separate paragraph.\n #\n-# -e::\n+# -e:: Force message editing of messages given with -m\n #\tForce the editor to be brought up even when '-m' parameters were\n #\tpassed to `cg-commit`.\n #\n-# -E::\n+# -E:: Force message editing and commit the result\n #\tForce the editor to be brought up and do the commit even if\n #\tthe default commit message is not changed.\n #\n-# -f::\n+# -f:: Force commit when no changes has been made\n #\tForce the commit even when there's \"nothing to commit\", that is\n #\tthe tree is the same as the last time you committed, no changes\n #\thappened.\n #\n-# -N::\n+# -N:: Only update the cache\n #\tDon't add the files to the object database, just update the caches\n #\tand the commit information. This is for special purposes when you\n #\tmight not actually _have_ any object database. This option is\n #\tnormally not interesting.\n #\n-# -q::\n+# -q:: Be very very quiet\n #\tBe quiet in case there's \"nothing to commit\", and silently exit\n #\treturning success. In a sense, this is the opposite to '-f'.\n #\ndiff --git a/cg-diff b/cg-diff\nindex 628be53..0572170 100755\n--- a/cg-diff\n+++ b/cg-diff\n@@ -10,26 +10,26 @@\n #\n # OPTIONS\n # -------\n-# -c::\n+# -c:: Colorize\n #\tColorize the diff output\n #\n-# -p::\n+# -p:: Use ID parent\n #\tShow diff to the parent of the current commit (or the commit\n #\tspecified by the -r parameter).\n #\n-# -s::\n+# -s:: Summarize and show diff stat\n #\tSummarize the diff by showing a histogram for removed and added\n #\tlines (similar to the output of diffstat(1)) and information\n #\tabout added and renamed files and mode changes.\n #\n-# -r FROM_ID[..TO_ID]::\n+# -r FROM_ID[..TO_ID]:: Limit to revision range\n #\tSpecify the revisions to diff using either '-r rev1..rev2' or\n #\t'-r rev1 -r rev2'. If no revision is specified, the current\n #\tworking tree is implied. Note that no revision is different from\n #\tempty revision which means '-r rev..' compares between 'rev' and\n #\t'HEAD', while '-r rev' compares between 'rev' and working tree.\n #\n-# -m::\n+# -m:: Base the diff at the merge base\n #\tBase the diff at the merge base of the -r arguments (defaulting\n #\tto HEAD and origin).\n #\ndiff --git a/cg-fetch b/cg-fetch\nindex c406c9a..5a2039f 100755\n--- a/cg-fetch\n+++ b/cg-fetch\n@@ -25,10 +25,10 @@\n #\n # OPTIONS\n # -------\n-# -f::\n+# -f:: Force the complete fetch even if the heads are the same.\n #\tForce the complete fetch even if the heads are the same.\n #\n-# -v::\n+# -v:: Enable verbosity\n #\tDisplay more verbose output.\n #\n # ENVIRONMENT\ndiff --git a/cg-help b/cg-help\nindex ddec1b9..6ba7657 100755\n--- a/cg-help\n+++ b/cg-help\n@@ -13,7 +13,7 @@\n #\n # OPTIONS\n # -------\n-# -c::\n+# -c::\tColorize\n #\tColorize the output.\n \n USAGE=\"cg-help [-c] [cg-COMMAND | COMMAND]\"\n@@ -33,6 +33,7 @@ setup_colors()\n \tlocal copyright=\"$(tput setaf 4)\"\n \n \tapply_colors=\"\n+\ts/^\\(-.*\\)::.*/$desclist\\1$color_none:/\n \ts/^\\(.*\\)::/$desclist\\1$color_none:/\n \ts/\\`\\(cg-[a-z-]*\\)\\`/$cgcmd\\1$color_none/g\n \ts/\\`\\([^\\`]*\\)\\`/$codesnippet&$color_none/g\n@@ -90,7 +91,7 @@ elif [ \"$ARGS\" = \"tag\" ]; then\n \texit\n elif [ \"$ARGS\" ]; then\n \tcmd=$(echo \"${ARGS[0]}\" | sed 's/^cg-//')\n-\tprint_help $cmd | colorize\n+\tprint_help long $cmd | colorize\n \t[ \"${PIPESTATUS[0]}\" -eq 0 ] && exit\n \techo \"cg-help: no help available for command \\\"${ARGS[0]}\\\"\"\n \techo \"Call cg-help without any arguments for the list of available commands\"\n@@ -126,6 +127,6 @@ These expressions can be used interchang\n \n For details on individual commands, do e.g.:\n \tcg-help cg-log\n-\tcg-log --help\n+\tcg-log --long-help\n (both variants are equivalent)\n __END__\ndiff --git a/cg-init b/cg-init\nindex 0ee264e..a0a7372 100755\n--- a/cg-init\n+++ b/cg-init\n@@ -13,22 +13,22 @@\n #\n # OPTIONS\n # -------\n-# -e EXCLUDEPATTERN::\n+# -e EXCLUDEPATTERN:: Ignore files matching EXCLUDEPATTERN\n #\tIgnore files matching this pattern when importing files for the\n #\tinitial commit. Note that if you are importing any .gitignore\n #\tfiles, they will be considered as well. If you want to make\n #\ten even more custom choice of files to be imported, use the -I\n #\tparameter and add and perform the initial commit manually.\n #\n-# -I::\n+# -I:: No initial commit\n #\tDo not perform the initial commit. You can perform the initial commit\n #\tmanually later, but you will need to pass cg-commit the -C parameter.\n #\n-# -m MESSAGE::\n+# -m MESSAGE:: Specify initial commit message\n #\tSpecify the commit message for the initial commit. See `cg-commit`\n #\tdocumentation for details.\n #\n-# -N::\n+# -N:: Only update the cache\n #\tOnly update the cache: do not copy the data into the object database.\n #\tThis is for special purposes when you might not actually _have_ any\n #\tobject database. This option is normally not interesting.\ndiff --git a/cg-log b/cg-log\nindex 710ce7b..89fe063 100755\n--- a/cg-log\n+++ b/cg-log\n@@ -13,7 +13,7 @@\n # Arguments not interpreted as options will be interpreted as filenames;\n # cg-log then displays only changes in those files.\n #\n-# -c::\n+# -c::\tColorize\n #\tColorize the output. The used colors are listed below together\n #\twith information about which log output (summary, full or both)\n #\tthey apply to:\n@@ -26,10 +26,10 @@\n #\t\t- `date`:\t'green'\t\t(summary)\n #\t\t- `trim_mark`:\t'magenta'\t(summary)\n #\n-# -f::\n+# -f::\tList affected files\n #\tList affected files. (No effect when passed along `-s`.)\n #\n-# -r FROM_ID[..TO_ID]::\n+# -r FROM_ID[..TO_ID]:: Limit to a set of revisions\n #\tLimit the log information to a set of revisions using either\n #\t'-r FROM_ID[..TO_ID]' or '-r FROM_ID -r TO_ID'. In both cases the\n #\toption expects IDs which resolve to commits and will include the\n@@ -37,31 +37,31 @@\n #\tto the initial commit is shown. If no revisions is specified,\n #\tthe log information starting from 'HEAD' will be shown.\n #\n-# -d DATE::\n+# -d DATE:: Limit to revisions newer than given DATE\n #\tLimit the log information to revisions newer than given DATE,\n #\tand on second time further restrain it to revisions older than\n #\tgiven date. Therefore, '-d \"2 days ago\" -d \"yesterday\"' will\n #\tshow all the commits from the day before yesterday.\n #\n-# -m::\n+# -m::\tEnd the log at the merge base of the revision set\n #\tEnd the log listing at the merge base of the -r arguments\n #\t(defaulting to HEAD and origin).\n #\n-# -M, --no-merges::\n+# -M, --no-merges:: Ignore merge commits\n #\tDon't display merge commits in the log.\n #\n-# -s::\n+# -s::\tSummarize the log entries\n #\tShow a one line summary for each log entry. The summary contains\n #\tinformation about the commit date, the author, the first line\n #\tof the commit log and the commit ID. Long author names and commit\n #\tIDs are trimmed and marked with an ending tilde (~).\n #\n-# --summary::\n+# --summary:: Group commits by title\n #\tGenerate the changes summary, listing the commit titles grouped\n #\tby their author. This is also known as a \"shortlog\", suitable\n #\te.g. for contribution summaries of announcements.\n #\n-# -uUSERNAME::\n+# -uUSERNAME:: Limit to commit where author/committer matches USERNAME\n #\tList only commits where author or committer contains 'USERNAME'.\n #\tThe search for 'USERNAME' is case-insensitive.\n #\ndiff --git a/cg-merge b/cg-merge\nindex 0e6066d..1087951 100755\n--- a/cg-merge\n+++ b/cg-merge\n@@ -34,17 +34,17 @@\n #\n # OPTIONS\n # -------\n-# -b BASE_COMMIT::\n+# -b BASE_COMMIT:: Specify the base commit for the merge\n #\tParameter specifies the base commit for the merge. Otherwise, the\n #\tleast common ancestor is automatically selected.\n #\n-# -c::\n+# -c:: Disable autocommitting\n #\tParameter specifies that you want to have tree merge never\n #\tautocommitted, but want to review and commit it manually. This will\n #\tbasically make cg-merge always behave like there were conflicts\n #\tduring the merge.\n #\n-# -j::\n+# -j:: Join current branch with BRANCH_NAME\n #\tJoin the current branch and BRANCH_NAME together. This makes sense\n #\twhen the branches have no common history, meaning they are actually\n #\tnot branches related at all as far as GIT is concerned. Merging such\n@@ -52,7 +52,7 @@\n #\tyou do not want; but equally likely, you may actually WANT to join\n #\tthe projects together, which is what this option does.\n #\n-# --squash::\n+# --squash:: Use \"squash\" merge to record pending commits as a single merge commit\n #\t\"Squash\" merge - condense all the to-be-merged commits to a single\n #\tmerge commit. This means \"throw away history of the branch I'm\n #\tmerging\", essentially like in CVS or SVN, with the same problem -\ndiff --git a/cg-mkpatch b/cg-mkpatch\nindex afaeff1..8982056 100755\n--- a/cg-mkpatch\n+++ b/cg-mkpatch\n@@ -13,14 +13,14 @@\n #\n # OPTIONS\n # -------\n-# -d DIRNAME::\n+# -d DIRNAME:: Create patches in the DIRNAME directory\n #\tSplit the patches to separate files with their names in the\n #\tformat \"%02d.patch\", created in directory DIRNAME (will be\n #\tcreated if non-existent). Note that this makes sense only\n #\twhen generating patch series, that is when you use the -r\n #\targument.\n #\n-# -f FORMAT::\n+# -f FORMAT:: Specify patch file name format\n #\tFormat string used for generating the patch filename when\n #\toutputting the split-out patches (that is, passed the -d\n #\toption). This is by default \"%s/%02d-%s.patch\". The first %s\n@@ -28,11 +28,11 @@\n #\tsequence number. The last %s is mangled first line of the\n #\tcommit message - kind of patch title.\n #\n-# -m::\n+# -m::\tBase the diff at the merge base\n #\tBase the patches at the merge base of the -r arguments\n #\t(defaulting to HEAD and origin).\n #\n-# -r FROM_ID[..TO_ID]::\n+# -r FROM_ID[..TO_ID]::\tLimit to revision range\n #\tSpecify a set of commits to make patches from using either\n #\t'-r FROM_ID[..TO_ID]' or '-r FROM_ID -r TO_ID'. In both cases the\n #\toption expects IDs which resolve to commits and will include the\n@@ -40,7 +40,7 @@\n #\tfrom 'FROM_ID' to the initial commit will be generated. If no\n #\t`-r` option is given the commit ID defaults to 'HEAD'.\n #\n-# -s::\n+# -s:: Omit patch header\n #\tSpecify whether to print a short version of the patch without\n #\ta patch header with meta info such as author and committer.\n #\ndiff --git a/cg-object-id b/cg-object-id\nindex fde2e2b..f2cb54e 100755\n--- a/cg-object-id\n+++ b/cg-object-id\n@@ -8,22 +8,22 @@\n #\n # OPTIONS\n # -------\n-# -c::\n+# -c:: Get commit ID\n #\tGet ID of commit matching the object ID (error out if it is not\n #\ta commit). This is the default if you do not pass any parameter\n #\tas well, but that is only for the human usage. For clarity, all\n #\tscripted usage of cg-object-id should use -c explicitly if it\n #\twants a commit.\n #\n-# -n::\n+# -n:: Disable object type checking\n #\tNormalize only - don't check the object type.\n #\n-# -p::\n+# -p:: Get parent commit ID(s)\n #\tGet ID of the first parent commit of a given revision or HEAD.\n #\tNOTE: Multiple SHA1s separated by newlines will be returned for\n #\tcommits with multiple parents.\n #\n-# -t::\n+# -t:: Get tree ID\n #\tGet ID of tree associated with given commit or HEAD.\n #\n # OBJECT_ID::\ndiff --git a/cg-patch b/cg-patch\nindex 153376e..d567b8e 100755\n--- a/cg-patch\n+++ b/cg-patch\n@@ -12,7 +12,7 @@\n #\n # OPTIONS\n # -------\n-# -R::\n+# -R:: Apply in reverse\n #\tApplies the patch in reverse (therefore effectively unapplies it)\n #\n # Takes the diff on stdin.\ndiff --git a/cg-push b/cg-push\nindex d63fb65..b4361e3 100755\n--- a/cg-push\n+++ b/cg-push\n@@ -14,7 +14,7 @@\n #\n # OPTIONS\n # -------\n-# -t TAG::\n+# -t TAG:: Push the given TAG\n #\tTells cg-push to also push the given tag. Note that in the\n #\tfuture, cg-push should push tags automatically. Also note\n #\tthat even if you pass `cg-push` the '-t' arguments, your\ndiff --git a/cg-reset b/cg-reset\nindex f2e92eb..eb25fb1 100755\n--- a/cg-reset\n+++ b/cg-reset\n@@ -16,7 +16,7 @@\n #\n # OPTIONS\n # -------\n-# --adds-removes::\n+# --adds-removes:: Only reset info about added and removed files\n #\tReset ONLY the so-called \"index\" file. This effectively means that\n #\tany adds and removes you did will be unrecorded (but if you removed\n #\tthe file physically as well, that will not be undone - run\ndiff --git a/cg-restore b/cg-restore\nindex f864b64..348f552 100755\n--- a/cg-restore\n+++ b/cg-restore\n@@ -23,12 +23,13 @@\n #\n # OPTIONS\n # -------\n-# -f::\n+# -f:: Undo local changes since last commit\n #\tRestore even locally modified files to the version as of\n #\tthe last commit. Take care!\n-# -r COMMIT_ID::\n-# -r TREE_ID::\n-# -r BLOB_ID::\n+#\n+# -r COMMIT_ID:: Restore files to given COMMIT_ID\n+# -r TREE_ID:: Restore files to given TREE_ID\n+# -r BLOB_ID:: Restore files to given BLOB_ID\n #\tRestore the file to the state appropriate to the given ID.\n #\tThe list of files to recover is mandatory in this case.\n \ndiff --git a/cg-rm b/cg-rm\nindex 4b7e5ee..2fea342 100755\n--- a/cg-rm\n+++ b/cg-rm\n@@ -8,9 +8,10 @@\n #\n # OPTIONS\n # -------\n-# -f::\n+# -f:: Force removal of the physical files\n #\tAlso delete the files from the tree physically.\n-# -n::\n+#\n+# -n:: Keep the physical files\n #\tDo not delete the files from the tree physically, if they are\n #\tstill there. So it effectively just makes Cogito to stop caring\n #\tabout the file. This is the default.\ndiff --git a/cg-status b/cg-status\nindex 2cb86be..61c41c8 100755\n--- a/cg-status\n+++ b/cg-status\n@@ -34,21 +34,21 @@\n # If neither -g or -w is passed, both is shown; otherwise, only the\n # corresponding parts are shown.\n #\n-# -g::\n+# -g:: Show the GIT repository information\n #\tShow the GIT repository information.\n #\n-# -n::\n+# -n:: Do not show status flags\n #\tDo not show status flags. This is probably useful only when you filter\n #\tthe flags for a single specific flag using the '-s' option.\n #\n-# -s STATUS::\n+# -s STATUS:: Limit to files matching the STATUS flags\n #\tShow only files with the given status flag, e.g. '-s D'. You can list\n #\tmultiple flags ('-s MmA') to filter for all of them.\n #\n-# -w::\n+# -w:: Show working files\n #\tShow the working tree file list.\n #\n-# -x::\n+# -x:: Disable file exclusion\n #\tDon't exclude any files from listing.\n #\n # DIRPATH::\ndiff --git a/cg-switch b/cg-switch\nindex 4f7994b..4ab160c 100755\n--- a/cg-switch\n+++ b/cg-switch\n@@ -11,19 +11,19 @@\n #\n # OPTIONS\n # -------\n-# -f::\n+# -f:: Enable overwriting of existing branches\n #\tForce the branch's head pointer update even if the branch\n #\talready exists. WARNING: The pointer to the original contents\n #\tof the branch will be lost! The contents itself will not be\n #\tdeleted, `git-fsck-objects --unreachable` might help you to\n #\tfind it.\n #\n-# -n::\n+# -n:: No switch; only create and update the branch\n #\tDo not switch your current branch to the given branch. This\n #\twill make cg-switch to only create or update the branch, but\n #\tleave your working copy alone.\n #\n-# -r COMMIT_ID::\n+# -r COMMIT_ID:: Branch off the given COMMIT_ID\n #\tPoint the branch at the given commit. Defaults to the current\n #\tcommit when creating a new branch; when switching to an existing\n #\tbranch, the branch pointer is not modified if no '-r' is passed.\ndiff --git a/cg-tag b/cg-tag\nindex 00ce8d4..da4f2d5 100755\n--- a/cg-tag\n+++ b/cg-tag\n@@ -13,12 +13,15 @@\n #\n # OPTIONS\n # -------\n-# -d DESCRIPTION::\n+# -d DESCRIPTION:: Specify tag description\n #\tDescription of the tag.\n-# -k KEYNAME::\n+#\n+# -k KEYNAME:: Use the given KEYNAME to sign the tag\n #\tUse the given key to sign the tag, instead of the default one.\n-# -s::\n+#\n+# -s:: Sign the tag by your private key using GPG.\n #\tSign the tag by your private key using GPG.\n+#\n # OBJECT_ID::\n #\tThis is most usually the ID of the commit to tag. Tagging\n #\tother objects than commits is possible, but rather \"unusual\".\ndiff --git a/cg-update b/cg-update\nindex aaed291..39b1949 100755\n--- a/cg-update\n+++ b/cg-update\n@@ -18,10 +18,10 @@\n #\n # OPTIONS\n # -------\n-# -f::\n+# -f:: Force the complete fetch even if the heads are the same.\n #\tForce the complete fetch even if the heads are the same.\n #\n-# --squash::\n+# --squash:: Use \"squash\" merge to record pending commits as a single merge commit\n #\t\"Squash\" merge - condense all the to-be-merged commits to a single\n #\tmerge commit. This is not to be used lightly; see the cg-merge\n #\tdocumenation for further details.\n\n-- \nJonas Fonseca\n"}]}