This documentation relates to an earlier version of FishEye.
View

Unknown macro: {spacejump}

or visit the current documentation home.

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 require the following:

 

On this page:

Related pages:

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).

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

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.
  • Only the first time parameter is set, if multiple time parameters are used in a commit command. See FE-3885.

#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

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.

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.

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

47 Comments

  1. Jean-Yves Avenard

    Sept 09, 2011

    How can you resolve an issue and provide a resolution type? Say resolving the issue with resolution being Fixed

    Some examples are a bit confusing.

    "For example, if you have transition name with spaces, such as start progress then specifying #start is sufficient. Hyphens replace spaces: #start-progress"

    seems to start that using #start is sufficient

    Yet the next chapter you read: A smart commit with action #start is ambiguous as FishEye will not be able to determine which transition to execute.

    Maybe using a different command between the two examples would be clearer

    1. Seb Ruiz

      Jan 04, 2012

      Hi Jean-Yves,

      I have updated the documentation and hope it is clearer now. You can specify a resolution with an optional argument after the transition, such as:

      #close fixed

      My apologies - this is apparently not possible in the latest JIRA FishEye plugin and there is currently a bug raised for it here:  FE-3873 - Getting issue details... STATUS

  2. Anonymous

    Sept 09, 2011

    Is there a way to effectively reverse this logic? I want to automatically create a review for every commit, unless I add "-review" in the commit comment.

    1. Seb Ruiz

      Sept 16, 2011

      There is no way to do this currently. You could create a Smart Commit that created a review unless if found the -review key.

      Please see our developer documentation for resources: https://developer.atlassian.com/display/FECRUDEV/Smart+Commit+Tutorial

  3. Miro Lehky [Metron]

    Sept 13, 2011

    How about assigning the issue to a specific person when when using the transition?

    1. Sten Pittet

      Sept 21, 2011

      You cannot do this for issues but you're allowed to assign people to reviews using the '@' sign and their login.

  4. Jean-Yves Avenard

    Sept 17, 2011

    Is there a way to mark an issue as fixed, without closing it? More often than not, when a dev commit a fix, the issue isn't going to be immediately closed. That's up to QA to do that once a bug has been verified as fixed.

    Something that is greatly missing is being able to add the reference to the commit where the change occurred in the comment.

    JIRA-123 #comment blah

    Shouldn't add just "blah" as a comment, but also includes in the comment the revision or commit. Such as:

    rev:1234: blah (or r1234 is svn, rev:SHA1 if git etc)...

    I would imagine to be the most common way of a dev committing a bug and wanting to change the related JIRA issue status, including the commit revision.

    Thanks

    1. Sten Pittet

      Sept 21, 2011

      Hi Jean-Yves,

      You can use the transition #resolve to mark your issue as resolved. Then QA can close the issue in a separate process. You can consult the JIRA documentation about workflows for more information.

      Regarding the comment are you thinking about having at the bottom of the comment a note saying "created from r1234"? Currently if you have JIRA integrated with FishEye you will be able to see all the commits related to an issue in the source tab.

      1. Jean-Yves Avenard

        Sept 21, 2011

        Yes, this is exactly what I am thinking about ; and that solution would be great.

        being able to see a commit in one screen, and directly relate a comment to a commit are two different things and the first is nowhere as straightforward.

        Also, being able to see the related svn commits require the JIRA user to have access to FishEye which isn't always the case. (users vs developers). For a user, knowing which revision of SVN includes the fix is however a useful information

        We implemented such method in bugzilla easily using post-commit hooks. Unfortunately, doing so in Fisheye/JIRA is nowhere near as simple (I wouldn't even know where to start)

  5. Kazimierz Lenkowski

    Sept 22, 2011

    By mistake I have put wrong Jira task id in commit message. Later on I have modified commit message to proper task id, but FishEye still links the change set to the wrong task.

    How can I change this FishEye-Jira changeset-task link?

    1. Jean-Yves Avenard

      Sept 22, 2011

      What is stored in the commit message has nothing to do with fisheye, fisheye only reads the value stored in the repository

      If using subversion, you would have to edit the commit message which is stored in the svn:log property

      something like svn propedit svn:log --revprop -r COMMIT_NUMBER path_to_svn

      This requires that your subversion repository allows editing properties (this is done by tinkering the pre-revprop-change in the svn hooks folder).

      Then simply re-run a fisheye properties indexing.

      1. Kazimierz Lenkowski

        Sept 22, 2011

        Thanks for quick response. It worked well after re-scanning props.

        Is it possible to start revision re-scan without having administrator rights on the repository? It will be troublesome if each time a developer makes a mistake in commit log, he will have to go ask administrators to re-scan.

  6. Greg Carnie

    Oct 02, 2011

    Has anyone else been unable to commit the work log comment when using the #time Command?  I can use the #comment command to add comments and the #time to just add time, but the work log comment only appears as 'null'.  Anyone seeing the same?

    1. Joshua Worden

      Sept 20, 2012

      Yes, we're currently having the same issue. Haven't figured out how to resolve it yet.

  7. Anonymous

    Oct 07, 2011

    Can you add a comment, resolve, and re-assign to someone else using a smart commit?

    1. Seb Ruiz

      Oct 07, 2011

      Both adding comments and resolutions/workflow transitions are supported. Assigning to users is not currently.

  8. Anonymous

    Oct 08, 2011

    i know this might seam abit backward but what would be cool is if you raise a JIRA task from a commit message...

    say you find a random typo, or sub-optimal code while doing another task, by allowing a smart commit to open a new task we can make use of crucible's JIRA integration (rasing tasks from defect messages)... currently we have to raise a task in JIRA then mention it in the commit message... by allowing this you could save a few min and keep track of every change even those tiny tweeks that seam silly raising a task to close it right away...

  9. Seb Ruiz

    Nov 09, 2011

    plugins.atlassian.com gets a little confused if a bugfix is released for an older version (it uses the last uploaded plugin rather than the highest version number). The latest is currently 3.4.7, which can be found here: https://plugins.atlassian.com/plugin/details/290?versionId=623849

  10. Anonymous

    Nov 13, 2011

    Due to the following errors, the smart commits were not actioned and will need to be performed manually.

    Error processing TTBY-81 #work 5m renamed the reportlayout for dataloads to be specific, not generic
    FishEye was unable to execute the transition "work" on the issue TTBY-81 because it appears the JIRA server located at https://mysite.com/issues does not have a compatible version of the JIRA FishEye plugin installed. Please upgrade the JIRA FishEye plugin to version ${encoder.htmlEncode($str)} or greater.

    See the documentation for how to invoke JIRA Issue Transitions automatically

     

    Not helpful..  Using the latest version of the plugin according to jirs 4.3. Is this limited to 4.4?

  11. Anonymous

    Nov 18, 2011

    Is it possible to specify the Fix Version using the Smart Commits, e.g. FOO-123 #resolve fixed #fix-version 1.1?

    1. Sten Pittet

      Nov 20, 2011

      It's not possible to use the fix version with the default Smart Commits but you can extend this module to add your own actions.

      You can check our documentation for more resources: https://developer.atlassian.com/display/FECRUDEV/FishEye+Smart+Commit+Tutorial

  12. 3layer Tecnologia [Atlassian Partner]

    Dec 15, 2011

    Hi all,

    I configured the Smart Commits, but although worklogs are produced in JIRA, they still come without the text part (the worklog message). See here:

    What is wrong ?

    1. Seb Ruiz

      Dec 15, 2011

      This is a known bug/limitation with Smart Commits at the moment. Please comment/vote on  FE-3757 - Getting issue details... STATUS  to voice your support for having it fixed.

      1. 3layer Tecnologia [Atlassian Partner]

        Dec 15, 2011

        Thanks, Ruiz. I will follow...

    2. Jean-Yves Avenard

      Dec 15, 2011

      You would have to use as commit message:

      TPUP-58 #time 1m #comment Cosmetical code

       

      Edit: I misread, I thought you wanted to add a general comment, not a comment on the time spent

  13. Morgan Fletcher

    Mar 07, 2012

    How can I discover all of the available smart commit commands for Jira and Crucible?

    1. Seb Ruiz

      Mar 07, 2012

      All the currently available smart commit commands are listed above in this document. If there are any amendments, this page will be updated accordingly.

      1. Morgan Fletcher

        Mar 07, 2012

        They can be changed via different states in a custom workflow, correct? I found that "#code-complete" works on our JIRA implementation. How do I discover those states? Are there no #commands for crucible?

        This is how I discovered some of the states:

        FishEye was unable to execute the transition "resolve" on the issue http://jira/browse/XXX-1234 because JIRA responded with the following error: No transitions for issue XXX-1234 (Open) matched the command 'resolve'. Valid transitions are: Close Issue, Start Progress, Code Complete

        1. Seb Ruiz

          Mar 07, 2012

          As described above, the JIRA workflow integration is dependant on your currently set up workflow transition in your JIRA project. Crucible does not, and cannot know about valid commands because available transitions will be different for each issue depending on it's current state. Additionally, the JIRA workflow may change without notice. This means that Crucible will try to find available transitions when requested.

          You can see the valid commands by visiting the JIRA issue and seeing it's available workflow options.

  14. Anonymous

    Mar 19, 2012

    It's useful to note that each line can only contain one smart commit. For example a commit message of 

    KEY-1 +review @john 

    Will link KEY-1 to this commit but will not create a review.

    See FE-3894

  15. Anonymous

    Mar 21, 2012

    Can i use smarts commits on my GIT clone, give the required smart comments and push to the repository indexed by Fisheye/Crucible for a review?

    Or smart commits can be made only on the git repository that is being indexed by Fisheye/Crucible?

    Is there a way to create a review for the commits done on my GIT clone which is not indexed?

    1. Seb Ruiz

      Mar 22, 2012

      You are describing a common git workflow: make commits locally, then push them to a hosted service. FishEye will process smart commits when it indexes them, so those commits must be pushed to whichever repository FishEye is indexing.

      There is no way to create a review from commits on a clone which is not indexed by FishEye, unless you create a patch review.

      1. Anonymous

        Mar 23, 2012

        Thanks, so when i push smart commits from my local clone to a repository that FishEye is indexing, will get a review link in the command line itself?

  16. rajneesh sharma

    Apr 09, 2012

    We are able to see smart commit changes to status, time-logged, comments, but only as anonymous. Has anybody else figured out how to do this without anonymous access enabled in JIRA?

  17. starwarsfan

    Jun 20, 2012

    Hi

    At the moment we are migrating from Trac to Fisheye. Our developers strongly miss a feature: How to link to other revisions on the commit message? In example if you enter something like "... [12345] ..." on your commit message, Trac converts this to a link to the corresponding changeset for revision 12345. How can we achieve this on Fisheye?

    Kind regards,

    Yves

    1. starwarsfan

      Jun 22, 2012

      Nobody with an idea on this problem here? Any hint would be much appreciated!

      Kind regards,

      Yves

    2. Seb Ruiz

      Jun 22, 2012

      You could setup a linker. See the documentation: Linkers

  18. Anonymous

    Jun 21, 2012

    The crucible create review looks like it could be quite handy. But from my playing around I noticed that it only works when there is a single line in the svn commit message. If I have multiple lines then it doesn't work. eg.

    This works:

    Fix a bug +review CR-TEST

     

    This doesn't work:

    Fix a bug

    +review CR-TEST

     

    Is this how it's supposed to work?

     

  19. Rene Verschoor

    Jun 21, 2012

    Yes, from the Advanced command line syntax section above:

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

    1. Anonymous

      Jun 21, 2012

      ah ok. I saw that in the JIRA section and not the crucible section.

      Also I read that as commit command (eg. +review CR-TEST) had to be on one line, but it didn't exclude having additionial lines in the commit log. eg:

      +review CR-TEST

      Lots of comments on the nature of the change

      And test instructions.

       

      Our commit logs tend to be fairly verbose (thus spanning multiple lines) and having the smart commit would have been very useful addition.

       

      1. Seb Ruiz

        Jun 21, 2012

        Having the command of +review ... on a different line does and should work (I do it all the time). The documentation on spanning multiple lines specifies to the following type of syntax:

        Fix a bug +review
CR-TEST

        1. Anonymous

          Jun 26, 2012

          I can't seem to get it to consistently work. I created 2 svn updates with the following text. The first created the review and the second did not.

           

          Trying a autocreated crucible review

          +review CR-FORGETEST

           

           I couldn't find any errors in the logs.

           

          1. Daniel R

            Jun 27, 2012

            Hello Anonymous,

            Please open a support ticket at https://support.atlassian.com so we can further investigate this issue you are experiencing.

            Thank you,

            Daniel

             

  20. Anonymous

    Jul 10, 2012

    Smart commits are very handy but what if I want to create a pre-commit review? Is there a way to achieve similar behavior without actually committing code in the repository? The current IntelliJ IDEA plug-in seems not to allow "Updating an existing review" as shown above. If this is not possible with the "smart commits" as well, then the only option for updating existing pre-commit reviews will be through manually browsing patch files in the web UI which is rather distracting the code-writing process.

     

    1. Daniel R

      Jul 10, 2012

      Crucible has a REST API which you can use to add a patch file to a review (be wary that the documentation is meager):

      http://docs.atlassian.com/fisheye-crucible/latest/wadl/crucible.html#d2e666

  21. Davide Cavestro

    Jul 23, 2012

    So is there any way to send to JIRA a comment with some new lines? (i.e. using some particular escape syntax or whatsoever...) That would let the developer write a complete commit message, hence avoiding the need to return to JIRA and add there a complete comment

    1. EddieW

      Sept 17, 2012

      Ignore my previously response...

      Before Fisheye (B.F.) there was Mylyn and subversion over HTTPS, and it was good.   Developers would include a commit format like:

      IN progress, https://long-link-to-defect-ticket : Summary of ticket.
 
Particular change 1 - details
Particular change 2 - details

      But After Fisheye (A.F.) we found that the format of our commit comments have changed, and we no longer need the multiple lines.

      • Single or multiple lines will look the same in JIRA anyway.  
      • Using the JIRAKEY-123 relates the commit to the work item
      • The ticket name shoudl be the summary.
      • A nice summary of the ticket is visible in fisheye
      TICKET-321 #resolve #time 2h 4m #comment Added the required meothods to foobar class to support actionX. Also renamed ActionY method to support future enhancements.

       

      When someone views that in Fisheye they can see all the files I changed, hover the mouse to see full details of the ticket, and can jump into JIRA if additional details are needed.  Our comments now focus more on another developer picking up the commit, rather then understanding context of the change.



Log a request with our support team.



Raise an issue for our developers.



See answers from the community.



Blog and update our documentation.

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