for Shelving and Checkpointing

References:

  1. Shelving and Checkpointing Dev

  2. Shelve-Checkpoint Side Issues

Role Models

 

git stash *

hg shelve *

bzr shelve *

p4 shelve *

store

store & revert

stash [save]

shelve

shelve

shelve

naming

"stash@{N}"

[--name NAME] (default based on bookmark/branch)

shelf id number N

changelist number N

message

stash save MESSAGE

--message

--message

(no default)

yes (GUI)

patch hunks

-p

--interactive

(yes; default)

(no?)

interactive

(when using -p)

--interactive

(default; [--all] for non-interactive)

 

unversioned

--include-untracked

--unknown

--addremove

(no)

(no?)

retrieve

apply & remove

stash pop [NAME]

unshelve [NAME]

unshelve [N] [--apply]

unshelve -s N

apply & keep

stash apply [NAME]

unshelve --keep [NAME]

unshelve --keep [N]

(n/a?)

show diff

stash show -p [NAME]

shelve --patch [NAME]

unshelve --preview [N]

diff2 @=N

other

list

stash list

(name msg base)

shelve --list

(name age msg)

shelve --list

(name msg)

changes -s shelved ...

drop

stash drop [NAME]

stash clean

shelve --delete NAME

shelve --cleanup

unshelve --delete-only [N]

shelve -d -c...

access in other cmds

stash@{N}

  

@=N

* The column headings are linked to their documentation

Shelving with Checkpointing

Based mainly on Mercurial (hg shelve) syntax, which seems the best fit for Subversion.

(For Shelving v1, see Shelving v1 CLI.)

 

svn checkpointing

notes

store

store

checkpoint save NAME [PATH...]

v1: doesn't detect if same as previous checkpoint

like 'shelve' but without reverting

naming

NAME-NNN.patch

in shelves dir

log message

-m "message"

default: keep the existing message for NAME, if any

retrieve

restore newest version

checkpoint restore NAME

Apply latest version to the working copy

restore version N

checkpoint restore NAME [N]

unshelve NAME [N]

Apply version N to the working copy

other

aliases

checkpoint

savepoint | sp

changeset | cs (maybe?)

list

checkpoint list|--list NAME

List checkpoints of NAME

svn checkpoint save NAME [PATH...]

  • if WC is unmodified, do nothing

  • find latest version of checkpoint series: NAME-VERSION.patch

  • N=(VERSION+1)

  • store WC modifications as NAME-N.patch

  • store value N in file 'NAME.current'

  • WC state remains unchanged

  • print "saved 'NAME' version N"

svn unshelve NAME [N]

svn checkpoint restore NAME [N]

  • if WC is modified:

    • # warn? abort? first save a new checkpoint to allow undoing?

  • update the WC working state to the current [or given] checkpoint

  • set the 'current' checkpoint to N

  • discard any checkpoints newer than N

  • print "reverted|restored|rolled back|rolled forward to checkpoint N", N='current'

Extensions to consider

  • add a [--wc-root] to select the WC root path (for shelving and all WC commands)

  • give 'svn diff', 'svn log' etc. a syntax to view shelved changes

  • use the saved log message when committing

  • Operate like an undo/redo stack: after any batch of undo/redo, the next change discards all the pending redo steps. In other words, after rollback, user may then roll forward if later checkpoints not yet discarded.

  • On commit: remove all related checkpoints?

Shelving Integrated with Changelists

Additional behaviour:

svn cl NAME PATH...

  • (the existing command adds PATHs to a new or existing changelist)

  • fail if NAME is already a shelved change

shelve [--cl NAME]...

  • "--cl" as a synonym for "--name"; can specify multiple changelists

  • save a patch for each [named] changelist separately

  • for paths in no changelist, use a special name ("shelved"?)

  • the shelved patch also records unmodified files whose paths are in the changelist

unshelve

  • if NAME is already a changelist, fail

  • convert to a changelist

  • with [--keep],

    • can we keep the same name as both shelved and changelist?

    • or keep a copy with a new name instead?

  • if shelved paths overlap with another changelist's paths:

    • # warn? abort? merge? give them which changelist name?

 


Julian Foad, Assembla, 2017

  • No labels