Documentation for FishEye 2.10.x. Documentation for other versions is available too.

Smart commits allow repository committers to perform actions like transitioning JIRA issues or creating Crucible code reviews by embedding specific commands into their commit messages. Multiple smart commits can be used in one commit message, however they must be on separate lines. Note that smart commits don't provide for field-level updates in JIRA issues.

Note that Smart commits require the following:

Transition your JIRA issues

Compatibility

  • In order to use smart commits with JIRA you need to have the JIRA FishEye Plugin version 3.4.5 or above installed on your JIRA instance.
  • Note that smart commits only support the default JIRA issue key format (that is, two or more uppercase letters, followed by a hyphen and the issue number, for example BAM-123).

On this page:

Related pages:

Basic command line syntax

The basic command line syntax for your commit comment is:

<ISSUE_KEY> #<COMMAND> <optional COMMAND_PARAMETERS>

Please note, commit commands cannot span more than one line (i.e. you cannot use carriage returns).

For example, if you include the following text in your commit message, FishEye will record 2 days and 5 hours of work against issue JRA-123, when you perform your commit:

 JRA-123 #time 2d 5h

(info) Please see the section below for further information on the command line parameters.

Advanced command line syntax

If you wish to perform multiple actions on issues, you can create composite commands by combining keywords, as described below. Please note, commit commands cannot span more than one line (i.e. you cannot use carriage returns).

  • To perform multiple actions on a single issue:

<ISSUE_KEY> #<COMMAND1> <optional COMMAND1_PARAMETERS> #<COMMAND2> <optional COMMAND2_PARAMETERS> #<COMMAND3> <optional COMMAND3_PARAMETERS> etc

For example, if you include the following text in your commit message, FishEye will log 2 days and 5 hours of work against issue JRA-123, add the comment 'Task completed ahead of schedule' and resolve the issue, when you perform your commit: 

 JRA-123 #time 2d 5h #comment Task completed ahead of schedule #resolve
  • To perform a single action on multiple issues:

<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<COMMAND> <optional COMMAND_PARAMETERS> etc
 
For example, if you include the following text in your commit message, FishEye will resolve issues JRA-123, JRA-234 and JRA-345, when you perform your commit: 

 JRA-123 JRA-234 JRA-345 #resolve
  • To perform multiple actions on multiple issues:

<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<COMMAND1> <optional COMMAND1_PARAMETERS> #<COMMAND2> <optional COMMAND2_PARAMETERS> #<COMMAND3> <optional COMMAND3_PARAMETERS> etc.

For example, if you include the following text in your commit message, FishEye will log 2 days and 5 hours of work against issues JRA-123, JRA-234 and JRA-345, add the comment 'Task completed ahead of schedule' to all three issues, and resolve all three issues, when you perform your commit:

 JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #comment Task completed ahead of schedule

Commands

Note that you can see the custom commands available for use with smart commits by visiting the JIRA issue and seeing its available workflow transitions (in an issue, click View Workflow, near the issue status).

Command

Command Parameters

Description

Example

#time

<n>w <n>d <n>h <n>m <work log comment> 
where <n> is a user-specified time period.

This command records time tracking information against an issue.
Please note, time tracking must be enabled for your JIRA instance to use this command. Please check with your JIRA administrator, if you cannot record time tracking information against issues.

Please note:

  • Work log comments cannot be set using smart commits. See FE-3757.

#time 1w 2d 4h 30m Total work logged — this command would record 1 week, 2 days, 4hours and 30 minutes against an issue, and add the comment 'Total work logged' in the Work Log tab of the issue.

 

#comment

<comment text>

This command records a comment against an issue.

#comment My comment. — this command would create the comment, "My comment", against the issue.

#<workflow command>
e.g. #resolve

<workflow> <comment text> 

This command transitions an issue to a particular workflow state. Please see the documentation for  Configuring Workflow  in JIRA.

FishEye will do prefix matching for issue transitioning. For example, if you have transition name with spaces, such as finish work then specifying #finish is sufficient. Hyphens replace spaces: #finish-work

FishEye will only execute issue transitions if there is no ambiguity in valid workflow transitions. Take the following example:
An issue has two valid transitions:

  • Start Progress
  • Start Review

A smart commit with action #start is ambiguous as FishEye will not be able to determine which transition to execute. In order to execute one of these transitions, the smart commit specified will need to be fully qualified #start-review

Please note: If you want to resolve an issue using the #resolve command, you will not be able to set the resolution via smart commits.

