README

@@ -1,10 +1,9 @@
 Josh's SVN wrapper script
-https://github.com/holtrop/jsvn
 
 This wrapper script to Subversion supplements normal svn behavior by
 adding additional functionality or modifying the output of the default
-svn subcommands (simplification and colorization). Much of the functionality
+svn subcommands. Much of the functionality implemented here was inspired
-implemented here was inspired by the way that git works.
+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'.
@@ -17,113 +16,47 @@ path and automatically alias 'svn' to it if so:
 Implemented subcommands:
  add <file>...
   - add files as usual; add recursive contents of directories
- binaries [--set-lock]
+ branch[es] [[-d] <branch_name>]
-  - show a list of versioned binary files under the current path, with
+  - with no arguments, list branches with '*' by the current one
-    a prepended '*' for those with svn:needs-lock set
+  - with -d, delete <branch>
-  - with --set-lock, set svn:needs-lock to '*' for binaries
+  - otherwise, create a new branch from the current one
- bisect <operation>
+ tag[s] [[-d] <tag_name>] | [-m <old_tag_name> <new_tag_name>]
-  operations:
+  - with no arguments, list tags
-   - init  initialize a new bisect operation
+  - with -d, delete <tag>
-   - bad   mark the current revision as bad - containing the change sought
+  - with -m, rename <old_tag_name> to <new_tag_name>
-   - good  mark the current revision as good - older than the change sought
+  - otherwise, create a new tag from the current branch
-   - reset terminate the bisect operation and return to the original revision
- branch[es]
-  - branch: list branches with '*' by the current one
-  - branch -d name: delete branch <name>
-  - branch [-s] name [source[@rev]]: create branch <name>
-    - if <source> is given it is resolved as a reference name (can be 'trunk',
-      or a tag or branch name)
-    - if <source> is not given the HEAD of the current working-copy URL is used.
-    - also switch to the new branch if -s is given
- checkout [options] [url] [wc_path]
-  - if a URL is given that ends with /trunk and no working copy path is given,
-    then the last directory component before "/trunk" is used as the working
-    copy path
- clean [-x] {-n|-f} [path...]
-  - remove (or list) unversioned items
-  options:
-    -x, --ignore-ignores
-      - remove/list unversioned items that are ignored by Subversion
-    -n, --dry-run
-      - perform a dry-run, i.e. list files that would be removed but do not
-        actually remove them
-    -f, --force
-      - perform the actual removal of unversioned files
- commit
-  - removes trailing whitespace (including end-of-line characters) from commit
-    messages before committing if neither -m nor -F arguments are given
- diff
-  - allow specifying ref1..ref2 syntax to show the diff between two references
-    - references can be tag names, branch names, or 'trunk'
-  - allow specifying ref1...ref2 syntax to show the diff between the common
-    ancestor of ref1 and ref2 and ref2's HEAD
- externals
-  - print a list of the externals in the repository
- 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
- log
-  - allow specifying ref1..ref2 syntax to show the log entries for
-    ref2 which are not a part of ref1
- merge <branch>
-  - merge branch <branch> into the current WC path
-  - falls back to Subversion "merge" if <branch> doesn't exist
- revert <path[s]>
-  - revert all affected files under given target path(s)
- root
-  - output root URL (for use on shell such as "svn log $(svn root)/tags")
- stash [options] [file...]
-  - allow temporarily saving changes to the working copy without committing
-  - the stashes behaves as a "stack" where stashing pushes a new stash object
-    and popping removes the newest one from the top of the stack
-  - binary files are ignored (a warning is printed) and not stashed
-  options:
-    -e, --externals
-      - also stash changes in externals (if no explicit targets given)
-      - this option is implicitly on if the configuration value
-        'stash_externals' is set to True
-    --noexternals
-      - reverse --externals (or the configuration value 'stash_externals')
-    -k, --keep
-      - create the stash object, but keep the changes locally as well
-      - with --pop, do not remove the stash object after reapplying it
-    -p, --patch
-      - interactively prompt for whether to stash each hunk
-    --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 unless -k (keep) given
-      - <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
-    - if none of --list, --pop, --show, or --drop is given, a new stash object
-      is created containing the chosen differences
-    - if file is given, only the changes from the listed files will be stashed
  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
