|Easy Vendor Branch Management
|Categories/Tags:||[Vendor branch management (category)][Synchronization with Subversion (category)]|
|Documentation:||http://piston.rubyforge.org/ daily usage page
|Description:||Piston is a utility that eases [[vendor branch management (not the vendor drop kind—the other kind). This is similar to
pistonstores a local copy of the remote repository directory in your local repository. This allows you to make local modifications to your local copy and commit those changes.
svn:externals, when you
svn updatea repository containing a
pistonimport, it doesn't automatically update your
piston-imported directory. The directory will only be updated when you explicitly request an update via
svn:externals, you can tie your local copy of a remote repository directory to a specific revision. But unlike with
svn:externals, it's easy to switch back and forth between being tied to a revision (
piston lock) and simply using the latest revision (
svn exportit was possible to export a copy of remote repository directory, commit it to your local repository, and then forget which repository you got the code from! That can make it difficult to update your code with the vendor's latest changes, when that happens!
piston, by contrast, remembers the source repository info for you so you don't have to!
Several of my comrades in #caboose are using piston to manage external plugins for Ruby on Rails. Wait! Isn’t this what Subversion externals is meant for? Well, yes… but externals also eat away at productivity. For example, each day, we may have anywhere from 4-6 designers and developers working on one client project. When we’re in crunch mode, this could account for quite a few subversion commits throughout the day. We all know that we should run svn up on a regular basis to make sure that we’re keeping things in sync… especially when designers and developers are working really closely and fine tuning something specific in the application. Well, the one downside to this process is that each svn up not only checks our repository, but it also checks external repositories. “But wait! Can’t you just ignore externals on an update?” Of course, but who wants to type out --ignore-externals each time they run an update? ...or perhaps you could make an alias for this in your shell. In any event, everyone on the team is then left to be responsible for doing this… and an extra 30-60 seconds (if not longer) per svn update times x number of people on project… well… time wasted if you’re closely watching the svn updates. [...] Another issue with svn externals is that when a repository goes down, it really starts to slow stuff down your updates. This is always fun when you go to deploy your application with Capistrano and realize that you can’t finish the update because it can’t connect it to http://svn.lazyatom.com/public/plugins/acts_as_hasselhoff/ to make sure that your application has the latest version of [the plugin]. Then there is the whole issue of wanting to make changes to the plugin that you’re including as an external. How does that fit into the whole mix? There is Hope! Piston encourages you to keep your external plugins in your local repository. Don’t worry, it remembers where it retrieved the code from so that you can update from the external repository at any time. ...
With Piston, you import a remote repository and check it into your local repository. You can then go nuts modifying it or periodically sync it up with its remote origin using piston update. There's an advent calendar full of reasons why you'd want to manage Rails plugins with Piston rather than using svn:externals. For one thing, it makes checkouts and updates faster -- code is all kept in the same repository so you don't need to query foreign repositories on every svn up. It also gives you simple control over which reversion of a plugin you keep around -- it's really not ideal to have your plugins updating to the bleeding edge all the time. You could set your external to a tag, but what plugin author uses tags? Seriously. Piston makes life easier. ... Grab remote updates (plugin was updated, you want the updates):$ piston update vendor/plugins/simply_helpful/ Updated to r5710 (4 changes)
See directories under Piston's watch in your project:$ piston status vendor/plugins/simply_helpful (http://dev.rubyonrails.org/svn/rails/plugins/simply_helpful) vendor/plugins/annotate_models (http://svn.pragprog.com/Public/plugins/annotate_models) M vendor/plugins/acts_as_attachment (http://svn.techno-weenie.net/projects/plugins/acts_as_attachment/) vendor/plugins/acts_as_textiled (svn://errtheblog.com/svn/plugins/acts_as_textiled) vendor/plugins/mocha (svn://rubyforge.org/var/svn/mocha/trunk) vendor/plugins/has_many_polymorphs (svn://rubyforge.org/var/svn/polymorphs/has_many_polymorphs)
First, you need to import the remote repository location:$ piston import http://dev.rubyonrails.org/svn/rails/trunk vendor/rails Exported r4720 from 'http://dev.rubyonrails.org/svn/rails/trunk' to 'vendor/rails' $ svn commit -m "Importing local copy of Rails"
When you want to get the latest changes from the remote repository location:$ piston update vendor/rails Updated 'vendor/rails' to r4720. $ svn commit -m "Updates vendor/rails to the latest revision"
You can prevent a local Piston-managed folder from updating by using the lock subcommand:$ piston lock vendor/rails 'vendor/rails' locked at r4720.
When you want to update again, you unlock:$ piston unlock vendor/rails 'vendor/rails' unlocked.
convert: Converts existing svn:externals into Piston managed folders usage: convert [DIR [...]] Converts folders which have the svn:externals property set to Piston managed folders.
> piston status M plugins/rake_completion (https://secure.near-time.com/svn/plugins/trunk/rake_completion/) > piston update Processing 'plugins/rake_completion'... Fetching remote repository's latest revision and UUID Restoring remote repository to known state at r74 Updating remote repository to r29 Processing adds/deletes Merging local changes back in Removing temporary files / folders Updating Piston properties Updated to r29 (0 changes) > piston status plugins/rake_completion (https://secure.near-time.com/svn/plugins/trunk/rake_completion/)
When you do an import from a remote repository, it stores some information about the remote repository in your local repository using Subversion's handy "custom property" feature. Observe which properties get set after doing an import:
> piston import https://secure.near-time.com/svn/plugins/trunk/rake_completion/ Exported r74 from 'https://secure.near-time.com/svn/plugins/trunk/rake_completion/' to 'rake_completion' > svn propget piston:root rake_completion/ https://secure.near-time.com/svn/plugins/trunk/rake_completion/ > svn propget piston:local-revision rake_completion/ 2377 > svn propget piston:uuid rake_completion/ 7c507d47-1513-0410-95a0-a599ac62d117 > svn propget piston:remote-revision rake_completion/ 74