diff --git a/README.md b/README.md index e0032c9..c3a7d83 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,20 @@ [![Gem Version](https://badge.fury.io/rb/capistrano-deploytags.svg)](http://badge.fury.io/rb/capistrano-deploytags) -Capistrano Deployment Tags -========================== -This plugin to Capistrano will add a timestamped Git tag -at each deployment, automatically. It is intended to be used with -the multistage recipe and will tag each release by environment. -You can, however, use it without multistage simply by setting :branch -and :stage in your recipe. -What It Does ------------- +## Capistrano Deployment Tags + +This plugin for Capistrano 3 will add a timestamped Git tag +at each deployment, automatically. It requires :branch and :stage to be set, +but as Capistrano 3 is multistage by default (unlike Cap 2) :stage should +already be set, but you can override the variable if you want to change the +name of the tag. + +### Requires Capistrano 3 + +As of version 1.0.0, this plugin requires Cap 3. If you need a Capistrano +2 compatible version, then use `gem 'capistrano-deploytags', '~> 0.9.2'` + +### What It Does + Simply: it makes it so you can track your deployments from Git. If I were to issue the command: @@ -24,21 +30,29 @@ generating statistics about deployments per day/week/year, tracking code size over a period of time, detecting Rails migrations, and probably a thousand other things I haven't thought of. -Usage ------ +### Usage + capistrano-deploytags is available on [rubygems.org](https://rubygems.org/gems/capistrano-deploytags). -You can install it from there with: +In keeping with the pattern used by Capistrano itself and other plugins, add it +to the `development` group of your Gemfile with `require: false`: -`gem install capistrano-deploytags` +```ruby +# Gemfile +group :deployment do + gem 'capistrano-deploytags', '~> 1.0.0', require: false +end +``` -If you use Bundler, be sure to add the gem to your Gemfile. -In your Capistrano `config/deploy.rb` you should add: +Then require `capistrano-deploytags/capistrano` in your Capfile -`require 'capistrano-deploytags'` +``` +# Capfile +require 'capistrano-deploytags/capistrano' +``` -This will create two tasks, one that runs before deployment and one -that runs after. +This will create two tasks, one that runs before the `deploy` task, and one +that runs after the `cleanup` task. *NOTE:* You will be creating and pushing tags from the version of the code in the current checkout. This plugin needs to be run from a clean checkout of your @@ -51,15 +65,14 @@ system that will actually be deployed before checking the tree for changes. Know this ahead of time as this may affect how you deal with your deployment branches. -Setting the Remote ------------------- -By default, Capistrano Deploytags will use the first remote in the list returned -by `git remote`. If you prefer to use a different remote, then you may change the -`:git_remote` setting from your `deploy.rb`, the stage, or on the command line with -`-S git_remote=your-remote`. +### Setting the Remote + +By default, Capistrano Deploytags will use the remote names `origin`. If you +use a different remote name, then you may change the `:git_remote` setting +from your `deploy.rb` or the stage. + +### Working on Your Deployment Scripts -Working on Your Deployment Scripts ----------------------------------- Because you must have a clean tree to deploy, working on your deployment scripts themselves can be a bit frustrating unless you know how to make it work. The easiest way around this problem is to simply commit your changes @@ -69,8 +82,8 @@ happily carry on deploying without complaint. Alternatively, you could disable the plugin temporarily with one of the methods described below. -Disabling Tagging for a Stage ------------------------------ +### Disabling Tagging for a Stage + Sometimes you do not want to enable deployment tagging for a particular stage. In that event, you can simply disable tagging by setting `no_deploytags` like so: @@ -79,7 +92,8 @@ like so: set :no_deploytags, true ``` -You can also set this from the command line at any time with `-S no_deploytags=true`. +You can also set this from the command line at any time with an environment +variable `cap stage deploy NO_DEPLOYTAGS=true`. *NOTE:* this will disable the use of the plugin's functionality entirely for that stage. The tasks will run, but will do nothing. This means that tasks that @@ -87,24 +101,24 @@ are hooked to the Capistrano Deploytags tasks will also still run, but they may find their expectations are not met with regards to the cleanliness of the git tree. -Customizing the Tag Format --------------------------- -You may override the time format in `config/deploy.rb`: +### Customizing the Tag Format + +You may override the time format in `deploy.rb` or your stage: ```ruby set :deploytag_time_format, "%Y.%m.%d-%H%M%S-utc" ``` -Customizing the Tag Commit Message ----------------------------------- +### Customizing the Tag Commit Message + By default, Capistrano Deploytags will create a tag with a message that indicates the local user name on the box where the deployment is done, and the hash of the tagged commit. If you prefer to have a more detailed commit message you may override -the `:deploytag_commit_message` setting from your `deploy.rb` or on the command line -with `-S deploytag_commit_message='This is my commit message for the deployed tag'`. +the `:deploytag_commit_message` setting from your `deploy.rb`, e.g. +`set :deploytag_commit_message, 'This is my commit message for the deployed tag'` + +### Viewing Deployment History -Viewing Deployment History --------------------------- It's trivial to view the deployment history for a repo. From a checkout of the repo, type `git tag -l -n1`. The output looks something like: @@ -113,7 +127,7 @@ dev-2013.07.22-105130 baz deployed a4d522d9d to dev dev-2013.07.22-113207 karl deployed 4c43f8464 to dev dev-2013.07.22-114437 gavin deployed 776e15414 to dev dev-2013.07.22-115103 karl deployed 619ff5724 to dev -dev-2013.07.22-144121 joshmyers deployed cf1ed1a02 to dev +dev-2013.07.22-144121 josh deployed cf1ed1a02 to dev ``` A little use of `grep` and you can easily get the history for a particular (e.g. `git tag -l -n1 | grep dev`). @@ -121,8 +135,8 @@ particular (e.g. `git tag -l -n1 | grep dev`). It should be noted that the names used when tags are created are the local user name on the box where the deployment is done. -Helpful Git Config ------------------- +### Helpful Git Config + You might find it useful to add this to your ~/.gitconfig in order to get a nice history view of the commits and tags. @@ -134,29 +148,43 @@ to get a nice history view of the commits and tags. You can then view the list by typing `git lol` from the checked out code path. -Deploying a Previous Commit ---------------------------- +### Deploying a Previous Commit + Because you have to actually be on the head of the branch you are deploying in order for tagging to work properly, deploying a previous -commit doesn't work as you might expect. The simple solution is to -create a new branch from the previous commit you wish to deploy and -supplying `-S branch=` as arguments to Capistrano. +commit doesn't work as you might expect. + +One simple solution is to configure your `config.rb` to accept an ENV var +override. Then if you need to deploy a previous commit you can check out that +commit (SHA or branch), and supply the var on the command line. e.g. with this +in your `config.rb`: + +```ruby +set :branch, ENV["REVISION"] || ENV["BRANCH_NAME"] || "master" +``` + +you can deploy a previous commit with + +```shell +git checkout +cap deploy REVISION= +``` + +### Running from Jenkins -Running from Jenkins --------------------- Because Jenkins will check out the code with the current revision number you will be in a detached state. This causes the plugin to be unhappy about the git tree. The solution is to add `-S branch=$GIT_COMMIT` to the cap deploy line called from your Jenkins build. This will cause the diffs and comparisons done by the deploytags gem to be correct. -Credits -------- +### Credits + This software was written by [Karl Matthias](https://github.com/relistan) with help from [Gavin Heavyside](https://github.com/gavinheavyside) and the support of [MyDrive Solutions Limited](http://mydrivesolutions.com). -License -------- +### License + This plugin is released under the BSD two clause license which is available in both the Ruby Gem and the source repository.