- tag[s]
+ merge <branch>
-  - tag [-v]: list tags
+  - merge branch <branch> into the current WC path
-    - with -v (verbose), lists tag origin and creation date
+  - falls back to Subversion "merge" if <branch> doesn't exist
-  - tag -d name: delete tag <name>
+ root
-  - tag -m old new: rename tag <old> to <new>
+  - output root URL (for use on shell such as "svn log $(svn root)/tags")
-  - tag name [source[@rev]]: create tag <name>
+ url
-    - if <source> is given it is resolved as a reference name (can be 'trunk',
+  - output repository URL of current working directory
-      or another tag or a branch name)
-    - if <source> is not given the HEAD of the current working-copy URL is used.
- url [file]
-  - output repository URL of file [default: '.' (current working directory)]
- users
-  - show a list of contributing users to a SVN path
  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
+
+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
@@ -131,14 +64,9 @@ Subversion without any jsvn processing.
 
 Configuration:
 
-jsvn will execute the files "~/.jsvn", and "$WCROOT/.svn/jsvn", in that
+jsvn will execute the file ~/.jsvn, if it exists, as a Python script.
-order, if they exist, as Python scripts for the user to locally configure
+Variables written to will be used as configuration directives.
-jsvn. Variables written to from within configuration scripts will be used
+Available configuration directives:
-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
@@ -146,89 +74,14 @@ Available configuration variables:
   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.
-             Starting with jsvn v1.2, user configuration scripts may define
-             python functions to be used as aliases. The execution
-             environment for these user-defined functions is limited but
-             does provide the following symbols:
-              - Popen, PIPE: passed from the subprocess module for arbitrary
-                command execution
-              - do(cmd, expand=True): the do() function allows the alias
-                function to execute a command within jsvn. 'cmd' should be
-                either a string if the command has no arguments, or a list
-                containing the command and all arguments. 'expand' is a
-                boolean flag determining whether user-defined aliases should
-                be used to expand the command. If an alias function invokes
-                do() with the same command that the alias function itself is
-                bound to, and expand is not set to False, then the alias
-                function will be called recursively!
-  svn:       Specify the path to the native Subversion executable. If not
-             specified, the first 'svn' in $PATH will be used.
-  ignore_executable_extensions: A list of extensions (including the '.')
-             for newly added files which should not automatically have the
-             svn:executable property added for them even if the files are
-             executable. The default value is ['.c', '.cc', '.h', '.txt'].
-  ignore_symlinks: True or False to hide unversioned symlinks from appearing
-             in status output (default: False)
-  stash_externals: True or False to enable/disable whether '-e' is implicitly
-             on for 'stash' subcommand. Defaults to False.
 
 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'
-  def up_and_ctags(args):
-      do(args, expand=False) # do the actual update command
-      Popen(['ctags', '-R']).wait()
-  aliases['up'] = up_and_ctags
 
 Author: Josh Holtrop
 
 History:
-  v1.7 - 2013-08-16
+  v1.0 - functional release on github
-    - add "clean" subcommand handler
-    - bugfix: revert subcommand handler: revert deleted items
-  v1.6 - 2013-07-24
-    - rework 'stash' subcommand to operate on individual hunks
-    - add 'revert' subcommand handler
-  v1.5 - 2012-11-08
-    - add -v (verbose) flag to 'tag' subcommand
-    - allow optional source argument to 'branch' subcommand
-    - remove repository prefix URL from diff --summarize output
-    - Add .exe extension to svn binary name if platform is Windows (not cygwin)
-  v1.4 - 2012-08-23
-    - allow optional source/revision argument when creating a tag
-    - handle ctrl+c better when interacting with a pager
-    - add configurable functionality to work around svn automatically adding svn:executable property
-    - bugfix for diff "..." range syntax to show correct diff
-    - improved performance for diff/log "..." syntax
-    - minor stash show bugfix
-  v1.3 - 2012-06-27
-    - colorize diff --summarize output
-    - log: support ref1..ref2 syntax for showing ref2 history not in ref1
-    - diff: support ref1..ref2 syntax for diffing branches/tags
-    - diff: support ref1...ref2 syntax for diffing from common ancestor
-    - branch: add -s option to immediately switch to newly-created branch
-    - bugfix: branch: throw error when creating a branch that already exists
-    - stash save: add -k option to keep the working copy intact
-    - stash pop: add -k option to keep the stash after applying it
-    - url subcommand can take an optional path argument to operate on
-    - various minor tweaks and improvements
-  v1.2 - 2012-05-11
-    - support working-copy-local jsvn configuration files ($WCROOT/.svn/jsvn)
-    - support python functions as user-implemented aliases
-    - 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