{"thread":{"id":"566","subject":"[RFC] Embedding asciidoc manpages in the cg scripts","startedAt":"2005-05-11T01:44:45Z","lastAt":"2005-05-13T18:48:57Z","messageCount":5,"participants":["Jonas Fonseca","Petr Baudis","David Greaves"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"3019","messageId":"20050511014445.GA14377@diku.dk","threadId":"566","inReplyTo":null,"subject":"[RFC] Embedding asciidoc manpages in the cg scripts","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2005-05-11T01:44:45Z","receivedAt":"2005-05-11T01:44:45Z","isPatch":false,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Hi Pasky,\n\nI am still a bit unsure how you want to embed asciidoc in the cg scripts\nso I hope you will comment on this patch probe.\n\nThe Makefile stuff is pretty much ripped off from the recent Makefile by\nDavid Greaves. I don't know if it should also live in\nDocumentation/Makefile.\n\nYou mentioned that you wanted the usage info in the USAGE variable. The\nvariable is initialized so that the usage info can be sed'ed out and\nbecome part of the manpage. I assume the reason for this is to add a\nusage function to cg-Xlib and use it as I have done in cg-add. This\nshould of course be done in a separate patch.\n\nFinally, the embedded asciidoc markup. I still don't understand why you\ndislike the cg-CMD strings in the NAME section. Asciidoc expects them\nthere and it will be so much harder to add them to the output of\n$(cg-help cg-CMD).\n\n---\n\n Makefile  |   28 +++++++++++++++++++++++++\n cg-Xlib   |    7 +++++-\n cg-add    |   28 ++++++++++++++++++++++---\n cg-commit |    4 +--\n cg-log    |   68 ++++++++++++++++++++++++++++++++++++++++++++------------------\n 5 files changed, 110 insertions(+), 25 deletions(-)\n\nIndex: Makefile\n===================================================================\n--- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/Makefile  (mode:100644)\n+++ uncommitted/Makefile  (mode:100644)\n@@ -29,6 +29,7 @@\n \n bindir?=$(prefix)/bin\n libdir?=$(prefix)/lib/cogito\n+mandir?=$(prefix)/man/man1\n \n CC?=gcc\n AR?=ar\n@@ -136,6 +137,8 @@\n \t$(INSTALL) $(PROG) $(SCRIPTS) $(SCRIPT) $(GEN_SCRIPT) $(DESTDIR)$(bindir)\n \t$(INSTALL) -m755 -d $(DESTDIR)$(libdir)\n \t$(INSTALL) $(LIB_SCRIPT) $(DESTDIR)$(libdir)\n+\t$(INSTALL) -m755 -d $(DESTDIR)$(mandir)\n+\t$(INSTALL) $(MANDOC) $(DESTDIR)$(mandir)\n \tcd $(DESTDIR)$(bindir); \\\n \tfor file in $(SCRIPT); do \\\n \t\tsed -e 's/\\$${COGITO_LIB}/\\$${COGITO_LIB:-$(sedlibdir)\\/}/g' $$file > $$file.new; \\\n@@ -157,3 +160,31 @@\n \n backup: clean\n \tcd .. ; tar czvf dircache.tar.gz dir-cache\n+\n+\n+DOCSRC\t= cg-log cg-add\n+HTMLDIR\t= Documentation/html\n+MANDIR\t= Documentation/man/man1\n+HTMLDOC\t= $(patsubst %,$(HTMLDIR)/%.html,$(DOCSRC))\n+MANDOC\t= $(patsubst %,$(MANDIR)/%.1,$(DOCSRC))\n+\n+doc-clean:\n+\t$(RM) $(HTMLDOC) $(MANDOC)\n+\n+html: $(HTMLDOC)\n+man: $(MANDOC)\n+\n+$(HTMLDIR):\n+\t$(INSTALL) -m755 -d $@\n+\n+$(MANDIR)/%.1: %.xml\n+\txmlto man $< -o $(@D)\n+\n+%.xml: %.txt\n+\tasciidoc -b docbook -d manpage -o $@ $<\n+\n+$(HTMLDIR)/%.html: %.txt $(HTMLDIR)\n+\tasciidoc -b css-embedded -d manpage -o $@ $<\n+\n+%.txt: %\n+\tcg-help $< > $@\nIndex: cg-Xlib\n===================================================================\n--- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/cg-Xlib  (mode:100755)\n+++ uncommitted/cg-Xlib  (mode:100755)\n@@ -17,6 +17,11 @@\n \texit 1\n }\n \n+usage () {\n+\techo \"usage: $USAGE\" >&2\n+\texit 1\n+}\n+\n \n mktemp () {\n \tif [ ! \"$BROKEN_MKTEMP\" ]; then\n@@ -52,7 +57,7 @@\n \n print_help () {\n \twhich \"cg-$1\" >/dev/null 2>&1 || exit 1\n-\tcat $(which cg-$1) | sed -n '3,/^$/s/^# *//p'\n+\tcat $(which cg-$1) | sed 's/^USAGE=\"\\(.*\\)\"/# \\1/' | sed -n '3,/^$/s/^# *//p'\n \texit\n }\n \nIndex: cg-add\n===================================================================\n--- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/cg-add  (mode:100755)\n+++ uncommitted/cg-add  (mode:100755)\n@@ -1,14 +1,36 @@\n #!/usr/bin/env bash\n #\n-# Add new file to a GIT repository.\n-# Copyright (c) Petr Baudis, 2005\n+# CG-ADD(1)\n+# =========\n #\n+# NAME\n+# ----\n+# cg-add - add files to a GIT repository\n+#\n+# SYNOPSIS\n+# --------\n+USAGE=\"cg-add FILE...\"\n+#\n+# DESCRIPTION\n+# -----------\n # Takes a list of file names at the command line, and schedules them\n # for addition to the GIT repository at the next commit.\n+#\n+# The command will fail if one of the given files does not exist.\n+#\n+# cg-add is part of Cogito, an SCM-like toolkit for managing GIT trees.\n+#\n+# OPTIONS\n+# -------\n+# No options.\n+#\n+# COPYING\n+# -------\n+# Copyright (c) Petr Baudis, 2005.\n \n . ${COGITO_LIB}cg-Xlib\n \n-[ \"$1\" ] || die \"usage: cg-add FILE...\"\n+[ \"$1\" ] || usage\n \n for file in \"$@\"; do\n \tif [ -f \"$file\" ]; then\nIndex: cg-log\n===================================================================\n--- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/cg-log  (mode:100755)\n+++ uncommitted/cg-log  (mode:100755)\n@@ -1,26 +1,56 @@\n #!/usr/bin/env bash\n #\n-# Make a log of changes in a GIT branch.\n-# Copyright (c) Petr Baudis, 2005.\n-# Copyright (c) David Woodhouse, 2005.\n-#\n-# Takes a -c option to add color to the output.\n-# Currently, the colors are:\n+# CG-LOG(1)\n+# =========\n #\n-#\theader\t\tGreen\t\n-#\tauthor \t\tCyan\n-#\tcommitter\tMagenta\n-#\tfiles\t\tBlue\n-#\tsignoff\t\tYellow\n-#\n-# Takes an -f option to list which files was changed.\n-#\n-# Takes an -r followed with id resolving to a commit to start from\n-# (HEAD by default), or id1:id2 representing an (id1;id2] range\n-# of commits to show.\n+# NAME\n+# ----\n+# cg-log - show log information for files or a range of commits\n+#\n+# SYNOPSIS\n+# --------\n+USAGE=\"cg-log [ -c ] [ -f ] [ --help | -h ] [-r FROM_ID[:TO_ID]]... [FILE]...\"\n+#\n+# DESCRIPTION\n+# -----------\n+# Display log information for files or a range of commits. The output\n+# will automatically be displayed in pager unless it is piped.\n+#\n+# cg-log is part of Cogito, an SCM-like toolkit for managing GIT trees.\n+#\n+# OPTIONS\n+# -------\n+# Arguments not interpreted as options will be interpreted as filenames;\n+# cg-log then displays only changes in those files.\n+#\n+# --help, -h::\n+#\tPrint this documentation\n+#\n+# -c::\n+#\tAdd color to the output. Currently, the colors are:\n+#\n+#\t\theader\t\tGreen\n+#\t\tauthor\t\tCyan\n+#\t\tcommitter\tMagenta\n+#\t\tfiles\t\tBlue\n+#\t\tsignoff\t\tYellow\n+#\n+# -f::\n+#\tList which files were changed.\n+#\n+# -r FROM_ID[:TO_ID]::\n+#\tLimit the log information to a range of commits. The range of\n+#\tincluded commits can be specified either as -r FROM_ID[:TO_ID]\n+#\tor as -r FROM_ID -r TO_ID. In both situations the -r option\n+#\texpects ID arguments which resolve to commits. For ranges, the\n+#\tlog for both the specified IDs will be included. If TO_ID is\n+#\tleft out all commits older than FROM_ID will not be shown. If no\n+#\t-r option is given commits starting from HEAD will be shown.\n #\n-# The rest of arguments are took as filenames; cg-log then displays\n-# only changes in those files.\n+# COPYING\n+# -------\n+# Copyright (c) Petr Baudis, 2005.\n+# Copyright (c) David Woodhouse, 2005.\n \n . ${COGITO_LIB}cg-Xlib\n # Try to fix the annoying \"Broken pipe\" output. May not help, but apparently\n-- \nJonas Fonseca\n"},{"id":"3064","messageId":"20050511213217.GG22686@pasky.ji.cz","threadId":"566","inReplyTo":"20050511014445.GA14377@diku.dk","subject":"Re: [RFC] Embedding asciidoc manpages in the cg scripts","fromName":"Petr Baudis","fromEmail":"pasky@ucw.cz","sentAt":"2005-05-11T21:32:17Z","receivedAt":"2005-05-11T21:32:17Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"Dear diary, on Wed, May 11, 2005 at 03:44:45AM CEST, I got a letter\nwhere Jonas Fonseca <fonseca@diku.dk> told me that...\n> Index: cg-add\n> ===================================================================\n> --- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/cg-add  (mode:100755)\n> +++ uncommitted/cg-add  (mode:100755)\n> @@ -1,14 +1,36 @@\n>  #!/usr/bin/env bash\n>  #\n> -# Add new file to a GIT repository.\n> -# Copyright (c) Petr Baudis, 2005\n> +# CG-ADD(1)\n> +# =========\n\nThis is really awful - it carries no interesting information whatsoever\nsince that is pretty obvious from the fact that it is in file called\ncg-add.\n\n>  #\n> +# NAME\n> +# ----\n> +# cg-add - add files to a GIT repository\n\nHalf of this is useless, too.\n\nI think you should just keep the first paragraph of the files as it is\nnow. Don't touch it, just parse it.\n\n> +#\n> +# SYNOPSIS\n> +# --------\n\nNo need for this heading either.\n\n> +USAGE=\"cg-add FILE...\"\n> +#\n> +# DESCRIPTION\n> +# -----------\n>  # Takes a list of file names at the command line, and schedules them\n>  # for addition to the GIT repository at the next commit.\n> +#\n> +# The command will fail if one of the given files does not exist.\n> +#\n> +# cg-add is part of Cogito, an SCM-like toolkit for managing GIT trees.\n\nUseless.\n\n> +#\n> +# OPTIONS\n> +# -------\n> +# No options.\n\nThe rest of DESCRIPTION and OPTIONS looks fine.\n\nI'd just expect you to be much less intrusive in the in-file comments\nand do more work when processing the stuff. I'm commenting on how it\nlooks inside of the sources - do whatever is necessary when processing\nit to generate a proper-looking manpage from it.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nC++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor\n"},{"id":"3072","messageId":"4282851A.2010305@dgreaves.com","threadId":"566","inReplyTo":"20050511213217.GG22686@pasky.ji.cz","subject":"Re: [RFC] Embedding asciidoc manpages in the cg scripts","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-05-11T22:20:10Z","receivedAt":"2005-05-11T22:20:10Z","isPatch":false,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Petr Baudis wrote:\n\n>> #\n>>+# NAME\n>>+# ----\n>>+# cg-add - add files to a GIT repository\n>>    \n>>\n>\n>Half of this is useless, too.\n>\n>I think you should just keep the first paragraph of the files as it is\n>now. Don't touch it, just parse it.\n>  \n>\nA bit harsh Petr.\n\nIsn't the idea of using an already written tool that you don't _have_ to\nparse it?\nWhere, consistently, do the cg-files have a 1 line summary.\n\n>>+#\n>>+# SYNOPSIS\n>>+# --------\n>>    \n>>\n>No need for this heading either.\n>  \n>\nActually there is :)\nasciidoc won't produce a manpage without it.\n\n>>+USAGE=\"cg-add FILE...\"\n>>+#\n>>+# DESCRIPTION\n>>+# -----------\n>> # Takes a list of file names at the command line, and schedules them\n>> # for addition to the GIT repository at the next commit.\n>>+#\n>>+# The command will fail if one of the given files does not exist.\n>>+#\n>>+# cg-add is part of Cogito, an SCM-like toolkit for managing GIT trees.\n>>    \n>>\n>\n>Useless.\n>  \n>\nYes - if you happen to have written and breathed the code - not so\nuseless if you're a normal user.\n\nIt cogito is ever installed as part of a distro (maybe even by default)\nthen it would be nice if \"man cg-add\" actually mentioned it was part of\ncogito and git...\n\n>>+#\n>>+# OPTIONS\n>>+# -------\n>>+# No options.\n>>    \n>>\n>\n>The rest of DESCRIPTION and OPTIONS looks fine.\n>\n>I'd just expect you to be much less intrusive in the in-file comments\n>and do more work when processing the stuff. I'm commenting on how it\n>looks inside of the sources - do whatever is necessary when processing\n>it to generate a proper-looking manpage from it.\n>  \n>\nHaving worked hard on being consistent throughout the git docs I'd say\nthat a little excess verbiage in the comments is a worthwhile price. I\ndon't think you can worry about performance or anything - these _are_\nshell scripts!\n\n\nMaybe you'd be happier if they were moved to the bottom of the file and\npreceded with:\n\n#asciidoc follows\n\nOr if you don't like that then maybe keep them external.\n\nDavid\n\n-- \n\n"},{"id":"3077","messageId":"20050511224806.GJ22686@pasky.ji.cz","threadId":"566","inReplyTo":"4282851A.2010305@dgreaves.com","subject":"Re: [RFC] Embedding asciidoc manpages in the cg scripts","fromName":"Petr Baudis","fromEmail":"pasky@ucw.cz","sentAt":"2005-05-11T22:48:06Z","receivedAt":"2005-05-11T22:48:06Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"Dear diary, on Thu, May 12, 2005 at 12:20:10AM CEST, I got a letter\nwhere David Greaves <david@dgreaves.com> told me that...\n> Petr Baudis wrote:\n> \n> >> #\n> >>+# NAME\n> >>+# ----\n> >>+# cg-add - add files to a GIT repository\n> >>    \n> >>\n> >\n> >Half of this is useless, too.\n> >\n> >I think you should just keep the first paragraph of the files as it is\n> >now. Don't touch it, just parse it.\n> >  \n> >\n> A bit harsh Petr.\n\nSorry, I didn't mean to sound (too) harsh. ;-)\n\n> Isn't the idea of using an already written tool that you don't _have_ to\n> parse it?\n\nNo, the idea is to get nice output while keeping the input easily human\nreadable. I'm only stretching that further, since we know more than\nasciidoc itself does about the file. :-)\n\n> Where, consistently, do the cg-files have a 1 line summary.\n\nI can't parse this sentence, I fear. All the cg-files have a 1 line\nsummary, then one or more copyright lines, then the description 'n\nstuff. That's fixed format, much like the git commit format.\n\n> >>+#\n> >>+# SYNOPSIS\n> >>+# --------\n> >>    \n> >>\n> >No need for this heading either.\n> >  \n> >\n> Actually there is :)\n> asciidoc won't produce a manpage without it.\n\nSo the script piping this to asciidoc can add this at the proper point.\n\n> >>+USAGE=\"cg-add FILE...\"\n> >>+#\n> >>+# DESCRIPTION\n> >>+# -----------\n> >> # Takes a list of file names at the command line, and schedules them\n> >> # for addition to the GIT repository at the next commit.\n> >>+#\n> >>+# The command will fail if one of the given files does not exist.\n> >>+#\n> >>+# cg-add is part of Cogito, an SCM-like toolkit for managing GIT trees.\n> >>    \n> >>\n> >\n> >Useless.\n> >  \n> >\n> Yes - if you happen to have written and breathed the code - not so\n> useless if you're a normal user.\n\nSorry, I've meant only the \"cg-add is part of Cogito, an SCM-like\ntoolkit for managing GIT trees\" part is useless.\n\n> It cogito is ever installed as part of a distro (maybe even by default)\n> then it would be nice if \"man cg-add\" actually mentioned it was part of\n> cogito and git...\n\nYes. I'm fine with it being in the manpage. I just don't want it in the\ncode since again, it is obvious there. And code (be it program code or\ndocumentation code) duplication is wrong, if you have a non-trivial\nchunk repeated over and over everywhere, you probably want to move it to\na single place. That'd be the conversion script here.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nC++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor\n"},{"id":"3249","messageId":"20050513184857.GB26263@diku.dk","threadId":"566","inReplyTo":"20050511224806.GJ22686@pasky.ji.cz","subject":"Re: [RFC] Embedding asciidoc manpages in the cg scripts","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2005-05-13T18:48:57Z","receivedAt":"2005-05-13T18:48:57Z","isPatch":false,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Petr Baudis <pasky@ucw.cz> wrote Thu, May 12, 2005:\n> Dear diary, on Thu, May 12, 2005 at 12:20:10AM CEST, I got a letter\n> where David Greaves <david@dgreaves.com> told me that...\n> > Petr Baudis wrote:\n> > \n> > >>+# NAME\n> > >>+# ----\n> > >>+# cg-add - add files to a GIT repository\n> > >\n> > >Half of this is useless, too.\n> > >\n> > >I think you should just keep the first paragraph of the files as it is\n> > >now. Don't touch it, just parse it.\n> > >  \n> > A bit harsh Petr.\n> \n> Sorry, I didn't mean to sound (too) harsh. ;-)\n\nDon't mind that you are harsh if it makes sense and I must agree that\nhaving a helper script really paid off reducing the added markup to\nalmost a half (in my initial patches). Plus, it is now easy to enhance\nthe manpages with links to referenced commands without having stuff like\n'link:' markup in the script headers.\n\nI ended up actually adding two scripts. One for lifting cg-* manpages\nand one for generating a cogito manpage with an overview of commands and\ninformation about command identifiers.\n\nThe generated manpages can be previewed at:\n\n\thttp://www.nitro.dk/~jonas/cogito/manpages/cogito.html\n\n-- \nJonas Fonseca\n\n\n[PATCH] Cogito manpages\n\nAdd asciidoc markup to Cogito script headers. Add a script to generate\nasciidoc manpages from the cg-* command headers and a script for\ngenerating a cogito(1) manpage. Finally, add build rules for making\nCogito manpages.\n\nNotes:\n\n* USAGE variables are added which can later be used by cg-help or die().\n\n* The command identifiers are name wrapped in '<'/'>' like in the GIT\n  manpages and are not similar to those in cg-help.\n\n* The top-level Makefile is changed to add a script header to cg-version\n  so it could also have a man pages. Don't know if that belongs there or\n  in Documentation/cg-version.txt. Anyway, in order to minimize the\n  patch I cleaned up the checking of .git/HEAD.\n\n* I had trouble getting asciidoc to accept the line\n\n\tgit+ssh://[user@]host/path\n\n  I couldn't figure out how to escape it so I changed it to\n\n\tgit+ssh://host/path or git+ssh://user@host/path\n\n  Finally the example with referencing branches via #fragments I shortened\n  the rsync URL so the line breaking '\\' was not needed.\n\n* The description of -r options should be carefully reviewed. I changed\n  them to be more alike across cg-{diff,log,mkpatch} and some of the\n  original ones looked wrong.\n\nSigned-off-by: Jonas Fonseca <fonseca@diku.dk>\n\n---\n Documentation/Makefile            |   11 ++\n Documentation/make-cg-manpage     |   65 ++++++++++++++++\n Documentation/make-cogito-manpage |  149 ++++++++++++++++++++++++++++++++++++++\n Makefile                          |   33 +++++---\n cg-add                            |   18 ++++\n cg-admin-lsobj                    |   35 +++++++-\n cg-admin-uncommit                 |   28 ++++---\n cg-branch-add                     |   44 ++++++-----\n cg-branch-ls                      |   19 ++++\n cg-cancel                         |   19 +++-\n cg-clone                          |   17 +++-\n cg-commit                         |   95 +++++++++++++++++++-----\n cg-diff                           |   29 +++++--\n cg-export                         |   15 +++\n cg-help                           |   17 ++++\n cg-init                           |   15 +++\n cg-log                            |   71 +++++++++++++-----\n cg-ls                             |   35 ++++++++\n cg-merge                          |   25 ++++--\n cg-mkpatch                        |   39 ++++++++-\n cg-patch                          |   11 ++\n cg-pull                           |   15 +++\n cg-restore                        |   24 ++++--\n cg-rm                             |   11 ++\n cg-seek                           |   26 ++++--\n cg-status                         |   30 +++++++\n cg-tag                            |   15 +++\n cg-tag-ls                         |    9 ++\n cg-update                         |   16 +++-\n 29 files changed, 785 insertions(+), 151 deletions(-)\n\nIndex: Documentation/Makefile\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/Documentation/Makefile  (mode:100644)\n+++ uncommitted/Documentation/Makefile  (mode:100644)\n@@ -1,4 +1,7 @@\n-DOC_SRC=$(wildcard git*.txt)\n+CG_IGNORE=$(wildcard ../cg-X*)\n+CG_SRC=$(filter-out $(CG_IGNORE), $(wildcard ../cg-*))\n+CG_TXT=cogito.txt $(patsubst ../cg-%,cg-%.txt,$(CG_SRC))\n+DOC_SRC=$(wildcard git*.txt) $(CG_TXT)\n DOC_HTML=$(patsubst %.txt,%.html,$(DOC_SRC))\n DOC_MAN=$(patsubst %.txt,%.1,$(DOC_SRC))\n \n@@ -22,3 +25,9 @@\n \n %.xml : %.txt\n \tasciidoc -b docbook -d manpage $<\n+\n+cogito.txt : make-cogito-manpage\n+\t./make-cogito-manpage > $@\n+\n+cg-%.txt : ../cg-% make-cg-manpage\n+\t./make-cg-manpage $< > $@\nIndex: Documentation/make-cg-manpage\n===================================================================\n--- /dev/null  (tree:de641904363cd3759f132ee7c0dfaf8a2ee58388)\n+++ uncommitted/Documentation/make-cg-manpage  (mode:100755)\n@@ -0,0 +1,65 @@\n+#!/usr/bin/env bash\n+#\n+# Generate asciidoc manpage markup from Cogito script header.\n+# Copyright (c) Jonas Fonseca, 2005\n+#\n+# Takes a path to a Cogito script. Prints the manpage to stdout.\n+\n+. ${COGITO_LIB}cg-Xlib\n+\n+command=$1\n+\n+[ -e \"$command\" ] || die \"$command does not exist\"\n+\n+COMMAND=$(basename $command)\n+\n+# FIXME: Show the SHA1 of the command below the TITLELINE.\n+\n+# Generate the 'CG-COMMAND(1)' title from cg-command\n+TITLE=\"$COMMAND(1)\"\n+# Asciidocs wants the title line ('====') to be as wide as the title.\n+TITLELINE=$(echo \"$TITLE\" | sed 's/[0-9a-zA-Z-()]/=/g')\n+\n+# Get `USAGE=\"cg-command args...\"` line and make it `cg-command args...`\n+SYNOPSIS=$(grep 'USAGE=' $command | sed 's/^USAGE=\"\\(.*\\)\"/\\1/')\n+\n+# Extract the script header.\n+HEADER=$(cat $command | sed -n '3,/^$/s/^# *//p')\n+\n+# Some scripts have copyright lines followed by 'Based on script by ...' lines.\n+# Include them so they are also put in the COPYRIGHT section.\n+COPYRIGHT=$(cat $command | sed -n '3,/^$/s/^# *//p' \\\n+\t\t\t | sed -n '/^Copyright (c)/,/^$/p' \\\n+\t\t\t | sed 's/(c)/(C)/')\n+\n+# First line of the header contains the caption. Normalize it by lowercasing the\n+# start and stripping any punctuation.\n+CAPTION=$(echo \"$HEADER\" | head -n 1 | tr '[A-Z]' '[a-z]' | sed 's/\\.$//')\n+\n+# Get remaining sections and carefully insert links to cogito commands when they\n+# were referenced as \"`cg-command`\". Note, we can't just do it for any cg-*\n+# combo because code listings will ignore any asciidoc markup....\"\n+BODY=$(echo \"$HEADER\" | sed -n '/^DESCRIPTION$/,$p' \\\n+\t\t      | sed 's/`\\(cg-[a-z-]\\+\\)`/link:\\1.html[`\\1(1)`]/')\n+\n+echo \"$TITLE\"\n+echo \"$TITLELINE\"\n+echo\n+echo \"NAME\"\n+echo \"----\"\n+echo \"$COMMAND - $CAPTION\"\n+echo\n+echo \"SYNOPSIS\"\n+echo \"--------\"\n+echo \"$SYNOPSIS\"\n+echo\n+echo \"$BODY\"\n+echo\n+echo \"COPYRIGHT\"\n+echo \"---------\"\n+echo \"$COPYRIGHT\"\n+echo\n+echo \"SEE ALSO\"\n+echo \"--------\"\n+echo \"$COMMAND command is part of link:cogito.html[cogito(1)],\"\n+echo \"a toolkit for managing link:git.html[git(1)] trees.\"\nIndex: Documentation/make-cogito-manpage\n===================================================================\n--- /dev/null  (tree:de641904363cd3759f132ee7c0dfaf8a2ee58388)\n+++ uncommitted/Documentation/make-cogito-manpage  (mode:100755)\n@@ -0,0 +1,149 @@\n+#!/usr/bin/env bash\n+#\n+# Generate a quick reference asciidoc manpage for the Cogito.\n+# Copyright (c) Jonas Fonseca, 2005\n+\n+# Shorthand for the link markup.\n+link()\n+{\n+\tcommand=\"$1\"\n+\techo \"link:$command.html[\\`$command(1)\\`]\"\n+}\n+\n+# Print description list entry.\n+print_command_info()\n+{\n+\tcommand=\"$1\"\n+\tcaption=$(cat \"$command\" | head -n 3 | tail -n 1 | sed 's/# //')\n+\tusage=$(grep 'USAGE=' \"$command\" | sed 's/^USAGE=\"\\(.*\\)\"/\\1/')\n+\tcmdname=$(basename $command)\n+\n+\techo\n+\tcase \"$cmdname\" in\n+\tcg-*)\n+\t\tlink \"$cmdname\"\n+\t\t;;\n+\t*-id)\n+\t\techo \"$cmdname::\"\n+\t\t;;\n+\tesac\n+\techo \"\t$caption\"\n+\techo\n+\techo \"\t$usage\"\n+}\n+\n+cat <<__END__\n+cogito(1)\n+=========\n+\n+NAME\n+----\n+cogito - SCM-like GIT layer\n+\n+SYNOPSIS\n+--------\n+cg-<command> <arg>...\n+\n+DESCRIPTION\n+-----------\n+\n+Cogito is a revision control system for tracking changes to content in a\n+highly distributed development environment. Amongst some of the noteworthy\n+features, Cogito has support for branching, tagging and multiple backends for\n+distributing repositories (local files, rsync, HTTP, ssh).\n+\n+Cogito is implemented as a series of \\`bash(1)\\` scripts on top of $(link git)\n+(a stupid content tracker) with the goal of providing an interface for working\n+with the GIT database in a manner similar to other SCM tools (like CVS,\n+BitKeeper or Monotone).\n+\n+Commands Overview\n+-----------------\n+\n+The Cogito commands can be split into regular commands and advanced commands.\n+The regular commands are those used for normal interacting with the\n+repository, while the advanced commands can be used for administrating the\n+repository and should to some degree be regarded as low-level and in some\n+cases dangerous.\n+\n+Below an overview of the available commands are listed. For details on\n+individual commands, do e.g. \\`cg-help cg-log\\` or \\`cg-log --help\\`.\n+\n+Regular commands\n+~~~~~~~~~~~~~~~~\n+__END__\n+\n+for command in $(ls ../cg-* | grep -v cg-admin- | grep -v cg-X); do\n+\tprint_command_info \"$command\"\n+done\n+\n+cat <<__END__\n+\n+Advanced commands\n+~~~~~~~~~~~~~~~~~\n+__END__\n+\n+for command in $(ls ../cg-admin-*); do\n+\tprint_command_info \"$command\"\n+done\n+\n+cat <<__END__\n+\n+Helper commands\n+~~~~~~~~~~~~~~~\n+\n+Cogito also provides various helper commands for resolving IDs for symbolic\n+names etc. The commands are:\n+__END__\n+\n+for command in $(ls ../*-id | grep -v git-); do\n+\tprint_command_info \"$command\"\n+done\n+\n+cat <<__END__\n+\n+Command Identifiers\n+-------------------\n+<branch>::\n+\tIndicates a branch name added with the $(link cg-branch-add) name.\n+\n+<command>::\n+\tIndicates a Cogito command. The \\`cg-\\` prefix is optional.\n+\n+<location>::\n+\tIndicates a local file path or a URI. See $(link cg-branch-add) for a\n+\tlist of supported URI schemes.\n+\n+<revision>::\n+\tIndicates an ID resolving to a commit. The following expressions can\n+\tbe used interchangably as IDs:\n+\t- empty string, 'this' or 'HEAD' (current HEAD)\n+\t- branch name (as registered with $(link cg-branch-add))\n+\t- tag name (as registered with $(link cg-tag))\n+\t- shortcut object hash (shorted unambiguous hash lead)\n+\t- commit object hash (as returned by \\`commit-id\\`)\n+\t- tree object hash (as returned by \\`tree-id\\`)\n+\n+<tag>::\n+\tIndicates a free form tag name.\n+\n+<type>::\n+\tIndicates a git object type i.e.: \\`blob\\`, \\`commit\\`, \\`tree\\` or\n+\t\\`tag\\`.\n+\n+<username>::\n+\tIndicates a free form user name.\n+\n+<file>::\n+\tIndicates a filename - always relative to the root of the repository.\n+\n+AUTHORS\n+-------\n+Cogito was written by Petr Baudis <pasky@ucw.cz>.\n+This manpage was written by Jonas Fonseca <fonseca@diku.dk>.\n+\n+COPYRIGHT\n+---------\n+Copyright (C) Petr Baudis, 2005.\n+Copyright (C) Jonas Fonseca, 2005.\n+__END__\nIndex: Makefile\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/Makefile  (mode:100644)\n+++ uncommitted/Makefile  (mode:100644)\n@@ -114,20 +114,33 @@\n \n \n ifneq (,$(wildcard .git))\n-cg-version: $(VERSION) .git/HEAD\n-\t@echo Generating cg-version...\n-\t@rm -f $@\n-\t@echo \"#!/bin/sh\" > $@\n-\t@echo \"echo \\\"$(shell cat $(VERSION)) ($(shell cat .git/HEAD))\\\"\" >> $@\n-\t@chmod +x $@\n-else\n-cg-version: $(VERSION)\n+GIT_HEAD=.git/HEAD\n+GIT_HEAD_ID=\" $(shell cat $(GIT_HEAD))\"\n+endif\n+cg-version: $(VERSION) $(GITHEAD) Makefile\n \t@echo Generating cg-version...\n \t@rm -f $@\n \t@echo \"#!/bin/sh\" > $@\n-\t@echo \"echo \\\"$(shell cat $(VERSION))\\\"\" >> $@\n+\t@echo \"#\" >> $@\n+\t@echo \"# Show the version of the Cogito toolkit.\" >> $@\n+\t@echo \"# Copyright (c) Petr Baudis, 2005\" >> $@\n+\t@echo \"#\" >> $@\n+\t@echo \"# DESCRIPTION\" >> $@\n+\t@echo \"# -----------\" >> $@\n+\t@echo \"# Show which version of Cogito is installed.\" >> $@\n+\t@echo \"# Additionally, the 'HEAD' of the installed Cogito\" >> $@\n+\t@echo \"# is also shown if this information was available\" >> $@\n+\t@echo \"# at the build time.\" >> $@\n+\t@echo \"#\" >> $@\n+\t@echo \"# OPTIONS\" >> $@\n+\t@echo \"# -------\" >> $@\n+\t@echo \"# -h, --help::\" >> $@\n+\t@echo \"#\tPrint usage help.\" >> $@\n+\t@echo >> $@\n+\t@echo \"USAGE=\\\"cg-version\\\"\" >> $@\n+\t@echo >> $@\n+\t@echo \"echo \\\"$(shell cat $(VERSION))$(GIT_HEAD_ID)\\\"\" >> $@\n \t@chmod +x $@\n-endif\n \n git.spec: git.spec.in $(VERSION)\n \tsed -e 's/@@VERSION@@/$(shell cat $(VERSION) | cut -d\"-\" -f2)/g' < $< > $@\nIndex: cg-add\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-add  (mode:100755)\n+++ uncommitted/cg-add  (mode:100755)\n@@ -1,10 +1,26 @@\n #!/usr/bin/env bash\n #\n-# Add new file to a GIT repository.\n+# Add files to the GIT repository.\n # Copyright (c) Petr Baudis, 2005\n #\n+# DESCRIPTION\n+# -----------\n # Takes a list of file names at the command line, and schedules them\n # for addition to the GIT repository at the next commit.\n+#\n+# The command will fail if one of the given files does not exist.\n+#\n+# Note that cogito manage content. Which means it doesn't make sense\n+# to `cg-add` stand-alone directories since directories have no content.\n+# Instead add a file within the new directory and `cg-add` will create\n+# a tree for managing the directory as needed.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-add <file>...\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-admin-lsobj\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-admin-lsobj  (mode:100755)\n+++ uncommitted/cg-admin-lsobj  (mode:100755)\n@@ -4,17 +4,44 @@\n # Copyright (c) Randy Dunlap, 2005\n # Copyright (c) Petr Baudis, 2005\n #\n-# Lists IDs of all the objects of a given type (blob, tree, commit) found\n-# in the dircache.\n+# DESCRIPTION\n+# -----------\n+# Lists IDs of all the objects of a given type found in the dircache.\n+# Takes the object type as the first parameter, defaults to all objects.\n+#\n+# The possible object types are:\n+# `blob`::\n+#\tThis object is a pure storage object containing some user data.\n+#\n+# `commit`::\n+#\tThis object ties directory hierarchies together into a DAG\n+#\tof revisions.\n+#\n+# `tree`::\n+#\tThis object is an object that ties one or more `blob` objects\n+#\tinto a directory structure.\n+#\n+# `tag`::\n+#\tThis object ties a symbolic release tag to an object in the\n+#\tdatabase.\n #\n-# Example usage:\n+# See the git README for more information about the object types.\n+#\n+# EXAMPLE USAGE\n+# -------------\n # Oh, I was messing with my HEADs and lost few commits, where on the earth\n # could they be...?\n+#\n #\tfor i in `cg-admin-lsobj commit | cut -f 1`; do\n #\t\techo -e \"\\n==================\\nme $i\"; cat-file commit $i;\n #\tdone\n #\n-# Takes the object type as the first parameter, defaults to all objects.\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-admin-lsobj [<type>]\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-admin-uncommit\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-admin-uncommit  (mode:100755)\n+++ uncommitted/cg-admin-uncommit  (mode:100755)\n@@ -1,18 +1,28 @@\n #!/usr/bin/env bash\n #\n-# Undo a commit or a series of commits\n+# Undo a commit or a series of commits.\n # Copyright (c) Matt Porter, 2005\n # Copyright (c) Petr Baudis, 2005\n #\n-# Optional -t parameter makes cg-admin-uncommit to roll back the tree\n-# as well to the previous commit. Without this option (by default)\n-# Cogito keeps the tree in its current state, therefore generating\n-# tree with local changes against the target commit, consisting of the\n-# changes in the rolled back commits.\n+# DESCRIPTION\n+# -----------\n+# Takes a commit ID which is the earliest commit to be removed from\n+# the repository. If no parameter is passed, it uncommits the latest\n+# commit ('HEAD').\n #\n-# Takes a commit ID which is the earliest commit to be\n-# removed from the repository. If no parameter is passed,\n-# it uncommits the latest commit (HEAD).\n+# OPTIONS\n+# -------\n+# -t::\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,\n+#\ttherefore generating tree with local changes against the target\n+#\tcommit, consisting of the changes in the rolled back commits.\n+#\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-admin-uncommit [-t] [<commit>]\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-branch-add\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-branch-add  (mode:100755)\n+++ uncommitted/cg-branch-add  (mode:100755)\n@@ -3,35 +3,41 @@\n # Add new branch to the GIT repository.\n # Copyright (c) Petr Baudis, 2005\n #\n-# After you add a branch, you can cg-pull it whenever you want\n-# and it will keep your objects database in sync with it. Its latest\n-# commit is accessible as .git/refs/heads/branchname (or - more conveniently\n-# - as $(commit-id branchname)). For example, to make a diff between\n-# Linus (after you added him) and your current tree, do\n-#\n-#\tcg-pull linus\n-#\tcg-diff linus\n+# DESCRIPTION\n+# -----------\n+# Takes the branch name and source location as parameters.\n+# After you add a branch, you can `cg-pull` it whenever you want and\n+# it will keep your objects database in sync with it. Its latest\n+# commit is accessible as `.git/refs/heads/branchname` (or - more\n+# conveniently - as `$(commit-id branchname)`). For example, to make a\n+# diff between Linus (after you added him) and your current tree, do:\n #\n+#\t$ cg-pull linus\n+#\t$ cg-diff linus\n #\n # The possible location specifiers are:\n #\n-# (1) Local path - note that pulling will hardlink the objects, not copy them.\n-# (2) rsync - either rsync://host/path or host:/path (the latter can change)\n-# (3) HTTP - http://host/path\n-# (4) SSH - git+ssh://[user@]host/absolute/path\n+# 1. Local path - note that pulling will hardlink the objects, not copy them.\n+# 2. rsync - either `rsync://host/path` or `host:/path` (the latter can change)\n+# 3. HTTP - `http://host/path`\n+# 4. SSH - `git+ssh://host/path` or `git+ssh://user@host/path` - note that\n+#    the path must be absolute.\n #\n # The URL can have a fragment part, which identifies a branch inside of\n # the repository. Therefore, if you have a repository\n-# rsync://kernel.org/pub/scm/linux/kernel/mj/linux.git and you are interested\n-# in its 'testing' branch, you can e.g.\n-#\n-#\tcg-branch-add mj-testing \\\n-#\t\trsync://kernel.org/pub/scm/linux/kernel/mj/linux.git#testing\n+# `rsync://host/path/repo.git` and you are interested in its 'testing'\n+# branch, you can e.g.:\n #\n-# and refer to it as 'mj-testing' anytime later.\n+#\t$ cg-branch-add repo-testing rsync://host/path/repo.git#testing\n #\n+# and refer to it as 'repo-testing' anytime later.\n #\n-# Takes the branch' name and location as parameters.\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-admin-uncommit <branch> <location>\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-branch-ls\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-branch-ls  (mode:100755)\n+++ uncommitted/cg-branch-ls  (mode:100755)\n@@ -3,7 +3,24 @@\n # List configured GIT branches.\n # Copyright (c) Steven Cole 2005\n #\n-# Takes no parameters.\n+# DESCRIPTION\n+# -----------\n+# Print a listing of all known branches.\n+#\n+# The output has the following format:\n+#\n+#\t<branch> <location>\n+# \n+# For example\n+#\n+#\torigin  rsync://rsync.kernel.org/pub/scm/cogito/cogito.git\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-branch-ls\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-cancel\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-cancel  (mode:100755)\n+++ uncommitted/cg-cancel  (mode:100755)\n@@ -3,16 +3,23 @@\n # Cancels current edits in the working tree.\n # Copyright (c) Petr Baudis, 2005\n #\n-# This script reverts the working tree to a consistent state before\n-# any changes to it (including merges etc) were done.\n+# DESCRIPTION\n+# -----------\n+# Reverts the working tree to a consistent state before any changes to it\n+# (including merges etc.) were done.\n #\n-# Basically, this is the opposite of cg-commit in some sense.\n+# Basically, this is the opposite of `cg-commit` in some sense.\n #\n-# Takes no arguments and the evil changes from the tree.\n-#\n-# This command is complementary to cg-restore, which only brings\n+# This command is complementary to `cg-restore`, which only brings\n # individual files in sync with their state at the time of the\n # last commit.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help\n+\n+USAGE=\"cg-cancel\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-clone\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-clone  (mode:100755)\n+++ uncommitted/cg-clone  (mode:100755)\n@@ -3,16 +3,25 @@\n # Clone a remote GIT repository.\n # Copyright (c) Petr Baudis, 2005\n #\n+# DESCRIPTION\n+# -----------\n # This is like cg-init, but it will create a new directory where it will do\n # the checkout.\n #\n-# If you pass it an optional -s parameter, it does the clone in the current\n-# directory instead of creating a new one.\n-#\n # Takes a parameter specifying the location of the source repository and an\n-# optional second parameter specifying the destination.  If the second\n+# optional second parameter specifying the destination. If the second\n # parameter is omitted, the basename of the source repository is used as the\n # destination.\n+#\n+# OPTIONS\n+# -------\n+# -s::\n+#\tClone in the current directory instead of creating a new one.\n+#\n+# -h, --help::\n+#\tPrint usage help\n+\n+USAGE=\"cg-clone [-s] <location> [<directory>]\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-commit\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-commit  (mode:100755)\n+++ uncommitted/cg-commit  (mode:100755)\n@@ -4,26 +4,81 @@\n # Copyright (c) Petr Baudis, 2005\n # Based on an example script fragment sent to LKML by Linus Torvalds.\n #\n-# Ignores any parameters for now, excepts changelog entry on stdin.\n-# -C makes cg-commit ignore cache and just commit the thing as-is;\n-# this is for internal purposes (merging).\n-# -m\"log message\" specifies the commit message, which is used instead\n-# of starting up an editor (if the input is not stdin, the input is\n-# appended after all the -m messages). Multiple -m parameters are\n-# appended to a single commit message, each as separate paragraph.\n-# -e forces the editor to be brought up even when -m parameters were\n-# passed to cg-commit.\n-# -E forces the editor to be brought up and it will do the commit\n-# even if the default commit message is not changed.\n-#\n-# These git environment variables are used in case values other than\n-# that returned by getpwuid(getuid()) are desired when performing a commit:\n-#\n-# GIT_AUTHOR_NAME       Author's name\n-# GIT_AUTHOR_EMAIL      Author's e-mail address\n-# GIT_AUTHOR_DATE       Date, perhaps from a patch e-mail\n-# GIT_COMMITTER_NAME    Committer's name\n-# GIT_COMMITTER_EMAIL   Committer's e-mail address\n+#\n+# DESCRIPTION\n+# -----------\n+# Commits changes to a GIT repository. Accepts the commit message from\n+# `stdin`. If the commit message is not modified the commit will be\n+# aborted.\n+#\n+# The `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_AUTHOR_DATE`,\n+# `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` environment variables\n+# are used in case values other than that returned by `getpwuid(getuid())`\n+# are desired when performing a commit.\n+#\n+# OPTIONS\n+# -------\n+# -C::\n+#\tMake `cg-commit` ignore the cache and just commit the thing as-is.\n+#\tNote, this is used internally by Cogito when merging. This option\n+#\tdoes not make sense when files are given on the command line.\n+#\n+# -m<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+#\tForce the editor to be brought up even when '-m' parameters were\n+#\tpassed to `cg-commit`.\n+#\n+# -E::\n+#\tForce the editor to be brought up and do the commit even if\n+#\tthe default commit message is not changed.\n+#\n+# -h, --help::\n+#\tPrint usage help.\n+#\n+# FILES\n+# -----\n+# $GIT_DIR/commit-template::\n+#\tIf the file exists it will be used as a template when creating\n+#\tthe commit message. The template file makes it possible to\n+#\tautomatically add `Signed-off-by` line to the log message.\n+#\n+# $GIT_DIR/hooks/commit-post::\n+#\tIf the file exists and is executable it will be executed upon\n+#\tcompletion of the commit. The script is passed two arguments.\n+#\tThe first argument is the commit ID and the second is the\n+#\tbranchname. A sample `commit-post` script might look like:\n+#\n+#\t#!/bin/sh\n+#\tid=$1\n+#\tbranch=$2\n+#\techo \"Committed $id in $branch\" | mail user@host\n+#\n+# ENVIRONMENT VARIABLES\n+# ---------------------\n+# GIT_AUTHOR_NAME::\n+#\tAuthor's name\n+#\n+# GIT_AUTHOR_EMAIL::\n+#\tAuthor's e-mail address\n+#\n+# GIT_AUTHOR_DATE::\n+#\tDate, useful when applying patches an e-mail\n+#\n+# GIT_COMMITTER_NAME::\n+#\tCommitter's name\n+#\n+# GIT_COMMITTER_EMAIL::\n+#\tCommitter's e-mail address\n+#\n+# EDITOR::\n+#\tThe editor used for entering revision log information.\n+\n+USAGE=\"cg-commit [-m<message>]... [-e | -E] [<file>]...\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-diff\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-diff  (mode:100755)\n+++ uncommitted/cg-diff  (mode:100755)\n@@ -3,18 +3,29 @@\n # Make a diff between two GIT trees.\n # Copyright (c) Petr Baudis, 2005\n #\n+# DESCRIPTION\n+# -----------\n+# Outputs a diff for converting the first tree to the second one.\n # By default compares the current working tree to the state at the\n-# last commit. You can specify -r rev1:rev2 or -r rev1 -r rev2 to\n-# tell it to make a diff between the specified revisions. If you\n-# do not specify a revision, the current working tree is implied\n-# (note that no revision is different from empty revision - -r rev:\n-# compares between rev and HEAD, while -r rev compares between rev\n-# and working tree).\n+# last commit.\n #\n-# -p instead of one ID denotes a parent commit to the specified ID\n-# (which must not be a tree, obviously).\n+# OPTIONS\n+# -------\n+# -p::\n+#\tInstead of one ID denotes a parent commit to the specified ID\n+#\t(which must not be a tree, obviously).\n #\n-# Outputs a diff converting the first tree to the second one.\n+# -r <commit>[:<commit>]::\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+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-diff [-p] [-r <commit>[:<commit>]] [<file>]...\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-export\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-export  (mode:100755)\n+++ uncommitted/cg-export  (mode:100755)\n@@ -3,12 +3,21 @@\n # Exports a particular revision from a GIT repository.\n # Copyright (c) Johannes E. Schindelin, 2005\n #\n-# Takes a destination and optionally an id as a parameter,\n-# defaulting to HEAD.\n+# DESCRIPTION\n+# -----------\n+# Takes a destination and optionally a tree ID as a parameter,\n+# defaulting to 'HEAD'.\n #\n-# The destination can be either a .tar, .tar.gz, .tar.bz2 or .tgz\n+# The destination can be either a `.tar`, `.tar.gz`, `.tar.bz2` or `.tgz`\n # for generating a tarball. Other destination specifiers are assumed\n # to be directory names, and the tree is exported to the given directory.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-export <destination> [<tree>]\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-help\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-help  (mode:100755)\n+++ uncommitted/cg-help  (mode:100755)\n@@ -1,9 +1,24 @@\n #!/usr/bin/env bash\n #\n-# The help for the Cogito toolkit.\n+# Show help for Cogito commands.\n # Copyright (c) Petr Baudis, 2005\n #\n+# DESCRIPTION\n+# -----------\n # Takes an optional argument describing the command to show the help for.\n+# The command can be specified either as '<command>' or 'cg-<command>'.\n+# If the argument is left out an overview of all the Cogito commands will\n+# be shown.\n+#\n+# Note help for a command is also available by passing `--help` or `-h`\n+# to the command.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help\n+\n+USAGE=\"cg-help [<command>]\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-init\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-init  (mode:100755)\n+++ uncommitted/cg-init  (mode:100755)\n@@ -3,10 +3,19 @@\n # Initialize a GIT repository.\n # Copyright (c) Petr Baudis, 2005\n #\n+# DESCRIPTION\n+# -----------\n # Takes an optional parameter which will make it \"clone\" a specified\n-# remote repository. Note that this usage is DEPRECATED - use cg-clone\n-# (possibly with the -s parameter) for doing this. This functionality\n-# will go away from cg-init soon.\n+# remote repository. Note that this usage is 'DEPRECATED'. Instead use\n+# `cg-clone` (possibly with the `-s` parameter) for doing this. This\n+# functionality will go away from `cg-init` soon.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-init\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-log\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-log  (mode:100755)\n+++ uncommitted/cg-log  (mode:100755)\n@@ -4,26 +4,59 @@\n # Copyright (c) Petr Baudis, 2005.\n # Copyright (c) David Woodhouse, 2005.\n #\n-# Takes a -c option to add color to the output.\n-# Currently, the colors are:\n+# DESCRIPTION\n+# -----------\n+# Display log information for files or a range of commits. The output\n+# will automatically be displayed in a pager unless it is piped to\n+# a program.\n+#\n+# OPTIONS\n+# -------\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+#\tAdd color to the output. Currently, the colors are:\n+#\t- `author`:\t'cyan'\n+#\t- `committer`:\t'magenta'\n+#\t- `header`:\t'green'\n+#\t- `files`:\t'blue'\n+#\t- `signoff`:\t'yellow'\n+#\n+# -f::\n+#\tList which files changed.\n+#\n+# -r <commit>[:<commit>]::\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+#\tspecified IDs. If 'TO_ID' is omitted all commits from 'FROM_ID'\n+#\tto the initial commit is shown. If no revisions is specified,\n+#\tthe log information starting from 'HEAD' will be shown.\n+#\n+# -u<username>::\n+#\tList only commits where author or committer contains '<username>'.\n+#\tThe search for '<username>' is case-insensitive.\n+#\n+# -h, --help::\n+#\tPrint usage help.\n+#\n+# EXAMPLE USAGE\n+# -------------\n+# To show a log of changes between two releases tagged as 'releasetag-0.9'\n+# and 'releasetag-0.10' do:\n+#\n+#\t$ cg-log -r releasetag-0.9:releasetag-0.10\n+#\n+# ENVIRONMENT VARIABLES\n+# ---------------------\n+# PAGER::\n+#\tThe pager to display log information in, defaults to `less`.\n #\n-#\theader\t\tGreen\t\n-#\tauthor \t\tCyan\n-#\tcommitter\tMagenta\n-#\tfiles\t\tBlue\n-#\tsignoff\t\tYellow\n-#\n-# Takes an -f option to list which files was changed.\n-#\n-# Takes -u\"username\" to list only commits where author or\n-# committer contains username.\n-#\n-# Takes an -r followed with id resolving to a commit to start from\n-# (HEAD by default), or id1:id2 representing an (id1;id2] range\n-# of commits to show.\n-#\n-# The rest of arguments are took as filenames; cg-log then displays\n-# only changes in those files.\n+# PAGER_FLAGS::\n+#\tFlags to pass to the pager, defaults to `--R`\n+\n+USAGE=\"cg-log [-c] [-f] [-u<username>] [-r <commit>[:<commit>]] <file>...\"\n \n . ${COGITO_LIB}cg-Xlib\n # Try to fix the annoying \"Broken pipe\" output. May not help, but apparently\nIndex: cg-ls\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-ls  (mode:100755)\n+++ uncommitted/cg-ls  (mode:100755)\n@@ -3,7 +3,40 @@\n # List contents of a particular tree in a GIT repository.\n # Copyright (c) Petr Baudis, 2005\n #\n-# Optionally takes commit or tree id as a parameter, defaulting to HEAD.\n+# DESCRIPTION\n+# -----------\n+# Optionally takes a commit or tree ID as a parameter, defaulting to\n+# 'HEAD'.\n+#\n+# Each line in the output has the following format:\n+#\n+#\t<mode>\t<type>\t<sha1>\t<name>\n+#\n+# where\n+#\n+# '<mode>'::\n+#\tThe file permission information in octal format.\n+#\n+# '<type>'::\n+#\tThe type can be the following: `blob` refers to files\n+#\tand `tree` refers to directories.\n+#\n+# '<sha1>'::\n+#\tThe object ID.\n+#\n+# '<name>'::\n+#\tThe file or directory name.\n+#\n+# An example line might look like:\n+#\n+#\t100644  blob    c7dacd0ea28994e3c754ca4eadb2e08c011ee3d3        README\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-ls [<tree>]\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-merge\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-merge  (mode:100755)\n+++ uncommitted/cg-merge  (mode:100755)\n@@ -3,15 +3,28 @@\n # Merge a branch to the current tree.\n # Copyright (c) Petr Baudis, 2005\n #\n+# DESCRIPTION\n+# -----------\n # Takes a parameter identifying the branch to be merged.\n-# Optional \"-b base_commit\" parameter specifies the base for the merge.\n-# Optional \"-c\" parameter specifies that you want to have tree merge\n-# never autocomitted, but want to review and commit it manually.\n #\n-# You have to examine the tree after the merge and then do cg-commit.\n+# You have to examine the tree after the merge and then do `cg-commit`.\n #\n-# Alternatively, it will just bring the HEAD forward, if your current\n-# HEAD is also the merge base.\n+# Alternatively, it will just bring the 'HEAD' forward, if your current\n+# 'HEAD' is also the merge base.\n+#\n+# OPTIONS\n+# -------\n+# -b <commit>::\n+#\tParameter specifies the base commit for the merge.\n+#\n+# -c::\n+#\tParameter specifies that you want to have tree merge never\n+#\tautocomitted, but want to review and commit it manually.\n+#\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-merge [-c] [-b <commit>] <branch>\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-mkpatch\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-mkpatch  (mode:100755)\n+++ uncommitted/cg-mkpatch  (mode:100755)\n@@ -1,14 +1,41 @@\n #!/usr/bin/env bash\n #\n-# Make a patch from a given commit.\n+# Make a patch from one or several commits.\n # Copyright (c) Petr Baudis, 2005\n #\n-# Takes an -s option which specifies whether to print a short\n-# version of the patch without a patch header with meta info such\n-# as author and committer.\n+# DESCRIPTION\n+# -----------\n+# Generate a patch with diff statistics and meta info about each commit.\n #\n-# Takes an -r followed with ID defaulting to HEAD, or id1:id2, forming\n-# a range (id1;id2]. (Use \"id1:\" to take just everything from id1 to HEAD.)\n+# OPTIONS\n+# -------\n+# -s::\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+#\n+# -r <commit>[:<commit>]::\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+#\tspecified IDs. If 'TO_ID' is omitted patches for all commits\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+# -h, --help::\n+#\tPrint usage help.\n+#\n+# EXAMPLE USAGE\n+# -------------\n+# To make patches for all commits between two releases tagged as\n+# 'releasetag-0.9' and 'releasetag-0.10' do:\n+#\n+#\t$ cg-mkpatch -r releasetag-0.9:releasetag-0.10\n+#\n+# The output will be a contionuos dump of patches each separated by\n+# the line\n+# `!-------------------------------------------------------------flip-`\n+\n+USAGE=\"cg-mkpatch [-s] [-r <commit>[:<commit>]]\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-patch\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-patch  (mode:100755)\n+++ uncommitted/cg-patch  (mode:100755)\n@@ -1,12 +1,21 @@\n #!/usr/bin/env bash\n #\n-# Apply a diff generated by git diff.\n+# Apply a diff generated by cg-diff.\n # Copyright (c) Petr Baudis, 2005\n #\n+# DESCRIPTION\n+# -----------\n # This is basically just a smart patch wrapper. It handles stuff like\n # mode changes, removal of files vs. zero-size files etc.\n #\n # Takes the diff on stdin.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-patch < patch on stdin\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-pull\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-pull  (mode:100755)\n+++ uncommitted/cg-pull  (mode:100755)\n@@ -1,11 +1,20 @@\n #!/usr/bin/env bash\n #\n-# Pulls changes from remote branch to the local GIT repository.\n-# Copyright (c) Petr Baudis, 2005\n+# Pull changes from a remote branch to the local GIT repository.\n+# Copyright (c) Petr Baudis, 2005.\n+#\n+# DESCRIPTION\n+# -----------\n+# Takes the branch name as an argument, defaulting to \"origin\".\n #\n # See cg-branch-add for some description.\n #\n-# Takes the branch' name, defaulting to \"origin\".\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-pull [<branch>]\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-restore\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-restore  (mode:100755)\n+++ uncommitted/cg-restore  (mode:100755)\n@@ -1,21 +1,29 @@\n #!/usr/bin/env bash\n #\n-# Restores files removed/changed in the working tree.\n+# Restore removed/changed files in the working tree.\n # Copyright (c) Petr Baudis, 2005\n #\n-# This script restores given files to their original state.\n-#\n-# Without any parameters, it recovers any files removed locally\n-# whose removal was not recorded by cg-rm.\n+# DESCRIPTION\n+# -----------\n+# Restore given files to their original state. Without any parameters,\n+# it recovers any files removed locally whose removal was not recorded\n+# by `cg-rm`.\n #\n # If passed a set of file names, it restores those files to their\n-# state as of the last commit (including bringing cg-rm'd files\n-# back to life; FIXME: does not do that part yet).\n+# state as of the last commit (including bringing files removed with\n+# `cg-rm` back to life; FIXME: does not do that part yet).\n #\n-# This command is complementary to the cg-cancel command, which\n+# This command is complementary to the `cg-cancel` command, which\n # forcefully abandons all the changes in the working tree and\n # restores everything to a proper state (including unseeking,\n # cancelling merge in progress and rebuilding indexes).\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-restore [<file>]...\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-rm\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-rm  (mode:100755)\n+++ uncommitted/cg-rm  (mode:100755)\n@@ -1,10 +1,19 @@\n #!/usr/bin/env bash\n #\n-# Remove a file from a GIT repository.\n+# Remove files from a GIT repository.\n # Copyright (c) Petr Baudis, 2005\n #\n+# DESCRIPTION\n+# -----------\n # Takes a list of file names at the command line, and schedules them\n # for removal from the GIT repository at the next commit.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-rm <file>...\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-seek\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-seek  (mode:100755)\n+++ uncommitted/cg-seek  (mode:100755)\n@@ -3,22 +3,30 @@\n # Seek the working tree to a given commit.\n # Copyright (c) Petr Baudis, 2005\n #\n-# This will bring the working tree from its current HEAD to a given\n-# commit. Note that it changes just the HEAD of the working tree, not\n-# the branch it is corresponding to. It will return to the HEAD of\n+# DESCRIPTION\n+# -----------\n+# Takes the target commit ID to seek to as an argument.\n+# Seeking will bring the working tree from its current 'HEAD' to a given\n+# commit. Note that it changes just the 'HEAD' of the working tree, not\n+# the branch it is corresponding to. It will return to the 'HEAD' of\n # the appropriate branch if passed no arguments.\n #\n # Therefore, for a quick excurse to the past of the 'master' branch:\n #\n-#\tcg-seek git-pasky-0.1\n-#\tcg-diff this master # will do the correct thing\n-#\tcg-seek # will restore what we had before\n+#\t$ cg-seek git-pasky-0.1\n+#\t$ cg-diff this master\t# will do the correct thing\n+#\t$ cg-seek\t\t# will restore what we had before\n #\n-# For intuitiveness, specifying the branch name (cg-seek master) will do\n+# For intuitiveness, specifying the branch name (`cg-seek master`) will do\n # the right thing too. If you want to migrate your working tree to another\n-# branch, use cg-fork.\n+# branch, use `cg-fork`.\n #\n-# Takes the target commit ID.\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-seek <commit>\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-status\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-status  (mode:100755)\n+++ uncommitted/cg-status  (mode:100755)\n@@ -3,7 +3,35 @@\n # Show status of entries in your working tree.\n # Copyright (c) Petr Baudis, 2005\n #\n-# Takes no arguments.\n+# DESCRIPTION\n+# -----------\n+# Print of files in the working tree.\n+#\n+# The output has the following format:\n+#\n+#\t<status flag> <file>\n+#\n+# where '<status flag>' can be one of the following:\n+#\n+# `?`::\n+#\t'<file>' is unknown.\n+# `M`::\n+#\t'<file>' has been touched or modified.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+#\n+# FILES\n+# -----\n+# $GIT_DIR/exclude::\n+#\tIf the file exists it will be used to prune which files to\n+#\tshow status for. The format is similar to the `dontdiff` file;\n+#\teach line contains a pattern for a file or group of files\n+#\tto exclude.\n+\n+USAGE=\"cg-status\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-tag\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-tag  (mode:100755)\n+++ uncommitted/cg-tag  (mode:100755)\n@@ -3,10 +3,19 @@\n # Mark certain commit by a tag.\n # Copyright (c) Petr Baudis, 2005\n #\n-# Creates a tag referencing the given commit (or HEAD). You can then\n-# use the tag anywhere you specify a commit/tree ID.\n+# DESCRIPTION\n+# -----------\n+# Creates a tag referencing the given commit (or 'HEAD'). You can then\n+# use the tag anywhere you specify a commit or tree ID.\n #\n-# Takes the tag's name and optionally the associated ID.\n+# Takes the tag name and optionally the associated ID as arguments.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-tag <tag> [<commit>]\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-tag-ls\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-tag-ls  (mode:100755)\n+++ uncommitted/cg-tag-ls  (mode:100755)\n@@ -3,7 +3,16 @@\n # List stored GIT tags.\n # Copyright (c) Steve Hoelzer 2005\n #\n+# DESCRIPTION\n+# -----------\n # Takes no parameters.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-tag-ls\"\n \n . ${COGITO_LIB}cg-Xlib\n \nIndex: cg-update\n===================================================================\n--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-update  (mode:100755)\n+++ uncommitted/cg-update  (mode:100755)\n@@ -1,9 +1,21 @@\n #!/usr/bin/env bash\n #\n-# Pulls changes from another branch to the local repository and merge changes.\n+# Pull and merge changes from a branch to the local repository.\n # Copyright (c) Petr Baudis, 2005\n #\n-# Takes the branch' name, defaulting to \"origin\".\n+# DESCRIPTION\n+# -----------\n+# Takes the branch name as an argument, defaulting to 'origin'.\n+#\n+# If local changes conflict with those of the branch updated from the\n+# merge will be blocked.\n+#\n+# OPTIONS\n+# -------\n+# -h, --help::\n+#\tPrint usage help.\n+\n+USAGE=\"cg-update [<branch>]\"\n \n . ${COGITO_LIB}cg-Xlib\n \n"}]}