Documentation/make-cogito-asciidoc

   1 #!/usr/bin/env bash
   2 #
   3 # Generate a quick reference asciidoc manpage for the Cogito.
   4 # Copyright (c) Jonas Fonseca, 2005
   5
   6 REGULAR_COMMANDS="$(ls ../cg-* | grep -v cg-admin- | grep -v cg-X)"
   7 ADVANCED_COMMANDS="$(ls ../cg-admin-*)"
   8 HELPER_COMMANDS="$(ls ../cg-X*)"
   9
  10 # Shorthand for the link markup.
  11 man()
  12 {
  13         section="$1"
  14         command="$2"
  15         echo "gitlink:$command[$section]"
  16 }
  17
  18 # Print description list entry.
  19 print_command_info()
  20 {
  21         command="$1"
  22         caption=$(sed -n '3s/^# *//p' < "$command")
  23         cmdname=$(basename $command)
  24
  25         echo
  26         case "$cmdname" in
  27         cg-X*)
  28                 echo "$cmdname::"
  29                 ;;
  30         cg-*)
  31                 usage=$(sed -n '/^USAGE=/,0s/.*"cg-[^ ]*\(.*\)"/\1/p' < $command)
  32                 echo "$(man 1 "$cmdname") $usage::"
  33                 ;;
  34         esac
  35         echo "  $caption"
  36 }
  37
  38 print_command_listing()
  39 {
  40         for command in "$@"; do
  41                 print_command_info "$command"
  42         done
  43 }
  44
  45
  46 cat <<__END__
  47 cogito(7)
  48 =========
  49
  50 NAME
  51 ----
  52 cogito - version control system
  53
  54 SYNOPSIS
  55 --------
  56 cg-COMMAND <arg>...
  57
  58 DESCRIPTION
  59 -----------
  60
  61 'Cogito' is a version control system layered on top of the git tree history
  62 storage system. Amongst some of the noteworthy features, 'Cogito' has support
  63 for branching, tagging and multiple backends for distributing repositories
  64 (local files, rsync, HTTP, ssh).
  65
  66 'Cogito' is implemented as a series of 'bash(1)' scripts on top of $(man 7 git)
  67 (a content-tracking filesystem) with the goal of providing an interface for
  68 working with the 'GIT' database in a manner similar to other SCM tools (like
  69 'CVS', 'BitKeeper' or 'Monotone').
  70
  71 Commands Overview
  72 -----------------
  73
  74 The 'Cogito' commands can be split into regular commands and advanced commands.
  75 The regular commands are those used for normal interacting with the repository,
  76 while the advanced commands can be used for administrating the repository and
  77 should to some degree be regarded as low-level and in some cases dangerous.
  78
  79 Below an overview of the available commands are listed. For details on
  80 individual commands, do e.g.
  81
  82         cg-help cg-log
  83
  84 or
  85
  86         cg-log --long-help
  87
  88 You can find the quick overview of the most useful commands and concepts in
  89 $(man 7 cg-ref).
  90
  91 Regular commands
  92 ~~~~~~~~~~~~~~~~
  93
  94 $(print_command_listing $REGULAR_COMMANDS)
  95
  96 Advanced commands
  97 ~~~~~~~~~~~~~~~~~
  98
  99 $(print_command_listing $ADVANCED_COMMANDS)
 100
 101 Helper commands
 102 ~~~~~~~~~~~~~~~
 103
 104 There are a few helper commands that are not meant to be used from the command
 105 line. They provide a library of generic functions used by many of the real
 106 'Cogito' commands. You can safely ignore them, unless you want to contribute to
 107 'Cogito' development.
 108
 109 $(print_command_listing $HELPER_COMMANDS)
 110
 111 Command Identifiers
 112 -------------------
 113 BRANCH_NAME::
 114         Indicates a branch name added with the $(man 1 cg-branch-add) or
 115         $(man 1 cg-switch) commands.
 116
 117 COMMAND::
 118         Indicates a 'Cogito' command. The \`cg-\` prefix is optional.
 119
 120 LOCATION::
 121         Indicates a local file path or a URI. See $(man 1 cg-branch-add) for a
 122         list of supported URI schemes.
 123
 124 COMMIT_ID, FROM_ID, TO_ID, BASE_COMMIT::
 125         Indicates an ID resolving to a commit. The following expressions can
 126         be used interchangeably as IDs:
 127         - empty string, 'this' or 'HEAD' (current HEAD)
 128         - branch name (as registered with $(man 1 cg-branch-add))
 129         - tag name (as registered with $(man 1 cg-tag))
 130         - date string (as recognized by the 'date' tool)
 131         - shortcut object hash (shorted unambiguous hash lead)
 132         - commit object hash (as returned by 'cg-object-id -c')
 133         - tree object hash (as returned by 'cg-object-id -t')
 134
 135 TAG_NAME::
 136         Indicates a free form tag name.
 137
 138 OBJECT_TYPE::
 139         Indicates a git object type i.e.: 'blob', 'commit', 'tree' or 'tag'.
 140
 141 USERNAME::
 142         Indicates a free form user name.
 143
 144 FILE::
 145         Indicates an already existing filename - always relative to the root
 146         of the repository.
 147
 148 FILES
 149 -----
 150 ~/.cgrc::
 151         This file is read on startup if \`stdout\` is a terminal and may
 152         contain information about default command line options. Each line
 153         consists of a command name and a list of options. Lines not
 154         starting with a 'Cogito' command name are ignored. To have
 155         \`cg-log\` and \`cg-diff\` colorize the output put the following
 156         in ~/.cgrc:
 157
 158                 log -c
 159                 diff -c
 160
 161         You can prevent Cogito from reading ~/.cgrc by setting the
 162         CG_NORC environment variable.
 163
 164 COPYRIGHT
 165 ---------
 166 Copyright (C) Petr Baudis, 2005.
 167
 168 SEE ALSO
 169 --------
 170 Cogito is based on gitlink:git[7]. A quick Cogito reference sheet is in
 171 gitlink:cg-ref[7]. Cogito homepage is at http://git.or.cz/cogito[].
 172 __END__