|A summary of the experimental 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.)
This version of shelving (issue SVN-3625) builds on the initial Shelving-v1 in Svn-1.10.
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.
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.
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|
Main commands: x-shelf-drop (shelf-drop) # delete a shelf x-shelf-list (shelf-list, shelves) # list all shelves x-shelf-log (shelf-log) # list the versions of a shelf x-shelf-save (shelf-save) # save, don't revert x-shelve (shelve) # save and revert x-unshelve (unshelve) # unshelve or restore Commands under development: x-shelf-diff (shelf-diff) x-shelf-list-by-paths (shelf-list-by-paths)
x-shelve (shelve): Move local changes onto a shelf. usage: x-shelve [--keep-local] SHELF [PATH...] Save the local changes in the given PATHs to a new or existing SHELF. Revert those changes from the WC unless '--keep-local' is given. The shelf's log message can be set with -m, -F, etc. 'svn shelve --keep-local' is the same as 'svn shelf-save'. The kinds of change you can shelve are committable changes to files and properties, except the following kinds which are not yet supported: * copies and moves * mkdir and rmdir Uncommittable states such as conflicts, unversioned and missing cannot be shelved. To bring back shelved changes, use 'svn unshelve SHELF'. Shelves are stored in <WC>/.svn/shelves/
x-unshelve (unshelve): Copy shelved changes back into the WC. usage: x-unshelve [--drop] [SHELF [VERSION]] Apply the changes stored in SHELF to the working copy. SHELF defaults to the newest shelf. Apply the newest version of the shelf, by default. If VERSION is specified, apply that version and discard all versions newer than that. In any case, retain the unshelved version and versions older than that (unless --drop is specified). With --drop, delete the entire shelf (like 'svn shelf-drop') after successfully unshelving with no conflicts. The working files involved should be in a clean, unmodified state before using this command. To roll back to an older version of the shelf, first ensure any current working changes are removed, such as by shelving or reverting them, and then unshelve the desired version. Unshelve normally refuses to apply any changes if any path involved is already modified (or has any other abnormal status) in the WC. With --force, it does not check and may error out and/or produce partial or unexpected results.
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)
When 'svn shelve' encounters any unshelvable WC state in the specified paths:
When 'svn unshelve' hits a path that already has a local modification:
(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:
When 'unshelve' hits a conflict in merging file or properties:
Client-level support (user interfaces):
Shelves are stored in WC metadata dir '.svn/shelves/'.