A summary of the experimental Shelving and Checkpointing feature in Svn-1.12, building on the Shelving-v2 in Svn-1.11.
(For other pages about Shelving and Checkpointing, see Shelving and Checkpointing.)
Summary
Experimental shelving v3:
- now supports all committable changes – see 'Functionality' below
- is slower than v2 -- see 'Performance' below
- is incompatible with v2 -- see 'Migrating' below
The main effort since v2 was on creating APIs in the svn client that allowed changes to be:
- 'exported' from the WC in the same manner as they are sent to the server in a commit, but instead to an arbitrary receiver (in this case, a shelf);
- 'imported' to the WC from an arbitrary sender of changes (in this case, a shelf)
and then re-implementing shelves as 'hidden WCs' and wiring up the high level 'glue' logic that connects 'export changes from a shelf-WC' to 'import changes to main-WC' and the other way around.
This lays the foundation for more powerful management of shelved changes. The previous experimental version of shelving code had to have their own implementations of all the mechanics of transferring and storing each kind of change, and that was unmaintainable. This version shares all of that functionality with the 'main' WC.
The emphasis of shelving v3 is making that architectural change. To make it also fast and use minimal space, more work will be required: see 'Performance' below.
Functionality
Kinds of change that can be shelved
WC State or Change | Shelving v1 svn 1.10 | Shelving v2 svn 1.11 | Shelving v3 svn 1.12 |
|---|---|---|---|
committable changes | |||
file text, file delete/add, most properties | yes | yes | yes |
mergeinfo changes | yes | yes | yes |
copies and moves | no | no | as copies* |
directories (mkdir/rmdir/...) | no | no | yes |
binary files & properties | no | yes | yes |
uncommittable state | |||
unresolved conflicts | no | no | no |
changelist assignment | no | no | no |
unversioned items (git stash -u/-a) | no | no | no |
inconsistent WC states (missing/obstructed) | no | no | no |
base state | |||
WC base state (rev, URL, switched, depth) | no | no | no |
*on shelving, a move is converted to copy-and-delete, just like it is on commit.
Performance
Experimental Shelving v3 generally is slower and uses more disk space than v2. It uses high-level WC functionality to support all committable changes in a WC, it runs up against WC performance issues. Particular issues in this version are:
- When shelving, an inefficient procedure is used to store a base state before the desired changes are stored on top of it.
- When shelving or unshelving a "copy" (or "move"), it fetches the base content of the copy directly from the repository, instead of from the local WC storage. That is because no suitable API implementation was available in Subversion for extracting the base content from the local WC storage. This also means that offline shelving and unshelving is not possible with copies or moves, in its current state.
With more effort invested, these performance issues in the experimental version could be overcome. (Interested in making it so? Get in touch with the Subversion project.)
Migrating from Shelving v2
Experimental Shelving v3 cannot read or write or see the existence of earlier experimental shelves.
To migrate a v2 shelf to v3, unshelve it using svn 1.11 into a clean (or clean enough) WC, and then shelve it using svn 1.12.
Implementation
This version stores each shelf (each shelf-version, in fact) in a "real" WC hidden inside the main WC's .svn metadata area.
Shelves are stored in WC metadata dir '.svn/experimental/shelves/v3/'.