jsvn/README

Josh's SVN wrapper script

This wrapper script to Subversion supplements normal svn behavior by
adding additional functionality or modifying the output of the default
svn subcommands. Much of the functionality implemented here was inspired
by the way that git works.

It is recommended to put this script in your $PATH as 'jsvn' or something
other than 'svn' and to make an alias svn='jsvn'.
For example, this .bash_aliases stanza will check if 'jsvn' is in your
path and automatically alias 'svn' to it if so:
  if [[ "$(which jsvn 2>/dev/null)" != "" ]]; then
      alias svn='jsvn'
  fi

Implemented subcommands:
 add <file>...
  - add files as usual; add recursive contents of directories
 bisect <operation>
  operations:
   - init  initialize a new bisect operation
   - bad   mark the current revision as bad - containing the change sought
   - good  mark the current revision as good - older than the change sought
   - reset terminate the bisect operation and return to the original revision
 branch[es] [[-d] <branch_name>]
  - with no arguments, list branches with '*' by the current one
  - with -d, delete <branch>
  - otherwise, create a new branch from the current one
 tag[s] [[-d] <tag_name>] | [-m <old_tag_name> <new_tag_name>]
  - with no arguments, list tags
  - with -d, delete <tag>
  - with -m, rename <old_tag_name> to <new_tag_name>
  - otherwise, create a new tag from the current branch
 switch <short_name>
  - switch to 'trunk', branch name, or tag name without having to specify
    the full URL
  - falls back to Subversion "switch" if <short_name> doesn't exist
 merge <branch>
  - merge branch <branch> into the current WC path
  - falls back to Subversion "merge" if <branch> doesn't exist
 root
  - output root URL (for use on shell such as "svn log $(svn root)/tags")
 url
  - output repository URL of current working directory
 watch-lock
  - block until the lock on a file/URL is released
 users
  - show a list of contributing users to a SVN path
 binaries [--set-lock]
  - show a list of versioned binary files under the current path, with
    a prepended '*' for those with svn:needs-lock set
  - with --set-lock, set svn:needs-lock to '*' for binaries
 lockable [--remove] | [--status] <file[s]>
  - with no switches, set svn:needs-lock to '*' for file[s]
  - with --remove, remove svn:needs-lock' for file[s]
  - with --status, prepended '*' for those with svn:needs-lock set
 externals
  - print a list of the externals in the repository
 stash [command]
  - allow temporarily saving changes to the working copy without committing
  - the stashes behaves as a "stack" where "save" pushes a new stash object
    and "pop" pops the newest one from the top of the stack
  commands:
    save (default if not specified):
     - save changes as a "stash" object and revert them from working copy
     - this only works with text files, not binary files
    list:
     - show a list of all stash objects
    pop [id]:
     - apply the stash object <id> back to the working copy
     - the stash object is removed if it was successfully applied
     - <id> defaults to the newest stash object created
    show [id]:
     - display the diff stored in stash with ID <id>
     - <id> defaults to the newest stash object created
    drop [id]:
     - delete stash object <id>
     - <id> defaults to the newest stash object created

The following subcommands are executed using their native handler, but
have their output simplified and/or colorized:
 - diff
 - log
 - status
 - update

If the subcommand name begins with two leading underscores ("__"), the
underscores will be stripped and the command will be handled by native
Subversion without any jsvn processing.

Configuration:

jsvn will execute the files "~/.jsvn", and "$WCROOT/.svn/jsvn", in that
order, if they exist, as Python scripts for the user to locally configure
jsvn. Variables written to from within configuration scripts will be used
as configuration directives to control jsvn's execution. jsvn's default
settings or even user-specified settings can thus be overridden for a
particular working copy by creating a "$WCROOT/.svn/jsvn" script.

Available configuration variables:
  use_color: True or False to enable/disable colorization of svn output
  use_pager: True or False to enable/disable automatic piping of svn
             output to a pager program
  pager:     A string specifying the pager program (and args) to execute
  aliases['XXX']: A string or list defining the alias 'XXX'. A string
             can be used if the alias expands to a single argument. A
             list must be used to pass multiple arguments to svn.
             An arbitrary shell command can be specified by beginning the
             alias definition with a '!' character. In this case, the shell
             variable $0 will contain the subcommand specified by the user
             on the command line, and $1, $2, ... will contain any positional
             parameters specified on the command line.
  svn:       Specify the path to the native Subversion executable. If not
             specified, the first 'svn' in $PATH will be used.

Configuration Examples:
  pager = 'less -FRXi' # enable case-insensitive searching in less
  aliases['revert'] = ['revert', '-R'] # default to recursive reverts
  aliases['s'] = ['status', '--ignore-externals']
  aliases['status'] = '__status' # ignore jsvn processing of status command
  aliases['init'] = '!svnadmin create $1'

Author: Josh Holtrop

History:
  v1.2 - in progress
    - support working-copy-local jsvn configuration files
    - bugfix: pager setting in config file overrides $PAGER environment
      variable instead of other way around
  v1.1 - 2012-04-16
    - add stash subcommand
    - add bisect subcommand
    - add support for aliases expanding to arbitrary shell commands
    - bugfix: remove trailing blank lines on colorized output sent to pager
  v1.0 - 2012-03-22
    - functional release on github