cg-help

   1 #!/usr/bin/env bash
   2 #
   3 # Show help for Cogito commands
   4 # Copyright (c) Petr Baudis, 2005
   5 #
   6 # Takes an optional argument describing the command to show the help for.
   7 # The command can be specified either as 'COMMAND' or 'cg-COMMAND'.
   8 # If the argument is left out an overview of all the Cogito commands will
   9 # be shown.
  10 #
  11 # Note, short help for a command is also available by passing `--help` or
  12 # `-h` to the command. The complete command manual is shown when passing
  13 # `--long-help` (and is the same as doing "`cg-help command`").
  14 #
  15 # OPTIONS
  16 # -------
  17 # -c::  Colorize
  18 #       Colorize the output. You can customize the colors using the
  19 #       $CG_COLORS environment variable (see below).
  20 #
  21 # ENVIRONMENT VARIABLES
  22 # ---------------------
  23 # PAGER::
  24 #       The pager to display log information in, defaults to `less`.
  25 #
  26 # PAGER_FLAGS::
  27 #       Flags to pass to the pager.
  28 #
  29 # CG_COLORS::
  30 #       Colon-separated list of 'name=color' pairs, where name is
  31 #       one of helpcopy, helpusage, helpsection, helplitem, helpcgcmd,
  32 #       helpcode, helpempth, default, and value is an ECMA-48 SGR
  33 #       sequence (see e.g. console_codes(4)).
  34 #
  35 # CG_COLORS_AUTO::
  36 #       Even if -c was passed or specified in ~/.cgrc, if this option
  37 #       is set, use colors only when the output is a terminal and it
  38 #       supports colors.
  39 #
  40 # CG_LESS::
  41 #       This is what the $LESS environment variable value will be set
  42 #       to before invoking $PAGER. It defaults to $LESS concatenated
  43 #       with the `R` flag to allow displaying of colorized output.
  44 #
  45 # CONFIGURATION VARIABLES
  46 # -----------------------
  47 # The following GIT configuration file variables are recognized:
  48 #
  49 # help.usecolor::
  50 #       If enabled, colorify the output like with -c if the output
  51 #       is a terminal.
  52
  53 # Testsuite: TODO
  54
  55 USAGE="cg-help [-c] [cg-COMMAND | COMMAND]"
  56 _git_repo_unneeded=1
  57
  58 . "${COGITO_LIB}"cg-Xlib || exit 1
  59
  60 setup_colors()
  61 {
  62         local C="helpcopy=34:helpusage=33"
  63         C="$C:helpsection=35:helplitem=33"
  64         C="$C:helpcgcmd=32:helpcode=36"
  65         C="$C:helpempth=31"
  66         C="$C:default=0"
  67         colorify_setup "$C"
  68
  69         apply_colors="
  70         s/^\(-.*\)::.*/$colhelplitem\1$coldefault:/
  71         s/^\(.*\)::/$colhelplitem\1$coldefault:/
  72         s/\`\(cg-[a-z-]*\)\`/$colhelpcgcmd\1$coldefault/g
  73         s/\`\([^\`]*\)\`/$colhelpcode&$coldefault/g
  74         s/[^A-Z0-9a-z_-]\$ .*/$colhelpcode&$coldefault/g
  75         s/'\([^ ]*\)'/$colhelpemph&$coldefault/g
  76         s/'\(-[A-Z0-9a-z_-]* [^']*\)'/$colhelpemph&$coldefault/g
  77         s/^Usage: .*/$colhelpusage&$coldefault/
  78         /^[A-Z -_]*/,/^---*$/s/^[A-Z -_]*\$/$colhelpsection&$coldefault/
  79         s/^Copyright .*/$colhelpcopy&$coldefault/
  80         "
  81 }
  82
  83 print_command_listing()
  84 {
  85         width="$(IFS=$'\n'; echo "$*" | column_width "$bin_path/" 25)"
  86         for command in "$@"; do
  87                 [ -f "$command" ] || continue
  88                 if [ -L "$command" ]; then
  89                         tg="$(readlink "$command")"
  90                         # Skip symlinks within the same directory, those are
  91                         # aliases; symlinks to elsewhere are permitted since
  92                         # they may be created by some weirder packaging sys.
  93                         [ z"${tg#*/}" != z"$tg" ] || continue
  94                 fi
  95                 cmdname="${command#$bin_path/}"
  96
  97                 shortdesc="$(sed -n 'n;n;p;q' <"$command")"
  98                 # Some minimal sanity check that we didn't pick up some
  99                 # random binary named cg-*
 100                 [ "${shortdesc:0:1}" = "#" ] || continue
 101                 columns_print '' t- "$cmdname" $width "  ${shortdesc:2}"
 102         done
 103 }
 104
 105 colorize() {
 106         sed -e "$apply_colors" | pager
 107 }
 108
 109
 110 colors=
 111 apply_colors=
 112 while optparse; do
 113         if optparse -c; then
 114                 colors=1
 115         else
 116                 optfail
 117         fi
 118 done
 119
 120 colorify_detect "$colors" help && setup_colors
 121 bin_path="$(dirname "$0")"
 122
 123
 124 if [ "$ARGS" = "admin" ]; then
 125         echo "The advanced (low-level, dangerous, or administrative) commands:"
 126         IFS=$'\n' print_command_listing $(ls "$bin_path"/cg-admin*)
 127         exit
 128 elif [ "$ARGS" = "branch" ]; then
 129         echo "The branch commands family:"
 130         IFS=$'\n' print_command_listing $(ls "$bin_path"/cg-branch*)
 131         exit
 132 elif [ "$ARGS" = "tag" ]; then
 133         echo "The tag commands family:"
 134         IFS=$'\n' print_command_listing $(ls "$bin_path"/cg-tag*)
 135         exit
 136 elif [ "$ARGS" ]; then
 137         cmd="$(echo "${ARGS[0]}" | sed 's/^cg-//')"
 138         print_help long "$cmd" | colorize
 139         [ "${PIPESTATUS[0]}" -eq 0 ] && exit
 140         echo "cg-help: no help available for command \"${ARGS[0]}\""
 141         echo "Call cg-help without any arguments for the list of available commands"
 142         exit 1
 143 fi
 144
 145
 146 REGULAR_COMMANDS="$(ls "$bin_path"/cg-* | grep -v /cg-X | grep -v /cg-admin | grep -v /cg-branch | grep -v /cg-tag)"
 147 # TODO: Some uberevil `column` tricks...
 148 BRANCH_COMMANDS="$(ls "$bin_path"/cg-branch* | sed 's#.*/##' | tr '\n' ' ')"
 149 TAG_COMMANDS="$(ls "$bin_path"/cg-tag* | sed 's#.*/##' | tr '\n' ' ')"
 150 ADVANCED_COMMANDS="$(ls "$bin_path"/cg-admin-* | sed 's#.*/##' | tr '\n' ' ')"
 151
 152 IFS=$'\n' colorize <<__END__
 153 The Cogito version control system  $(cg-version)
 154
 155 Available regular commands:
 156 $(print_command_listing $REGULAR_COMMANDS)
 157
 158 Special command families:
 159         cg-help admin   ($ADVANCED_COMMANDS\b)
 160         cg-help branch  ($BRANCH_COMMANDS\b)
 161         cg-help tag     ($TAG_COMMANDS\b)
 162
 163 These expressions can be used interchangeably as "ID"s:
 164         empty string, "this" or "HEAD" (current HEAD)
 165         branch name (as registered with cg-branch-add)
 166         tag name (as registered with cg-tag)
 167         date string (as recognized by the date tool)
 168         shortcut hash (shorted unambiguous hash lead)
 169         commit object hash (as returned by cg-object-id -c)
 170         tree object hash (accepted only by some commands)
 171
 172 For details on individual commands, do e.g.:
 173         cg-help cg-log
 174         cg-log --long-help
 175 (both variants are equivalent)
 176 __END__