# smart\_commits

## Smart Commit commands

The basic syntax for a Smart Commit message is:

```
<ignored text> <ISSUE_KEY> <ignored text> <COMMAND> <optional COMMAND_ARGUMENTS>
```

Any text between the issue key and the command is ignored. There are three commands you can use in your Smart Commit messages:

<br>

* `comment`
* `time`
* `transition`

  <br>

### Comment<br>

<br>

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Adds a comment to a Jira Software issue.</td></tr><tr><td>Syntax</td><td><pre><code>&#x3C;ignored text> &#x3C;ISSUE_KEY> &#x3C;ignored text> comment &#x3C;comment_string>
</code></pre></td></tr><tr><td>Example</td><td><pre><code>JRA-34 comment corrected indent issue
</code></pre></td></tr><tr><td></td><td></td></tr></tbody></table>

#### Notes:

The committer's email address must match the email address of a single Jira Software user with permission to comment on issues in that particular project.

<br>

### Time

<br>

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Records time tracking information against an issue.</td></tr><tr><td>Syntax</td><td><pre><code>&#x3C;ignored text> ISSUE_KEY &#x3C;ignored text> time &#x3C;value>w &#x3C;value>d &#x3C;value>h &#x3C;value>m &#x3C;comment_string>
</code></pre></td></tr><tr><td>Example</td><td><pre><code>JRA-34 time 1w 2d 4h 30m Total work logged
</code></pre></td></tr></tbody></table>

#### Notes:

This example records 1 week, 2 days, 4 hours and 30 minutes against the issue, and adds the comment `Total work logged` in the **Work Log** tab of the issue.

<br>

* Each value for `w`, `d`, `h` and `m` can be a decimal number.
* The committer's email address must match the email address of a single JIRA Software user with permission to log work on an issue.
* Your system administrator must have enabled time tracking on your JIRA Software instance.

  <br>

### Workflow transitions

<br>

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Transitions a Jira Software issue to a particular workflow state.</td></tr><tr><td>Syntax</td><td><pre><code>&#x3C;ignored text> ISSUE_KEY &#x3C;ignored text> &#x3C;transition_name> &#x3C;comment_string>
</code></pre></td></tr><tr><td>Example</td><td><pre><code>JRA-090 #close Fixed this today
</code></pre></td></tr></tbody></table>

#### Notes:

This example executes the close issue workflow transition for the issue and adds the comment `Fixed this today` to the issue. Note that the comment is added automatically without needing to use the comment command.

You can see the custom commands available for use with Smart Commits by visiting the JIRA Software issue and seeing its available workflow transitions:

1. Open an issue in the project.
2. Click **View Workflow** (near the issue's **Status**).

The Smart Commit only considers the part of a transition name before the first space. So, for a transition name such as `finish work`, then specifying `#finish` is sufficient. You must use hyphens to replace spaces when ambiguity can arise over transition names, for example: `#finish-work`.

If a workflow has two valid transitions, such as:

* `Start Progress`
* `Start Review`

A Smart Commit with the action `#start` is ambiguous because it could mean either of the two transitions. To specify one of these two transitions, fully qualify the transition you want by using either `#start-review` or `#start-progress`.

* When you resolve an issue with the `#resolve` command, you cannot set the **Resolution** field with Smart Commits.
* If you want to add a comment during the transition, the transition must have a screen associated with it.
* The committer's email address must match the email address of a single JIRA Software user with the appropriate project permissions to transition issues.

  <br>

## Advanced examples

<br>

### Multiple commands on a single issue

<br>

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>Syntax</td><td><pre><code>&#x3C;ISSUE_KEY> #&#x3C;COMMAND_1> &#x3C;optional COMMAND_1_ARGUMENTS> #&#x3C;COMMAND_2> &#x3C;optional COMMAND_2_ARGUMENTS> ... #&#x3C;COMMAND_n> &#x3C;optional COMMAND_n_ARGUMENTS>
</code></pre></td></tr><tr><td>Commit message</td><td><pre><code>JRA-123 #time 2d 5h #comment Task completed ahead of schedule #resolve
</code></pre></td></tr><tr><td>Result</td><td><p>Logs 2 days and 5 hours of work against issue JRA-123, adds the comment 'Task completed ahead of schedule', and resolves the issue.</p><p><br></p></td></tr></tbody></table>

***

### Multiple commands over multiple lines on a single issue

<br>

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>Syntax</td><td><pre><code>&#x3C;ISSUE_KEY> #&#x3C;COMMAND_1> &#x3C;optional COMMAND_1_ARGUMENTS> #&#x3C;COMMAND_2> &#x3C;optional COMMAND_2_ARGUMENTS> ... #&#x3C;COMMAND_n> &#x3C;optional COMMAND_n_ARGUMENTS>
</code></pre></td></tr><tr><td>Commit message</td><td><pre><code>JRA-123 #comment Imagine that this is a really, and I mean really, long comment #time 2d 5h
</code></pre></td></tr><tr><td>Result</td><td><p>Adds the comment <code>'Imagine that this is a really, and I'</code>, but drops the rest of the comment. The work time of 2 days and 5 hours is not logged against the issue because there is no issue key for the time command in the second line. That is, each line in the commit message must conform to the Smart Commit syntax.</p><p>This example would work as expected if set out as:</p><pre><code>JRA-123 #comment Imagine that this is a really, and I mean really, long comment
JRA-123 #time 2d 5h
</code></pre></td></tr></tbody></table>

\ <br>

***

### A single command on multiple issues

\ <br>

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>Syntax</td><td><pre><code>&#x3C;ISSUE_KEY1> &#x3C;ISSUE_KEY2> &#x3C;ISSUE_KEY3> #&#x3C;COMMAND> &#x3C;optional COMMAND_ARGUMENTS> etc
</code></pre></td></tr><tr><td>Commit message</td><td><pre><code>JRA-123 JRA-234 JRA-345 #resolve
</code></pre></td></tr><tr><td>Result</td><td><p>Resolves issues <code>JRA-123</code>, <code>JRA-234</code> and <code>JRA-345</code>.</p><p><br></p><p>Multiple issue keys must be separated by whitespace or commas.</p></td></tr></tbody></table>

\ <br>

### Multiple commands on multiple issues

<br>

<table data-header-hidden><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>Syntax</td><td><pre><code>&#x3C;ISSUE_KEY1> &#x3C;ISSUE_KEY2> ... &#x3C;ISSUE_KEYn> #&#x3C;COMMAND_1> &#x3C;optional COMMAND_1_ARGUMENTS> #&#x3C;COMMAND_2> &#x3C;optional COMMAND_2_ARGUMENTS> ... #&#x3C;COMMAND_n> &#x3C;optional COMMAND_n_ARGUMENTS>
</code></pre></td></tr><tr><td>Commit message</td><td><pre><code>JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #comment Task completed ahead of schedule
</code></pre></td></tr><tr><td>Result</td><td><p>Logs 2 days and 5 hours of work against issues <code>JRA-123</code>, <code>JRA-234</code> and <code>JRA-345</code>, adds the comment <code>'Task completed ahead of schedule'</code> to all three issues, and resolves all three issues.</p><p>Multiple issue keys must be separated by whitespace or commas.</p></td></tr></tbody></table>
