A rational svn shelve/checkpoint CLI

Towards a more rational shelving-with-checkpoints CLI.

   svn shelf-{save,shelve,unshelve,shelves,log,drop,diff}
     [SHELF_SPEC...] [PATH...]

SHELF_SPEC:

   --shelf=[SHELF][.VERSION]
   @[SHELF][.VERSION]

     Specify shelf SHELF (name, 'all', 'newest'), version VERSION
     (number, date, 'all', 'newest'). Defaults are per command.

   --version=VERSION

     Specify the default version for shelf specs in the command.

Aliases:

   svn save -> svn shelf-save
   svn shelve -> svn shelf-shelve
   svn unshelve -> svn shelf-unshelve
   svn shelves -> svn shelf-shelves

Main commands:

   svn save | shelf-save [@SHELF] [PATH...] # save only
   svn shelve | shelf-shelve [@SHELF] [PATH...] # save & revert

     defaults: SHELF:newest; PATH:'.'
     Save/Shelve to shelf SHELF the changes within a PATH.

   svn unshelve | shelf-unshelve [@[SHELF][.VERSION]...] [PATH...]

     defaults: SHELF:newest; VERSION:newest; PATH:'.'
     Unshelve each shelf-version SHELF.VERSION
     just the paths within PATH...
     (Warn if that omits other paths in the shelf-version.)

Ancillary commands:

   svn shelves | shelf-shelves [@SHELF...] [PATH...]

     defaults: SHELF:all; PATH:'.'
     List each shelf SHELF that has changes within a PATH.
     Same as 'shelf-log --version=newest ...'.

   svn shelf-log [@[SHELF][.VERSION]...] [PATH...]

     defaults: SHELF:newest; VERSION:all; PATH:'.'
     List each version in a shelf SHELF that has changes inside a PATH.

   svn shelf-drop [@SHELF...]

     defaults: SHELF:newest
     Delete each shelf SHELF.

   svn shelf-diff [@[SHELF][.VERSION]...] [PATH...]

     defaults: SHELF:newest; VERSION:newest; PATH:'.'
     Print a diff of the changes inside PATH... in each shelf-version.
     (Note: not the difference between two shelves or versions.)

Thoughts:

The use of a distinctive shelf specifier is intended to avoid the
ambiguity in the first optional argument to a syntax like "svn shelve
[NAME] [PATH...]". There are some other possible ways to resolve the
ambiguity, such as interpreting the first optional argument as NAME
unless it contains a '/' or '\' (if we don't allow '/' or '\' in NAME).

Using one-word subcommands like "shelf-drop" rather than "shelf drop" or
"shelf --delete" is intended to be better for consistency, for the help
system, and for extending existing scripting that assumes one-word
subcommands (the bash-completion script is one example). But note the
ugly repetition in "shelf-shelve", "shelve-unshelve", and "shelf-shelves".

A common syntax for referring to a particular shelved change is helpful.
"--shelf=" is OK for a start but the repetition of "shelf" here after
the subcommand name is ugly again, hence suggestion of "@" instead,
although using "@" to introduce the name rather than the version is
inconsistent with peg revision specifiers.

Perhaps we can take this further and achieve a syntax like "svn log
--shelf=NAME" and "svn diff --shelf=NAME[@VERSION]" in which a
shelf-spec is used with a regular existing subcommand, eliminating the
repetition in those commands. Then 'svn shelve' and 'unshelve' and
'shelves' become primary subcommands, but they still need a shelf specifier.

- Julian
Received on 2018-01-08 14:31:10 CET