#!/usr/bin/env bash
#
# Generate a quick reference asciidoc manpage for the Cogito.
# Copyright (c) Jonas Fonseca, 2005

REGULAR_COMMANDS="$(ls ../cg-* | grep -v cg-admin- | grep -v cg-X)"
ADVANCED_COMMANDS="$(ls ../cg-admin-*)"
HELPER_COMMANDS="$(ls ../cg-X*)"

# Shorthand for the link markup.
man()
{
	section="$1"
	command="$2"
	echo "gitlink:$command[$section]"
}

# Print description list entry.
print_command_info()
{
	command="$1"
	caption=$(sed -n '3s/^# *//p' < "$command")
	cmdname=$(basename $command)

	echo
	case "$cmdname" in
	cg-X*)
		echo "$cmdname::"
		;;
	cg-*)
		usage=$(sed -n '/^USAGE=/,0s/.*"cg-[^ ]*\(.*\)"/\1/p' < $command)
		echo "gitlink:$cmdname[] $usage::"
		;;
	esac
	echo "	$caption"
}

print_command_listing()
{
	for command in "$@"; do
		print_command_info "$command"
	done
}


cat <<__END__
cogito(7)
=========

NAME
----
cogito - version control system

SYNOPSIS
--------
cg-COMMAND <arg>...

DESCRIPTION
-----------

'Cogito' is a version control system layered on top of the git tree history
storage system. 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 $(man 7 git)
(a content-tracking filesystem) 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 --long-help

You can find the quick overview of the most useful commands and concepts in
$(man 7 cg-ref).

Regular commands
~~~~~~~~~~~~~~~~

$(print_command_listing $REGULAR_COMMANDS)

Advanced commands
~~~~~~~~~~~~~~~~~

$(print_command_listing $ADVANCED_COMMANDS)

Helper commands
~~~~~~~~~~~~~~~

There are a few helper commands that are not meant to be used from the command
line. They provide a library of generic functions used by many of the real
'Cogito' commands. You can safely ignore them, unless you want to contribute to
'Cogito' development.

$(print_command_listing $HELPER_COMMANDS)

Command Identifiers
-------------------
BRANCH_NAME::
	Indicates a branch name added with the $(man 1 cg-branch-add) or
	$(man 1 cg-switch) commands.

COMMAND::
	Indicates a 'Cogito' command. The \`cg-\` prefix is optional.

LOCATION::
	Indicates a local file path or a URI. See $(man 1 cg-branch-add) for a
	list of supported URI schemes.

COMMIT_ID, FROM_ID, TO_ID, BASE_COMMIT::
	Indicates an ID resolving to a commit. The following expressions can
	be used interchangeably as IDs:
	- empty string, 'this' or 'HEAD' (current HEAD)
	- branch name (as registered with $(man 1 cg-branch-add))
	- tag name (as registered with $(man 1 cg-tag))
	- date string (as recognized by the 'date' tool)
	- shortcut object hash (shorted unambiguous hash lead)
	- commit object hash (as returned by 'cg-object-id -c')
	- tree object hash (as returned by 'cg-object-id -t')

TAG_NAME::
	Indicates a free form tag name.

OBJECT_TYPE::
	Indicates a git object type i.e.: 'blob', 'commit', 'tree' or 'tag'.

USERNAME::
	Indicates a free form user name.

FILE::
	Indicates an already existing filename - always relative to the root
	of the repository.

FILES
-----
~/.cgrc::
	This file is read on startup if \`stdout\` is a terminal and may
	contain information about default command line options. Each line
	consists of a command name and a list of options. Lines not
	starting with a 'Cogito' command name are ignored. To have
	\`cg-log\` and \`cg-diff\` colorize the output put the following
	in ~/.cgrc:

		log -c
		diff -c

	You can prevent Cogito from reading ~/.cgrc by setting the
	CG_NORC environment variable.

COPYRIGHT
---------
Copyright (C) Petr Baudis, 2005.

SEE ALSO
--------
Cogito is based on gitlink:git[7]. A quick Cogito reference sheet is in
gitlink:cg-ref[7].
__END__