A summary of the Shelving and Checkpointing feature in Svn-1.11, building on the initial Shelving-v1 in Svn-1.10.
(For other pages about Shelving and Checkpointing, see Shelving and Checkpointing.)
It adds support for making checkpoints and rolling back to an earlier checkpoint (issue SVN-3626).
The implementation is no longer based on patch files. Instead, the base and working version of each file are stored when shelving. To apply the changes, 3-way merge is used for text files, and theirs-or-mine-or-conflict logic for binary files, similar to the way "svn merge" works.
The kinds of change that can be shelved and unshelved are detailed below.
Shelve and Unshelve
A shelf is created from WC changes based on a particular repository, branch and revision, but is not tied to those details. It is intended that a shelf can be unshelved (applied) on to any WC target that is similar to the original base, be it another branch, another revision, or (future possibility) another repository, similar to how patch files can be used.
Shelves are stored in the metadata area of a working copy, and used within that WC.
- to unshelve into a different revision: 'update' the WC to the new revision, then unshelve
- to unshelve into a different branch: 'switch' the WC to the new branch, then unshelve
- FUTURE: move a shelf to a different WC
- FUTURE: specify a different target WC when shelving/unshelving
- FUTURE: store shelves in a central location, such as user's home directory
Save a Checkpoint and Restore (Roll Back) to a Checkpoint
Checkpoints are supported by saving multiple versions of a shelf.
|Save a checkpoint|
copy the local changes into a new version of shelf 'foo'
doesn't revert the changes from the WC
move the local changes into a new version of shelf 'foo'
and revert the changes from the WC
|Restore / roll back|
unshelve version 3 of shelf 'foo'
and delete any newer versions
|list all the versions of shelf 'foo'|
|show version 3 as a diff|
Kinds of change that can be shelved
WC State or Change
|Shelving (in development)||Planned|
file text, file delete/add, most properties
copies and moves
binary files & properties
unversioned items (git stash -u/-a)
inconsistent WC states (missing/obstructed)
WC base state (rev, URL, switched, depth)
Conflicts and Error Handling
When 'svn shelve' encounters any unshelvable WC state in the specified paths:
- error out, refusing to shelve any changes
- error message gives some details of why it failed
When 'svn unshelve' hits a path that already has a local modification:
- error out; the error message gives some details of why it failed
- the shelf is not changed
- the WC is not changed
- with 'svn unshelve --force' option: bypass this check
(Why not unshelve with local modifications, by default? In the main use cases for unshelving, we expect that the user has a clean working copy. If the relevant files in the WC are not 'clean', it may be the user has made a mistake. And after we merge some shelved changes into the local modifications, if the user does not like the result, it is not possible to 'undo' the merge, in general. In some cases a reverse-merge may work but in general merging is not an automatically reversible process. But if the user is being careful, and deliberately wants to merge the shelved change with some local changes, we should make it possible to do this, so we have a 'force' option.)
When 'svn unshelve' hits a path that has different content from the base of the shelved change (for example, if the WC is switched to a different branch or updated to a different revision), it tries to merge:
- for text file content: 3-way merge
- for binary file content (as determined by 'svn:mime-type' property): theirs-or-mine-or-conflict
- properties: theirs-or-mine-or-conflict for each property
When 'unshelve' hits a conflict in merging file or properties:
- raise a conflict state in the WC for that path, just like 'merge' does.
- library functions implemented in libsvn_client
- not yet exposed through bindings (SWIG, JavaHL, etc.)
Client-level support (user interfaces):
- 'svn' command-line UI
- TortoiseSVN (for Windows)
- Cornerstone (for Mac)
Shelves are stored in WC metadata dir '.svn/shelves/'.