Daily Usage
This page explains the day to day usage of Piston.
Setup
Let's say you have a Rails application. You are using Capistrano and svn:externals to manage your plugins and vendor/rails.
The svn:externals of your plugins folder looks like this:
$ svn propget svn:externals vendor rails http://dev.rubyonrails.org/svn/rails/trunk $ svn propget svn:externals vendor/plugins response-logger svn://svn.teksol.info/svn/rails/plugins/response-logger file_column -r29 http://opensvn.csie.org/rails_file_column/plugins/file_column/trunk
As you can see, the FileColumn plugin always updates to revision 29. The others are free to update to HEAD.
Converting
First off, you need to convert your existing svn:externals to Piston managed folders. The command is simple:
$ piston convert Importing 'http://dev.rubyonrails.org/svn/rails/trunk' to vendor/rails (-r 4720) Exported r4720 from 'http://dev.rubyonrails.org/svn/rails/trunk' to 'vendor/rails' Importing 'svn://svn.teksol.info/svn/rails/plugins/response-logger' to vendor/plugins/response-logger (-r 2) Exported r2 from 'svn://svn.teksol.info/svn/rails/plugins/response-logger' to 'vendor/plugins/response-logger' Importing 'http://opensvn.csie.org/rails_file_column/plugins/file_column/trunk' to vendor/plugins/file_column (-r 29 locked) Exported r29 from 'http://opensvn.csie.org/rails_file_column/plugins/file_column/trunk' to 'vendor/plugins/file_column' Done converting existing svn:externals to Piston
If you examine the output, you will see Piston automatically locked revision 29 of vendor/plugins/file_column.
Let's examine how Piston manages it's properties.
$ svn proplist --verbose vendor/rails Properties on 'vendor/rails': piston:root : http://dev.rubyonrails.org/svn/rails/trunk piston:local-revision : 1474 piston:uuid : 5ecf4fe2-1ee6-0310-87b1-e25e094e27de piston:remote-revision : 4720
See the properties page for detailed explanations of how Piston uses these properties.
Then, commit your changes.
$ svn commit --message "Converted to Piston managed folders."
Congratulations, your repository now contains a copy of Rails as well as a copy of the ResponseLogger and FileColumn plugins.
NOTE: Piston is conservative. When converting, it will never use HEAD. Instead, Piston will read the current Last Changed Rev and use that. Why does it do it that way ? Your code is tested against the revision in question, but HEAD might have introduced changes which you have not yet tested, so Piston takes the more secure road.
Locking
Since you are using Edge Rails, destabilizing changes might occur at any time. If you hear about such a change, you should immediately lock your Piston folder to prevent inadvertent updates.
Locking a folder prevents Piston updates from touching the folder in question. Locking always locks at the current revision.
$ piston lock vendor/rails 'vendor/rails' locked at revision 4720 $ svn commit --message "Locked vendor/rails"
Unlocking
Once you know the destabilization has been corrected, you can unlock the Piston folder, and it will happily update afterwards.
$ piston unlock vendor/rails Unlocked 'vendor/rails' $ svn commit --message "Unlocked vendor/rails"
Updating
This is the most interesting part of Piston. Normally, when you copy the contents of a remote repository to your own, there is no way to further import changes. Piston does allow you to continue receiving updates from the upstream repository, albeit with a few caveats.
$ piston update vendor/rails Processing 'vendor/rails'... Updated to 4826 (124 changes) $ svn commit --message "Updated Rails to edge"
Using tagged releases
Before 1.3.0, Piston was not built to handle branches and tags properly. This has now been resolved. For example, let's say you have tagged Rails at 1.1.6. Now that 1.2.1 is out, you'd like to use that instead. Here's how to do it:
$ piston switch http://dev.rubyonrails.org/svn/rails/tags/rel_1-2-1 vendor\rails Processing 'vendor\rails'... Fetching remote repository's latest revision and UUID Restoring remote repository to known state at r6010 Updating remote repository to http://dev.rubyonrails.org/svn/rails/tags/rel_1-2-1@5990 Processing adds/deletes Removing temporary files / folders Updating Piston properties Updated to r5990 (663 changes)
