Transition your JIRA issues

Basic command line syntax

The command line syntax for a commit comment is:

<ISSUE_KEY> #<COMMAND> <optional COMMAND_PARAMETERS>

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

JRA-123 #time 2d 5h

Note that a single commit command cannot span more than one line (i.e. you cannot use carriage returns). For example:

JRA-123 #comment this is a comment

will give the expected result, but

JRA-123 #comment this is
a comment

will only add 'this is' as a comment to the issue  JRA-123.

 See the section below for further information about command line parameters.

Advanced command line syntax

You can perform multiple actions on issues by combining commands. Note that a commit command cannot span more than one line (i.e. you cannot use carriage returns), but you can add multiple commands to the same line.

• To perform multiple actions on a single issue:

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

Note that this commit message has wrapped to the next line here – a carraige return was not used.

For example, if you include the following text in the 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 make the 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 the commit message, FishEye will resolve issues JRA-123, JRA-234 and JRA-345, when you perform the 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.

Note that this commit message has wrapped to the next line here – a carraige return was not used.
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 the commit:

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

Note that the Git command line ignores lines starting with the '#' character, so you may need to begin a new line with a space before the '#'.

Commands

You can see the custom commands available for use with smart commits by visiting the JIRA Software 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 value.	This command records time tracking information against an issue. Note that time tracking must be enabled for your JIRA Software instance to use this command. Check with your JIRA Software administrator, if you cannot record time tracking information against issues. Note that 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. See Workflows  for JIRA Software. 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 Note that to resolve an issue using the #resolve command, you will not be able to set the resolution via smart commits. We are tracking this improvement request here:	#close Fixed the issue — this command would execute the 'Close Issue' workflow transition for an issue in the default JIRA Software 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 Software workflow

Integration with Crucible

Note that:

• Each commit command in the smart commit must not span more than one line (i.e. you cannot use carriage returns). However, you can use multiple commands in the same commit message, and these can be on the same line.
• Creating a review in Crucible using a smart commit requires that the author of the changeset has already been mapped to a Crucible username. See 'Author mapping' on Changing your user profile.

Creating a review

With smart commits, it is 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 that 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 using a 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 Software 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. Speak to your FishEye administrator about Configuring SMTP.