Home

Overview

The purpose of crucible-cli is to provide a command line interface for creating, summarizing and closing code reviews in Crucible.

crucible-cli leverages the Crucible REST API to interact with Crucible and create reviews.

The application is written using Eclipse RCP which will allow it to be built and deployed for a variety of environments from a single code base as an executable. It may be converted to a simple jar file with shell scripts at some point in the future to simplify deployment.

#License Information crucible-cli is licensed with a BSD style license. See the License page.

#Installation TBD.

#Usage

##Properties File The first thing you have to do is create a properties file. By default, crucible-cli expects to find a crucible-cli.properties in your home directory. The properties file needs 4 properties:

protocol=[http|https] host=hostname port=portNumber context=context

All 4 properties should be present but only protocol, host and port are required. You can force crucible-cli to use another properties file by using the optional command line arg --config, the value of which should be a fully qualified path to a properties file on your file system.

#Creating An Auth Token Crucible supports auth tokens. This makes it possible for you to use the REST API without having to specify your credentials each time.

To create an auth token you should use the following syntax:

crucible --action createToken --username user1 --password passwordForUser1

If this is successful a token will be written to ~/crucible-cli.tkn and will contain something like this:

username:xxx:blahblahblahblah

Currently crucible-cli doesn't offer a way to customize the file name or location of the token (however this is an enhancement that is slated for the future).

#How to User crucible-cli ##Create A Review To create a review from the command line using crucible-cli you will need to know two things from Crucible:

• Repository Name
• Project Key

The repository name maps to the abbreviated key name as shown on the "Source" tab for your code in FishEye. The project key is the abbreviated value you see when you look at your project in the "Projects" tab in Crucible.

Suppose I have a repository name of CLI and project key of CCLI-1-0 in my Crucible/FishEye instance. Further suppose that my username is jeff and I have two co-workers who I want to review one of my commits. Here is how I create a review:

crucible --action createReview --username jeff --projectKey CCLI-1-0 --repository CLI --reviewName "Code Review for new Foo feature" --description "A code review to cover all my commits to Git for the Foo feature in our next release"

This will create the review with me as the author and moderator. It will output the review id as well. You'll want to remember that for future use:

Review created with ID: CCLI-1-0-1

##Adding Code to my Review Next, I should probably add some code to this review. You need at least one commit entry from your SCM. Here is what you need to do:

crucible --action addChangesets --reviewId CCLI-1-0-1 --repository CLI --changeset commit1,commit2,commit3

This will cause crucible-cli to iterate over each commit and add it to the review. Although the Crucible REST docs suggest it is possible to do this in one request, I've found that I can't submit more than three at a time, so crucible-cli submits a unique request for each commit entry. Each successful addition will be noted with output like this:

Successfully added changeset commit1 to review CCLI-1-0-1 in repo CLI

##Adding Reviewers to My Review

Lastly, to add reviewers, you would run the following command:

crucible --action addReviewers --reviewId CCLI-1-0-1 --reviewers fred,jill

This will add Fred and Jill to my review.

##Summarizing a Review When the review is complete and you want to summarily summarize the review, you would use the following command:

crucible --action summarizeReview --reviewId CCLI-1-0-1

You should see a message like this upon success:

Successfully summarized review CCLI-1-0-1

Now you are ready to close the review.

#Closing a Summarized Review

To close a review it must be in the 'summarized' state already. The command syntax is as follows:

crucible --action closeReview --reviewId CCLI-1-0-1

Upon success, you will see this message:

Successfully closed review CCLI-7

Your review is now closed.

##Getting Help on the Command Line The crucible-cli application has help built in so that you can get help from the command line. To use help you can do the following:

crucible --help

or

crucible --action createReview --help

The first will produce a generic help message as follows:

crucible --help
usage: crucible 
 -action <arg>   Required; the action to be performed.
 -config <arg>   Optional; if you have a ~/crucible-cli.properties,
                 otherwise required.         
 -help           Print help information.    
-------------------------------------------
                               
Examples of available Actions:
--action createReview
--action closeReview
--action addChangesets
--action abandonReview
--action addReviewers
--action summarizeReview
--action createToken

Then when you need help with a specific action, the output looks like this:

crucible --action createReview --help
Create a new review in the specificied Crucible instance.
                                                          
Typically used in conjuction with addReviewers and addChangesets.
                                                                  
Note: reviews without reviewers get created in a draft state and don't
move into the 'out for review' queue till you add users.
 
 
usage: createReview
 -allowOthersToJoin <arg>   Optional. Defaults to true.
 -description <arg>         Required. A description of the changeset being
                            reviewed.
 -projectKey <arg>          Required. The project key from Crucible for
                            this change.
 -repository <arg>          The name of the repository as defined in
                            Crucible.
 -reviewName <arg>          Optional The name of this review that will be
                            shown in Crucible. Defaults to 'Review for
                            commit xxxx' where xxxx is the changeset
                            specfied.
 -username <arg>            Required. The user name that will be used as
                            the author/moderator(typically needs to match
                            the value in the token.
 
Examples:
-------------------------------------------------
--action createReview --projectKey PROJ-ID --reviewName "My Review of Foo" 
   --description "Review of my changes to Foo."--repository myRepo 
   --allowOtherToJoin true