#close Fixed the issue — this command would execute the 'Close Issue' workflow transition for an issue in the default JIRA workflow and adding the comment 'Fixed the issue'.
#start — this command would execute the 'Start Progress' workflow transition for an issue in the default JIRA workflow

Integration with Crucible

Please note that each commit command in the commit message must not span more than one line (i.e. you cannot use carriage returns). You can use multiple commands in the same message as long as they are on separate lines.

Creating a review

With smart commits, it is also easy to create a Crucible review from a commit:

Fix a bug +review CR-TEST

The command "+review" tells FishEye to create a new review in the project CR-TEST with the content of the changeset. The review will be in a draft state unless the project has default reviewers or reviewers are explicitly mentioned. If you only have one project in Crucible, or a repository is a project's default repository, it is not necessary to mention the project key. Just use "fix a bug +review".

Adding reviewers

Reviewers can be added to a new review using a smart commit:

Fix a bug +review CR-TEST @jcage @skhan

That command will create a new review in PROJ and add the users jcage and skhan to the review. The review will be automatically started if reviewers are specified.

Note, you cannot add reviewers to existing reviews using smart commits.

Review objectives

When creating a new review using a smart commit the default project objectives are added to the review, and since Fisheye/Crucible 2.10.2, the commit message is also copied to the review objectives.

Note that you cannot add arbitrary objectives to the review from the smart commit.

Updating an existing review

Often, reviews require rework and changes in response to comments left by the team. When committing these changes, adding the review key will iteratively add these new changes to the review:

Implement rework on past work +review CR-TEST-123

With this command FishEye will add the changeset content to the review CR-TEST-123.

Linkers

When using smart commits you can use linkers that create a hyperlink to the JIRA issue. See Linkers for more information.

Error handling

If there are any errors during the processing of smart commits, they will be logged to FishEye's error console, as well as emailed to the actioning users. Please speak to your FishEye administrator about Configuring SMTP.

  • No labels

9 Comments

  1. Anonymous

    Dec 10, 2012

    Are project links still required for smart commits for Fisheye 2.9+, JIRA 5.x?

    1. Daniel R

      Dec 13, 2012

      Project Links / Entity Links are no longer mandatory for smart commits to work. I will edit the documentation accordingly.

      Thank you,
      Daniel

  2. Anonymous

    Jan 10, 2013

    can we update a field in the issue using smart commits?

    1. paulwatson

      Jan 11, 2013

      Smart commits don't provide for field-level updates. You could write your own plugin to do this, however.

  3. James Kubecki

    Jan 18, 2013

    Is there an escape sequence for putting a hashtag/number sign (#) in a commit without it being interpreted? One of our developers used one and Fisheye attempted to interpret it as a workflow command. (It failed, which wasn't a problem, but it emailed him an error and he was confused.)

    1. Anonymous

      Jan 30, 2013

      Clear a good idea to add an escape sequence. The current workmode is too limited there...

  4. Daan

    Mar 12, 2013

    How can I update a issue and create a new review without adding 'garbage' to the review title?

    If I have a commit log that looks a bit like this:

    JIRAISSUE-XXX #workflowcommad #time 1d 2h 3m I've done some work on this issue bla bla
 
What I've fixed goes here
And here
And here some more
+review CRUCIBLEPROJECTGOESHERE

    I'll get a name containing the JIRAISSUE-XX #workflowcommand #time etc...

    1. Maurice Romaniuk

      Apr 04, 2013

      Are there any updates to what Da an is indicating? We are running into the same issue. Here is the format I have tried (we are  committing this command via GIT Tower and then pushing it to GIT):

      Nice descriptive title text JIRAISSUE-XXX #workflowcommand #time 1d 2h 3m #comment Info specific to JIRA progress +review CR-TEST @me @you @us

      This sets the Crucible title and objectives text as:

      Nice descriptive title text JIRAISSUE-XXX #workflowcommand #time 1d 2h 3m #comment Info specific to JIRA progress

      Not very nice as a result.

      Resolution?

       

      1. Anonymous

        Apr 25, 2013

        When resolving issues and adding comments with smart commit, then I've experienced that newline delimits different blocks. Does it not work the same when creating review?

        JRA-123 #resolve #comment Comment for about resolving 123
JRA-234 JRA-456 #close #comment Comment about closing 234 and 345
Something completely different that does not show up in JIRA comments 
but is visible in fisheye and three issues source tab.

        We don't use review creating with smart commits, but wishful thinking tells me, that, when you put your +review in commit messages new line, then it should be interpreted separately. (maybe try with extra linefeed before +review or try putting +review onto first line instead)

 

 

 Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.