* Re: [RFC] Embedding asciidoc manpages in the cg scripts
2005-05-11 22:48 ` Petr Baudis
@ 2005-05-13 18:48 ` Jonas Fonseca
0 siblings, 0 replies; 5+ messages in thread
From: Jonas Fonseca @ 2005-05-13 18:48 UTC (permalink / raw)
To: Petr Baudis; +Cc: David Greaves, git
[-- Attachment #1: Type: text/plain, Size: 1156 bytes --]
Petr Baudis <pasky@ucw.cz> wrote Thu, May 12, 2005:
> Dear diary, on Thu, May 12, 2005 at 12:20:10AM CEST, I got a letter
> where David Greaves <david@dgreaves.com> told me that...
> > Petr Baudis wrote:
> >
> > >>+# NAME
> > >>+# ----
> > >>+# cg-add - add files to a GIT repository
> > >
> > >Half of this is useless, too.
> > >
> > >I think you should just keep the first paragraph of the files as it is
> > >now. Don't touch it, just parse it.
> > >
> > A bit harsh Petr.
>
> Sorry, I didn't mean to sound (too) harsh. ;-)
Don't mind that you are harsh if it makes sense and I must agree that
having a helper script really paid off reducing the added markup to
almost a half (in my initial patches). Plus, it is now easy to enhance
the manpages with links to referenced commands without having stuff like
'link:' markup in the script headers.
I ended up actually adding two scripts. One for lifting cg-* manpages
and one for generating a cogito manpage with an overview of commands and
information about command identifiers.
The generated manpages can be previewed at:
http://www.nitro.dk/~jonas/cogito/manpages/cogito.html
--
Jonas Fonseca
[-- Attachment #2: cogito-manpages.patch --]
[-- Type: text/plain, Size: 43608 bytes --]
[PATCH] Cogito manpages
Add asciidoc markup to Cogito script headers. Add a script to generate
asciidoc manpages from the cg-* command headers and a script for
generating a cogito(1) manpage. Finally, add build rules for making
Cogito manpages.
Notes:
* USAGE variables are added which can later be used by cg-help or die().
* The command identifiers are name wrapped in '<'/'>' like in the GIT
manpages and are not similar to those in cg-help.
* The top-level Makefile is changed to add a script header to cg-version
so it could also have a man pages. Don't know if that belongs there or
in Documentation/cg-version.txt. Anyway, in order to minimize the
patch I cleaned up the checking of .git/HEAD.
* I had trouble getting asciidoc to accept the line
git+ssh://[user@]host/path
I couldn't figure out how to escape it so I changed it to
git+ssh://host/path or git+ssh://user@host/path
Finally the example with referencing branches via #fragments I shortened
the rsync URL so the line breaking '\' was not needed.
* The description of -r options should be carefully reviewed. I changed
them to be more alike across cg-{diff,log,mkpatch} and some of the
original ones looked wrong.
Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
---
Documentation/Makefile | 11 ++
Documentation/make-cg-manpage | 65 ++++++++++++++++
Documentation/make-cogito-manpage | 149 ++++++++++++++++++++++++++++++++++++++
Makefile | 33 +++++---
cg-add | 18 ++++
cg-admin-lsobj | 35 +++++++-
cg-admin-uncommit | 28 ++++---
cg-branch-add | 44 ++++++-----
cg-branch-ls | 19 ++++
cg-cancel | 19 +++-
cg-clone | 17 +++-
cg-commit | 95 +++++++++++++++++++-----
cg-diff | 29 +++++--
cg-export | 15 +++
cg-help | 17 ++++
cg-init | 15 +++
cg-log | 71 +++++++++++++-----
cg-ls | 35 ++++++++
cg-merge | 25 ++++--
cg-mkpatch | 39 ++++++++-
cg-patch | 11 ++
cg-pull | 15 +++
cg-restore | 24 ++++--
cg-rm | 11 ++
cg-seek | 26 ++++--
cg-status | 30 +++++++
cg-tag | 15 +++
cg-tag-ls | 9 ++
cg-update | 16 +++-
29 files changed, 785 insertions(+), 151 deletions(-)
Index: Documentation/Makefile
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/Documentation/Makefile (mode:100644)
+++ uncommitted/Documentation/Makefile (mode:100644)
@@ -1,4 +1,7 @@
-DOC_SRC=$(wildcard git*.txt)
+CG_IGNORE=$(wildcard ../cg-X*)
+CG_SRC=$(filter-out $(CG_IGNORE), $(wildcard ../cg-*))
+CG_TXT=cogito.txt $(patsubst ../cg-%,cg-%.txt,$(CG_SRC))
+DOC_SRC=$(wildcard git*.txt) $(CG_TXT)
DOC_HTML=$(patsubst %.txt,%.html,$(DOC_SRC))
DOC_MAN=$(patsubst %.txt,%.1,$(DOC_SRC))
@@ -22,3 +25,9 @@
%.xml : %.txt
asciidoc -b docbook -d manpage $<
+
+cogito.txt : make-cogito-manpage
+ ./make-cogito-manpage > $@
+
+cg-%.txt : ../cg-% make-cg-manpage
+ ./make-cg-manpage $< > $@
Index: Documentation/make-cg-manpage
===================================================================
--- /dev/null (tree:de641904363cd3759f132ee7c0dfaf8a2ee58388)
+++ uncommitted/Documentation/make-cg-manpage (mode:100755)
@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+#
+# Generate asciidoc manpage markup from Cogito script header.
+# Copyright (c) Jonas Fonseca, 2005
+#
+# Takes a path to a Cogito script. Prints the manpage to stdout.
+
+. ${COGITO_LIB}cg-Xlib
+
+command=$1
+
+[ -e "$command" ] || die "$command does not exist"
+
+COMMAND=$(basename $command)
+
+# FIXME: Show the SHA1 of the command below the TITLELINE.
+
+# Generate the 'CG-COMMAND(1)' title from cg-command
+TITLE="$COMMAND(1)"
+# Asciidocs wants the title line ('====') to be as wide as the title.
+TITLELINE=$(echo "$TITLE" | sed 's/[0-9a-zA-Z-()]/=/g')
+
+# Get `USAGE="cg-command args..."` line and make it `cg-command args...`
+SYNOPSIS=$(grep 'USAGE=' $command | sed 's/^USAGE="\(.*\)"/\1/')
+
+# Extract the script header.
+HEADER=$(cat $command | sed -n '3,/^$/s/^# *//p')
+
+# Some scripts have copyright lines followed by 'Based on script by ...' lines.
+# Include them so they are also put in the COPYRIGHT section.
+COPYRIGHT=$(cat $command | sed -n '3,/^$/s/^# *//p' \
+ | sed -n '/^Copyright (c)/,/^$/p' \
+ | sed 's/(c)/(C)/')
+
+# First line of the header contains the caption. Normalize it by lowercasing the
+# start and stripping any punctuation.
+CAPTION=$(echo "$HEADER" | head -n 1 | tr '[A-Z]' '[a-z]' | sed 's/\.$//')
+
+# Get remaining sections and carefully insert links to cogito commands when they
+# were referenced as "`cg-command`". Note, we can't just do it for any cg-*
+# combo because code listings will ignore any asciidoc markup...."
+BODY=$(echo "$HEADER" | sed -n '/^DESCRIPTION$/,$p' \
+ | sed 's/`\(cg-[a-z-]\+\)`/link:\1.html[`\1(1)`]/')
+
+echo "$TITLE"
+echo "$TITLELINE"
+echo
+echo "NAME"
+echo "----"
+echo "$COMMAND - $CAPTION"
+echo
+echo "SYNOPSIS"
+echo "--------"
+echo "$SYNOPSIS"
+echo
+echo "$BODY"
+echo
+echo "COPYRIGHT"
+echo "---------"
+echo "$COPYRIGHT"
+echo
+echo "SEE ALSO"
+echo "--------"
+echo "$COMMAND command is part of link:cogito.html[cogito(1)],"
+echo "a toolkit for managing link:git.html[git(1)] trees."
Index: Documentation/make-cogito-manpage
===================================================================
--- /dev/null (tree:de641904363cd3759f132ee7c0dfaf8a2ee58388)
+++ uncommitted/Documentation/make-cogito-manpage (mode:100755)
@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+#
+# Generate a quick reference asciidoc manpage for the Cogito.
+# Copyright (c) Jonas Fonseca, 2005
+
+# Shorthand for the link markup.
+link()
+{
+ command="$1"
+ echo "link:$command.html[\`$command(1)\`]"
+}
+
+# Print description list entry.
+print_command_info()
+{
+ command="$1"
+ caption=$(cat "$command" | head -n 3 | tail -n 1 | sed 's/# //')
+ usage=$(grep 'USAGE=' "$command" | sed 's/^USAGE="\(.*\)"/\1/')
+ cmdname=$(basename $command)
+
+ echo
+ case "$cmdname" in
+ cg-*)
+ link "$cmdname"
+ ;;
+ *-id)
+ echo "$cmdname::"
+ ;;
+ esac
+ echo " $caption"
+ echo
+ echo " $usage"
+}
+
+cat <<__END__
+cogito(1)
+=========
+
+NAME
+----
+cogito - SCM-like GIT layer
+
+SYNOPSIS
+--------
+cg-<command> <arg>...
+
+DESCRIPTION
+-----------
+
+Cogito is a revision control system for tracking changes to content in a
+highly distributed development environment. Amongst some of the noteworthy
+features, Cogito has support for branching, tagging and multiple backends for
+distributing repositories (local files, rsync, HTTP, ssh).
+
+Cogito is implemented as a series of \`bash(1)\` scripts on top of $(link git)
+(a stupid content tracker) with the goal of providing an interface for working
+with the GIT database in a manner similar to other SCM tools (like CVS,
+BitKeeper or Monotone).
+
+Commands Overview
+-----------------
+
+The Cogito commands can be split into regular commands and advanced commands.
+The regular commands are those used for normal interacting with the
+repository, while the advanced commands can be used for administrating the
+repository and should to some degree be regarded as low-level and in some
+cases dangerous.
+
+Below an overview of the available commands are listed. For details on
+individual commands, do e.g. \`cg-help cg-log\` or \`cg-log --help\`.
+
+Regular commands
+~~~~~~~~~~~~~~~~
+__END__
+
+for command in $(ls ../cg-* | grep -v cg-admin- | grep -v cg-X); do
+ print_command_info "$command"
+done
+
+cat <<__END__
+
+Advanced commands
+~~~~~~~~~~~~~~~~~
+__END__
+
+for command in $(ls ../cg-admin-*); do
+ print_command_info "$command"
+done
+
+cat <<__END__
+
+Helper commands
+~~~~~~~~~~~~~~~
+
+Cogito also provides various helper commands for resolving IDs for symbolic
+names etc. The commands are:
+__END__
+
+for command in $(ls ../*-id | grep -v git-); do
+ print_command_info "$command"
+done
+
+cat <<__END__
+
+Command Identifiers
+-------------------
+<branch>::
+ Indicates a branch name added with the $(link cg-branch-add) name.
+
+<command>::
+ Indicates a Cogito command. The \`cg-\` prefix is optional.
+
+<location>::
+ Indicates a local file path or a URI. See $(link cg-branch-add) for a
+ list of supported URI schemes.
+
+<revision>::
+ Indicates an ID resolving to a commit. The following expressions can
+ be used interchangably as IDs:
+ - empty string, 'this' or 'HEAD' (current HEAD)
+ - branch name (as registered with $(link cg-branch-add))
+ - tag name (as registered with $(link cg-tag))
+ - shortcut object hash (shorted unambiguous hash lead)
+ - commit object hash (as returned by \`commit-id\`)
+ - tree object hash (as returned by \`tree-id\`)
+
+<tag>::
+ Indicates a free form tag name.
+
+<type>::
+ Indicates a git object type i.e.: \`blob\`, \`commit\`, \`tree\` or
+ \`tag\`.
+
+<username>::
+ Indicates a free form user name.
+
+<file>::
+ Indicates a filename - always relative to the root of the repository.
+
+AUTHORS
+-------
+Cogito was written by Petr Baudis <pasky@ucw.cz>.
+This manpage was written by Jonas Fonseca <fonseca@diku.dk>.
+
+COPYRIGHT
+---------
+Copyright (C) Petr Baudis, 2005.
+Copyright (C) Jonas Fonseca, 2005.
+__END__
Index: Makefile
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/Makefile (mode:100644)
+++ uncommitted/Makefile (mode:100644)
@@ -114,20 +114,33 @@
ifneq (,$(wildcard .git))
-cg-version: $(VERSION) .git/HEAD
- @echo Generating cg-version...
- @rm -f $@
- @echo "#!/bin/sh" > $@
- @echo "echo \"$(shell cat $(VERSION)) ($(shell cat .git/HEAD))\"" >> $@
- @chmod +x $@
-else
-cg-version: $(VERSION)
+GIT_HEAD=.git/HEAD
+GIT_HEAD_ID=" $(shell cat $(GIT_HEAD))"
+endif
+cg-version: $(VERSION) $(GITHEAD) Makefile
@echo Generating cg-version...
@rm -f $@
@echo "#!/bin/sh" > $@
- @echo "echo \"$(shell cat $(VERSION))\"" >> $@
+ @echo "#" >> $@
+ @echo "# Show the version of the Cogito toolkit." >> $@
+ @echo "# Copyright (c) Petr Baudis, 2005" >> $@
+ @echo "#" >> $@
+ @echo "# DESCRIPTION" >> $@
+ @echo "# -----------" >> $@
+ @echo "# Show which version of Cogito is installed." >> $@
+ @echo "# Additionally, the 'HEAD' of the installed Cogito" >> $@
+ @echo "# is also shown if this information was available" >> $@
+ @echo "# at the build time." >> $@
+ @echo "#" >> $@
+ @echo "# OPTIONS" >> $@
+ @echo "# -------" >> $@
+ @echo "# -h, --help::" >> $@
+ @echo "# Print usage help." >> $@
+ @echo >> $@
+ @echo "USAGE=\"cg-version\"" >> $@
+ @echo >> $@
+ @echo "echo \"$(shell cat $(VERSION))$(GIT_HEAD_ID)\"" >> $@
@chmod +x $@
-endif
git.spec: git.spec.in $(VERSION)
sed -e 's/@@VERSION@@/$(shell cat $(VERSION) | cut -d"-" -f2)/g' < $< > $@
Index: cg-add
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-add (mode:100755)
+++ uncommitted/cg-add (mode:100755)
@@ -1,10 +1,26 @@
#!/usr/bin/env bash
#
-# Add new file to a GIT repository.
+# Add files to the GIT repository.
# Copyright (c) Petr Baudis, 2005
#
+# DESCRIPTION
+# -----------
# Takes a list of file names at the command line, and schedules them
# for addition to the GIT repository at the next commit.
+#
+# The command will fail if one of the given files does not exist.
+#
+# Note that cogito manage content. Which means it doesn't make sense
+# to `cg-add` stand-alone directories since directories have no content.
+# Instead add a file within the new directory and `cg-add` will create
+# a tree for managing the directory as needed.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-add <file>..."
. ${COGITO_LIB}cg-Xlib
Index: cg-admin-lsobj
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-admin-lsobj (mode:100755)
+++ uncommitted/cg-admin-lsobj (mode:100755)
@@ -4,17 +4,44 @@
# Copyright (c) Randy Dunlap, 2005
# Copyright (c) Petr Baudis, 2005
#
-# Lists IDs of all the objects of a given type (blob, tree, commit) found
-# in the dircache.
+# DESCRIPTION
+# -----------
+# Lists IDs of all the objects of a given type found in the dircache.
+# Takes the object type as the first parameter, defaults to all objects.
+#
+# The possible object types are:
+# `blob`::
+# This object is a pure storage object containing some user data.
+#
+# `commit`::
+# This object ties directory hierarchies together into a DAG
+# of revisions.
+#
+# `tree`::
+# This object is an object that ties one or more `blob` objects
+# into a directory structure.
+#
+# `tag`::
+# This object ties a symbolic release tag to an object in the
+# database.
#
-# Example usage:
+# See the git README for more information about the object types.
+#
+# EXAMPLE USAGE
+# -------------
# Oh, I was messing with my HEADs and lost few commits, where on the earth
# could they be...?
+#
# for i in `cg-admin-lsobj commit | cut -f 1`; do
# echo -e "\n==================\nme $i"; cat-file commit $i;
# done
#
-# Takes the object type as the first parameter, defaults to all objects.
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-admin-lsobj [<type>]"
. ${COGITO_LIB}cg-Xlib
Index: cg-admin-uncommit
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-admin-uncommit (mode:100755)
+++ uncommitted/cg-admin-uncommit (mode:100755)
@@ -1,18 +1,28 @@
#!/usr/bin/env bash
#
-# Undo a commit or a series of commits
+# Undo a commit or a series of commits.
# Copyright (c) Matt Porter, 2005
# Copyright (c) Petr Baudis, 2005
#
-# Optional -t parameter makes cg-admin-uncommit to roll back the tree
-# as well to the previous commit. Without this option (by default)
-# Cogito keeps the tree in its current state, therefore generating
-# tree with local changes against the target commit, consisting of the
-# changes in the rolled back commits.
+# DESCRIPTION
+# -----------
+# Takes a commit ID which is the earliest commit to be removed from
+# the repository. If no parameter is passed, it uncommits the latest
+# commit ('HEAD').
#
-# Takes a commit ID which is the earliest commit to be
-# removed from the repository. If no parameter is passed,
-# it uncommits the latest commit (HEAD).
+# OPTIONS
+# -------
+# -t::
+# This optional parameter makes `cg-admin-uncommit` to roll back
+# the tree as well to the previous commit. Without this option
+# (by default) Cogito keeps the tree in its current state,
+# therefore generating tree with local changes against the target
+# commit, consisting of the changes in the rolled back commits.
+#
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-admin-uncommit [-t] [<commit>]"
. ${COGITO_LIB}cg-Xlib
Index: cg-branch-add
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-branch-add (mode:100755)
+++ uncommitted/cg-branch-add (mode:100755)
@@ -3,35 +3,41 @@
# Add new branch to the GIT repository.
# Copyright (c) Petr Baudis, 2005
#
-# After you add a branch, you can cg-pull it whenever you want
-# and it will keep your objects database in sync with it. Its latest
-# commit is accessible as .git/refs/heads/branchname (or - more conveniently
-# - as $(commit-id branchname)). For example, to make a diff between
-# Linus (after you added him) and your current tree, do
-#
-# cg-pull linus
-# cg-diff linus
+# DESCRIPTION
+# -----------
+# Takes the branch name and source location as parameters.
+# After you add a branch, you can `cg-pull` it whenever you want and
+# it will keep your objects database in sync with it. Its latest
+# commit is accessible as `.git/refs/heads/branchname` (or - more
+# conveniently - as `$(commit-id branchname)`). For example, to make a
+# diff between Linus (after you added him) and your current tree, do:
#
+# $ cg-pull linus
+# $ cg-diff linus
#
# The possible location specifiers are:
#
-# (1) Local path - note that pulling will hardlink the objects, not copy them.
-# (2) rsync - either rsync://host/path or host:/path (the latter can change)
-# (3) HTTP - http://host/path
-# (4) SSH - git+ssh://[user@]host/absolute/path
+# 1. Local path - note that pulling will hardlink the objects, not copy them.
+# 2. rsync - either `rsync://host/path` or `host:/path` (the latter can change)
+# 3. HTTP - `http://host/path`
+# 4. SSH - `git+ssh://host/path` or `git+ssh://user@host/path` - note that
+# the path must be absolute.
#
# The URL can have a fragment part, which identifies a branch inside of
# the repository. Therefore, if you have a repository
-# rsync://kernel.org/pub/scm/linux/kernel/mj/linux.git and you are interested
-# in its 'testing' branch, you can e.g.
-#
-# cg-branch-add mj-testing \
-# rsync://kernel.org/pub/scm/linux/kernel/mj/linux.git#testing
+# `rsync://host/path/repo.git` and you are interested in its 'testing'
+# branch, you can e.g.:
#
-# and refer to it as 'mj-testing' anytime later.
+# $ cg-branch-add repo-testing rsync://host/path/repo.git#testing
#
+# and refer to it as 'repo-testing' anytime later.
#
-# Takes the branch' name and location as parameters.
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-admin-uncommit <branch> <location>"
. ${COGITO_LIB}cg-Xlib
Index: cg-branch-ls
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-branch-ls (mode:100755)
+++ uncommitted/cg-branch-ls (mode:100755)
@@ -3,7 +3,24 @@
# List configured GIT branches.
# Copyright (c) Steven Cole 2005
#
-# Takes no parameters.
+# DESCRIPTION
+# -----------
+# Print a listing of all known branches.
+#
+# The output has the following format:
+#
+# <branch> <location>
+#
+# For example
+#
+# origin rsync://rsync.kernel.org/pub/scm/cogito/cogito.git
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-branch-ls"
. ${COGITO_LIB}cg-Xlib
Index: cg-cancel
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-cancel (mode:100755)
+++ uncommitted/cg-cancel (mode:100755)
@@ -3,16 +3,23 @@
# Cancels current edits in the working tree.
# Copyright (c) Petr Baudis, 2005
#
-# This script reverts the working tree to a consistent state before
-# any changes to it (including merges etc) were done.
+# DESCRIPTION
+# -----------
+# Reverts the working tree to a consistent state before any changes to it
+# (including merges etc.) were done.
#
-# Basically, this is the opposite of cg-commit in some sense.
+# Basically, this is the opposite of `cg-commit` in some sense.
#
-# Takes no arguments and the evil changes from the tree.
-#
-# This command is complementary to cg-restore, which only brings
+# This command is complementary to `cg-restore`, which only brings
# individual files in sync with their state at the time of the
# last commit.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help
+
+USAGE="cg-cancel"
. ${COGITO_LIB}cg-Xlib
Index: cg-clone
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-clone (mode:100755)
+++ uncommitted/cg-clone (mode:100755)
@@ -3,16 +3,25 @@
# Clone a remote GIT repository.
# Copyright (c) Petr Baudis, 2005
#
+# DESCRIPTION
+# -----------
# This is like cg-init, but it will create a new directory where it will do
# the checkout.
#
-# If you pass it an optional -s parameter, it does the clone in the current
-# directory instead of creating a new one.
-#
# Takes a parameter specifying the location of the source repository and an
-# optional second parameter specifying the destination. If the second
+# optional second parameter specifying the destination. If the second
# parameter is omitted, the basename of the source repository is used as the
# destination.
+#
+# OPTIONS
+# -------
+# -s::
+# Clone in the current directory instead of creating a new one.
+#
+# -h, --help::
+# Print usage help
+
+USAGE="cg-clone [-s] <location> [<directory>]"
. ${COGITO_LIB}cg-Xlib
Index: cg-commit
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-commit (mode:100755)
+++ uncommitted/cg-commit (mode:100755)
@@ -4,26 +4,81 @@
# Copyright (c) Petr Baudis, 2005
# Based on an example script fragment sent to LKML by Linus Torvalds.
#
-# Ignores any parameters for now, excepts changelog entry on stdin.
-# -C makes cg-commit ignore cache and just commit the thing as-is;
-# this is for internal purposes (merging).
-# -m"log message" specifies the commit message, which is used instead
-# of starting up an editor (if the input is not stdin, the input is
-# appended after all the -m messages). Multiple -m parameters are
-# appended to a single commit message, each as separate paragraph.
-# -e forces the editor to be brought up even when -m parameters were
-# passed to cg-commit.
-# -E forces the editor to be brought up and it will do the commit
-# even if the default commit message is not changed.
-#
-# These git environment variables are used in case values other than
-# that returned by getpwuid(getuid()) are desired when performing a commit:
-#
-# GIT_AUTHOR_NAME Author's name
-# GIT_AUTHOR_EMAIL Author's e-mail address
-# GIT_AUTHOR_DATE Date, perhaps from a patch e-mail
-# GIT_COMMITTER_NAME Committer's name
-# GIT_COMMITTER_EMAIL Committer's e-mail address
+#
+# DESCRIPTION
+# -----------
+# Commits changes to a GIT repository. Accepts the commit message from
+# `stdin`. If the commit message is not modified the commit will be
+# aborted.
+#
+# The `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_AUTHOR_DATE`,
+# `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` environment variables
+# are used in case values other than that returned by `getpwuid(getuid())`
+# are desired when performing a commit.
+#
+# OPTIONS
+# -------
+# -C::
+# Make `cg-commit` ignore the cache and just commit the thing as-is.
+# Note, this is used internally by Cogito when merging. This option
+# does not make sense when files are given on the command line.
+#
+# -m<message>::
+# Specify the commit message, which is used instead of starting
+# up an editor (if the input is not `stdin`, the input is appended
+# after all the '-m' messages). Multiple '-m' parameters are appended
+# to a single commit message, each as separate paragraph.
+#
+# -e::
+# Force the editor to be brought up even when '-m' parameters were
+# passed to `cg-commit`.
+#
+# -E::
+# Force the editor to be brought up and do the commit even if
+# the default commit message is not changed.
+#
+# -h, --help::
+# Print usage help.
+#
+# FILES
+# -----
+# $GIT_DIR/commit-template::
+# If the file exists it will be used as a template when creating
+# the commit message. The template file makes it possible to
+# automatically add `Signed-off-by` line to the log message.
+#
+# $GIT_DIR/hooks/commit-post::
+# If the file exists and is executable it will be executed upon
+# completion of the commit. The script is passed two arguments.
+# The first argument is the commit ID and the second is the
+# branchname. A sample `commit-post` script might look like:
+#
+# #!/bin/sh
+# id=$1
+# branch=$2
+# echo "Committed $id in $branch" | mail user@host
+#
+# ENVIRONMENT VARIABLES
+# ---------------------
+# GIT_AUTHOR_NAME::
+# Author's name
+#
+# GIT_AUTHOR_EMAIL::
+# Author's e-mail address
+#
+# GIT_AUTHOR_DATE::
+# Date, useful when applying patches an e-mail
+#
+# GIT_COMMITTER_NAME::
+# Committer's name
+#
+# GIT_COMMITTER_EMAIL::
+# Committer's e-mail address
+#
+# EDITOR::
+# The editor used for entering revision log information.
+
+USAGE="cg-commit [-m<message>]... [-e | -E] [<file>]..."
. ${COGITO_LIB}cg-Xlib
Index: cg-diff
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-diff (mode:100755)
+++ uncommitted/cg-diff (mode:100755)
@@ -3,18 +3,29 @@
# Make a diff between two GIT trees.
# Copyright (c) Petr Baudis, 2005
#
+# DESCRIPTION
+# -----------
+# Outputs a diff for converting the first tree to the second one.
# By default compares the current working tree to the state at the
-# last commit. You can specify -r rev1:rev2 or -r rev1 -r rev2 to
-# tell it to make a diff between the specified revisions. If you
-# do not specify a revision, the current working tree is implied
-# (note that no revision is different from empty revision - -r rev:
-# compares between rev and HEAD, while -r rev compares between rev
-# and working tree).
+# last commit.
#
-# -p instead of one ID denotes a parent commit to the specified ID
-# (which must not be a tree, obviously).
+# OPTIONS
+# -------
+# -p::
+# Instead of one ID denotes a parent commit to the specified ID
+# (which must not be a tree, obviously).
#
-# Outputs a diff converting the first tree to the second one.
+# -r <commit>[:<commit>]::
+# Specify the revisions to diff using either '-r rev1:rev2' or
+# '-r rev1 -r rev2'. If no revision is specified, the current
+# working tree is implied. Note that no revision is different from
+# empty revision which means '-r rev:' compares between 'rev' and
+# 'HEAD', while '-r rev' compares between 'rev' and working tree.
+#
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-diff [-p] [-r <commit>[:<commit>]] [<file>]..."
. ${COGITO_LIB}cg-Xlib
Index: cg-export
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-export (mode:100755)
+++ uncommitted/cg-export (mode:100755)
@@ -3,12 +3,21 @@
# Exports a particular revision from a GIT repository.
# Copyright (c) Johannes E. Schindelin, 2005
#
-# Takes a destination and optionally an id as a parameter,
-# defaulting to HEAD.
+# DESCRIPTION
+# -----------
+# Takes a destination and optionally a tree ID as a parameter,
+# defaulting to 'HEAD'.
#
-# The destination can be either a .tar, .tar.gz, .tar.bz2 or .tgz
+# The destination can be either a `.tar`, `.tar.gz`, `.tar.bz2` or `.tgz`
# for generating a tarball. Other destination specifiers are assumed
# to be directory names, and the tree is exported to the given directory.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-export <destination> [<tree>]"
. ${COGITO_LIB}cg-Xlib
Index: cg-help
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-help (mode:100755)
+++ uncommitted/cg-help (mode:100755)
@@ -1,9 +1,24 @@
#!/usr/bin/env bash
#
-# The help for the Cogito toolkit.
+# Show help for Cogito commands.
# Copyright (c) Petr Baudis, 2005
#
+# DESCRIPTION
+# -----------
# Takes an optional argument describing the command to show the help for.
+# The command can be specified either as '<command>' or 'cg-<command>'.
+# If the argument is left out an overview of all the Cogito commands will
+# be shown.
+#
+# Note help for a command is also available by passing `--help` or `-h`
+# to the command.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help
+
+USAGE="cg-help [<command>]"
. ${COGITO_LIB}cg-Xlib
Index: cg-init
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-init (mode:100755)
+++ uncommitted/cg-init (mode:100755)
@@ -3,10 +3,19 @@
# Initialize a GIT repository.
# Copyright (c) Petr Baudis, 2005
#
+# DESCRIPTION
+# -----------
# Takes an optional parameter which will make it "clone" a specified
-# remote repository. Note that this usage is DEPRECATED - use cg-clone
-# (possibly with the -s parameter) for doing this. This functionality
-# will go away from cg-init soon.
+# remote repository. Note that this usage is 'DEPRECATED'. Instead use
+# `cg-clone` (possibly with the `-s` parameter) for doing this. This
+# functionality will go away from `cg-init` soon.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-init"
. ${COGITO_LIB}cg-Xlib
Index: cg-log
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-log (mode:100755)
+++ uncommitted/cg-log (mode:100755)
@@ -4,26 +4,59 @@
# Copyright (c) Petr Baudis, 2005.
# Copyright (c) David Woodhouse, 2005.
#
-# Takes a -c option to add color to the output.
-# Currently, the colors are:
+# DESCRIPTION
+# -----------
+# Display log information for files or a range of commits. The output
+# will automatically be displayed in a pager unless it is piped to
+# a program.
+#
+# OPTIONS
+# -------
+# Arguments not interpreted as options will be interpreted as filenames;
+# cg-log then displays only changes in those files.
+#
+# -c::
+# Add color to the output. Currently, the colors are:
+# - `author`: 'cyan'
+# - `committer`: 'magenta'
+# - `header`: 'green'
+# - `files`: 'blue'
+# - `signoff`: 'yellow'
+#
+# -f::
+# List which files changed.
+#
+# -r <commit>[:<commit>]::
+# Limit the log information to a set of revisions using either
+# '-r FROM_ID[:TO_ID]' or '-r FROM_ID -r TO_ID'. In both cases the
+# option expects IDs which resolve to commits and will include the
+# specified IDs. If 'TO_ID' is omitted all commits from 'FROM_ID'
+# to the initial commit is shown. If no revisions is specified,
+# the log information starting from 'HEAD' will be shown.
+#
+# -u<username>::
+# List only commits where author or committer contains '<username>'.
+# The search for '<username>' is case-insensitive.
+#
+# -h, --help::
+# Print usage help.
+#
+# EXAMPLE USAGE
+# -------------
+# To show a log of changes between two releases tagged as 'releasetag-0.9'
+# and 'releasetag-0.10' do:
+#
+# $ cg-log -r releasetag-0.9:releasetag-0.10
+#
+# ENVIRONMENT VARIABLES
+# ---------------------
+# PAGER::
+# The pager to display log information in, defaults to `less`.
#
-# header Green
-# author Cyan
-# committer Magenta
-# files Blue
-# signoff Yellow
-#
-# Takes an -f option to list which files was changed.
-#
-# Takes -u"username" to list only commits where author or
-# committer contains username.
-#
-# Takes an -r followed with id resolving to a commit to start from
-# (HEAD by default), or id1:id2 representing an (id1;id2] range
-# of commits to show.
-#
-# The rest of arguments are took as filenames; cg-log then displays
-# only changes in those files.
+# PAGER_FLAGS::
+# Flags to pass to the pager, defaults to `--R`
+
+USAGE="cg-log [-c] [-f] [-u<username>] [-r <commit>[:<commit>]] <file>..."
. ${COGITO_LIB}cg-Xlib
# Try to fix the annoying "Broken pipe" output. May not help, but apparently
Index: cg-ls
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-ls (mode:100755)
+++ uncommitted/cg-ls (mode:100755)
@@ -3,7 +3,40 @@
# List contents of a particular tree in a GIT repository.
# Copyright (c) Petr Baudis, 2005
#
-# Optionally takes commit or tree id as a parameter, defaulting to HEAD.
+# DESCRIPTION
+# -----------
+# Optionally takes a commit or tree ID as a parameter, defaulting to
+# 'HEAD'.
+#
+# Each line in the output has the following format:
+#
+# <mode> <type> <sha1> <name>
+#
+# where
+#
+# '<mode>'::
+# The file permission information in octal format.
+#
+# '<type>'::
+# The type can be the following: `blob` refers to files
+# and `tree` refers to directories.
+#
+# '<sha1>'::
+# The object ID.
+#
+# '<name>'::
+# The file or directory name.
+#
+# An example line might look like:
+#
+# 100644 blob c7dacd0ea28994e3c754ca4eadb2e08c011ee3d3 README
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-ls [<tree>]"
. ${COGITO_LIB}cg-Xlib
Index: cg-merge
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-merge (mode:100755)
+++ uncommitted/cg-merge (mode:100755)
@@ -3,15 +3,28 @@
# Merge a branch to the current tree.
# Copyright (c) Petr Baudis, 2005
#
+# DESCRIPTION
+# -----------
# Takes a parameter identifying the branch to be merged.
-# Optional "-b base_commit" parameter specifies the base for the merge.
-# Optional "-c" parameter specifies that you want to have tree merge
-# never autocomitted, but want to review and commit it manually.
#
-# You have to examine the tree after the merge and then do cg-commit.
+# You have to examine the tree after the merge and then do `cg-commit`.
#
-# Alternatively, it will just bring the HEAD forward, if your current
-# HEAD is also the merge base.
+# Alternatively, it will just bring the 'HEAD' forward, if your current
+# 'HEAD' is also the merge base.
+#
+# OPTIONS
+# -------
+# -b <commit>::
+# Parameter specifies the base commit for the merge.
+#
+# -c::
+# Parameter specifies that you want to have tree merge never
+# autocomitted, but want to review and commit it manually.
+#
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-merge [-c] [-b <commit>] <branch>"
. ${COGITO_LIB}cg-Xlib
Index: cg-mkpatch
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-mkpatch (mode:100755)
+++ uncommitted/cg-mkpatch (mode:100755)
@@ -1,14 +1,41 @@
#!/usr/bin/env bash
#
-# Make a patch from a given commit.
+# Make a patch from one or several commits.
# Copyright (c) Petr Baudis, 2005
#
-# Takes an -s option which specifies whether to print a short
-# version of the patch without a patch header with meta info such
-# as author and committer.
+# DESCRIPTION
+# -----------
+# Generate a patch with diff statistics and meta info about each commit.
#
-# Takes an -r followed with ID defaulting to HEAD, or id1:id2, forming
-# a range (id1;id2]. (Use "id1:" to take just everything from id1 to HEAD.)
+# OPTIONS
+# -------
+# -s::
+# Specify whether to print a short version of the patch without
+# a patch header with meta info such as author and committer.
+#
+# -r <commit>[:<commit>]::
+# Specify a set of commits to make patches from using either
+# '-r FROM_ID[:TO_ID]' or '-r FROM_ID -r TO_ID'. In both cases the
+# option expects IDs which resolve to commits and will include the
+# specified IDs. If 'TO_ID' is omitted patches for all commits
+# from 'FROM_ID' to the initial commit will be generated. If no
+# `-r` option is given the commit ID defaults to 'HEAD'.
+#
+# -h, --help::
+# Print usage help.
+#
+# EXAMPLE USAGE
+# -------------
+# To make patches for all commits between two releases tagged as
+# 'releasetag-0.9' and 'releasetag-0.10' do:
+#
+# $ cg-mkpatch -r releasetag-0.9:releasetag-0.10
+#
+# The output will be a contionuos dump of patches each separated by
+# the line
+# `!-------------------------------------------------------------flip-`
+
+USAGE="cg-mkpatch [-s] [-r <commit>[:<commit>]]"
. ${COGITO_LIB}cg-Xlib
Index: cg-patch
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-patch (mode:100755)
+++ uncommitted/cg-patch (mode:100755)
@@ -1,12 +1,21 @@
#!/usr/bin/env bash
#
-# Apply a diff generated by git diff.
+# Apply a diff generated by cg-diff.
# Copyright (c) Petr Baudis, 2005
#
+# DESCRIPTION
+# -----------
# This is basically just a smart patch wrapper. It handles stuff like
# mode changes, removal of files vs. zero-size files etc.
#
# Takes the diff on stdin.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-patch < patch on stdin"
. ${COGITO_LIB}cg-Xlib
Index: cg-pull
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-pull (mode:100755)
+++ uncommitted/cg-pull (mode:100755)
@@ -1,11 +1,20 @@
#!/usr/bin/env bash
#
-# Pulls changes from remote branch to the local GIT repository.
-# Copyright (c) Petr Baudis, 2005
+# Pull changes from a remote branch to the local GIT repository.
+# Copyright (c) Petr Baudis, 2005.
+#
+# DESCRIPTION
+# -----------
+# Takes the branch name as an argument, defaulting to "origin".
#
# See cg-branch-add for some description.
#
-# Takes the branch' name, defaulting to "origin".
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-pull [<branch>]"
. ${COGITO_LIB}cg-Xlib
Index: cg-restore
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-restore (mode:100755)
+++ uncommitted/cg-restore (mode:100755)
@@ -1,21 +1,29 @@
#!/usr/bin/env bash
#
-# Restores files removed/changed in the working tree.
+# Restore removed/changed files in the working tree.
# Copyright (c) Petr Baudis, 2005
#
-# This script restores given files to their original state.
-#
-# Without any parameters, it recovers any files removed locally
-# whose removal was not recorded by cg-rm.
+# DESCRIPTION
+# -----------
+# Restore given files to their original state. Without any parameters,
+# it recovers any files removed locally whose removal was not recorded
+# by `cg-rm`.
#
# If passed a set of file names, it restores those files to their
-# state as of the last commit (including bringing cg-rm'd files
-# back to life; FIXME: does not do that part yet).
+# state as of the last commit (including bringing files removed with
+# `cg-rm` back to life; FIXME: does not do that part yet).
#
-# This command is complementary to the cg-cancel command, which
+# This command is complementary to the `cg-cancel` command, which
# forcefully abandons all the changes in the working tree and
# restores everything to a proper state (including unseeking,
# cancelling merge in progress and rebuilding indexes).
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-restore [<file>]..."
. ${COGITO_LIB}cg-Xlib
Index: cg-rm
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-rm (mode:100755)
+++ uncommitted/cg-rm (mode:100755)
@@ -1,10 +1,19 @@
#!/usr/bin/env bash
#
-# Remove a file from a GIT repository.
+# Remove files from a GIT repository.
# Copyright (c) Petr Baudis, 2005
#
+# DESCRIPTION
+# -----------
# Takes a list of file names at the command line, and schedules them
# for removal from the GIT repository at the next commit.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-rm <file>..."
. ${COGITO_LIB}cg-Xlib
Index: cg-seek
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-seek (mode:100755)
+++ uncommitted/cg-seek (mode:100755)
@@ -3,22 +3,30 @@
# Seek the working tree to a given commit.
# Copyright (c) Petr Baudis, 2005
#
-# This will bring the working tree from its current HEAD to a given
-# commit. Note that it changes just the HEAD of the working tree, not
-# the branch it is corresponding to. It will return to the HEAD of
+# DESCRIPTION
+# -----------
+# Takes the target commit ID to seek to as an argument.
+# Seeking will bring the working tree from its current 'HEAD' to a given
+# commit. Note that it changes just the 'HEAD' of the working tree, not
+# the branch it is corresponding to. It will return to the 'HEAD' of
# the appropriate branch if passed no arguments.
#
# Therefore, for a quick excurse to the past of the 'master' branch:
#
-# cg-seek git-pasky-0.1
-# cg-diff this master # will do the correct thing
-# cg-seek # will restore what we had before
+# $ cg-seek git-pasky-0.1
+# $ cg-diff this master # will do the correct thing
+# $ cg-seek # will restore what we had before
#
-# For intuitiveness, specifying the branch name (cg-seek master) will do
+# For intuitiveness, specifying the branch name (`cg-seek master`) will do
# the right thing too. If you want to migrate your working tree to another
-# branch, use cg-fork.
+# branch, use `cg-fork`.
#
-# Takes the target commit ID.
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-seek <commit>"
. ${COGITO_LIB}cg-Xlib
Index: cg-status
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-status (mode:100755)
+++ uncommitted/cg-status (mode:100755)
@@ -3,7 +3,35 @@
# Show status of entries in your working tree.
# Copyright (c) Petr Baudis, 2005
#
-# Takes no arguments.
+# DESCRIPTION
+# -----------
+# Print of files in the working tree.
+#
+# The output has the following format:
+#
+# <status flag> <file>
+#
+# where '<status flag>' can be one of the following:
+#
+# `?`::
+# '<file>' is unknown.
+# `M`::
+# '<file>' has been touched or modified.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+#
+# FILES
+# -----
+# $GIT_DIR/exclude::
+# If the file exists it will be used to prune which files to
+# show status for. The format is similar to the `dontdiff` file;
+# each line contains a pattern for a file or group of files
+# to exclude.
+
+USAGE="cg-status"
. ${COGITO_LIB}cg-Xlib
Index: cg-tag
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-tag (mode:100755)
+++ uncommitted/cg-tag (mode:100755)
@@ -3,10 +3,19 @@
# Mark certain commit by a tag.
# Copyright (c) Petr Baudis, 2005
#
-# Creates a tag referencing the given commit (or HEAD). You can then
-# use the tag anywhere you specify a commit/tree ID.
+# DESCRIPTION
+# -----------
+# Creates a tag referencing the given commit (or 'HEAD'). You can then
+# use the tag anywhere you specify a commit or tree ID.
#
-# Takes the tag's name and optionally the associated ID.
+# Takes the tag name and optionally the associated ID as arguments.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-tag <tag> [<commit>]"
. ${COGITO_LIB}cg-Xlib
Index: cg-tag-ls
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-tag-ls (mode:100755)
+++ uncommitted/cg-tag-ls (mode:100755)
@@ -3,7 +3,16 @@
# List stored GIT tags.
# Copyright (c) Steve Hoelzer 2005
#
+# DESCRIPTION
+# -----------
# Takes no parameters.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-tag-ls"
. ${COGITO_LIB}cg-Xlib
Index: cg-update
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-update (mode:100755)
+++ uncommitted/cg-update (mode:100755)
@@ -1,9 +1,21 @@
#!/usr/bin/env bash
#
-# Pulls changes from another branch to the local repository and merge changes.
+# Pull and merge changes from a branch to the local repository.
# Copyright (c) Petr Baudis, 2005
#
-# Takes the branch' name, defaulting to "origin".
+# DESCRIPTION
+# -----------
+# Takes the branch name as an argument, defaulting to 'origin'.
+#
+# If local changes conflict with those of the branch updated from the
+# merge will be blocked.
+#
+# OPTIONS
+# -------
+# -h, --help::
+# Print usage help.
+
+USAGE="cg-update [<branch>]"
. ${COGITO_LIB}cg-Xlib
^ permalink raw reply [flat|nested] 5+ messages in thread