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
