Associating work items with commits

You can use Git notes to associate work items with Git commits. You can change notes objects without changing the commit. When you change the contents of a notes object that is associated with a commit, a new object is created but the commit association is maintained. Associated notes objects are displayed in the Git log by default and show the work items that are linked to the commit.
Note: Work item links are created by server-side hooks (post-receive) when commits are pushed (for commits and notes). For more information about how to deploy hooks, see Configuring Git and Gerrit server-side hooks.

Git notes objects can contain multiple lines of text – like a commit message text. Rational Team Concert post-receive hooks interpret the line that starts with the text rtc.wi: as the line that contains the work item references. The format is: rtc.wi:wi-number, wi-number. For example, rtc.wi:123, 234, 245.

Note: Non-work item reference lines, such as notes text, can be included with a work item reference line.

Creating links through commit comments

The work item references are extracted from the commit comment (when the commits are pushed). The work item references use a specific format - the comment contains certain keywords followed by the work item numbers. The format is keyword wi-num.

The supported keywords are task, defect, bug, workitem. The following examples are text fragments that are valid work item references when they occur in commit comments:

fix workitem 123 and test
resolve bug 123

This method is the same as the existing way to create commit links in work items (available since Rational Team Concert release 5.0).

Defining new keywords

With Rational Team Concert release 6.0, you can define new keywords in addition to the pre-defined keywords noted above.

New keywords are defined by using a Git configuration property named rtc.wikeywords. The property value is a comma-separated list of keywords. The following command illustrates how to define keywords:

git config --global rtc.wikeywords "ticket,issue"

The above command adds ticket and issue as two new work item keywords. After you define the keywords, you can have comment text that contains fix for ticket 100; 100 is detected as a work item reference number.

You can create the property as a global Git configuration property, so that these keywords are applied across repositories. Otherwise, ignore the --global switch in the above command.

When pushed on the Git server side, the post-receive hook recognizes the work item number from the commit comment and attempts to link with it. If successful, a Note object is created and updated for the commit.

Suppressing detection of work item from Commit comment

With Rational Team Concert release 6.0, you can use Notes objects to hold work item references without adding them in commits comments. For compatibility with an earlier version, this behavior is intact. However, you can suppress this detection by defining a Git configuration property called rtc.ignoreworkitemsfromcomment. The value of this property is a comma-separated list of keywords. The following command illustrates how to define the property: git config --global rtc.ignoreworkitemsfromcomment true

You can create the property as a global Git configuration property if you want to suppress it across repositories. Otherwise, ignore the --global switch in the above command.

Creating links by using Notes

You can create a Git notes object for a commit and mention a work item number as part of the Git notes text. If a notes object exists for a commit, you can use the append or edit subcommand to update the note.

The following example illustrates how to add/create a Git notes object to a commit.

#It is a good practice to fetch the latest notes from the remote repository to avoid merge complications
git fetch origin +refs/notes/commits:refs/notes/commits

#Append the given text to the notes object of the given commit. If no notes object exists, append creates one.
git notes append -m "rtc.wi:123" commit-sha1

#Push the Notes Ref
git push origin refs/notes/commits:refs/notes/commits

The following example illustrates how to edit an existing notes object.

#It is a good practice to fetch the latest notes from the remote repository to avoid merge complications
git fetch origin +refs/notes/commits:refs/notes/commits

#To edit, you can use the following command, which opens an editor, where in you can add a line "rtc.wi:123"
git notes edit commit-sha1

#Push the Notes Ref
git push origin refs/notes/commits:refs/notes/commits

Removing links

The following example illustrates how to delete and push a Git notes object, which removes the commit link from all work items that are mentioned in the Git notes text.

#It is a good practice to fetch the latest notes from the remote repository to avoid merge complications
git fetch origin +refs/notes/commits:refs/notes/commits

#Delete the notes object itself.
git notes remove commit-sha1

#Push the Notes Ref
git push origin refs/notes/commits:refs/notes/commits

The following example illustrates how to remove a work item number from Git notes text, which unlinks the notes object with a specific work item only.

#It is a good practice to fetch the latest notes from the remote repository to avoid merge complications
git fetch origin +refs/notes/commits:refs/notes/commits

#To edit, you can use the following command, which opens an editor, where in you can remove the desired work item reference.
git notes edit commit-sha1

#Push the Notes Ref
git push origin refs/notes/commits:refs/notes/commits

Modifying links

The following example illustrates how to add or remove a work item number from Git notes text then push the notes object.

#It is a good practice to fetch the latest notes from the remote repository to avoid merge complications
git fetch origin +refs/notes/commits:refs/notes/commits

#To edit, you can use the following command, which opens an editor, where in you can change the desired work item number.
git notes edit commit-sha1

#Push the Notes Ref
git push origin refs/notes/commits:refs/notes/commits

Automatic un-linking when history is changed

When a (force) push operation results in a move back in the history of a branch (removes commits from the current branch), the removal is detected and removed automatically if the removed commits are not part of another branch. Similarly, when a (force) push operation results in a move back in the history of a branch and adds newer commits, the removal of some commits and addition of newer commits are detected. The corresponding links are severed and/or created, respectively.

Note: Avoid altering history, especially when commits are already pushed to a remote repository. You can use process enforcement and permission checks to restrict users from altering history. For more information, see Defining Git-related permissions and preconditions.

Process Governance for Notes

You can control who can push Note objects (allow Notes changes to be accepted only from certain roles).

To avoid accidental unlinking of commit links with work items, you can limit the roles that can change notes by creating a Ref Mapping for the Notes ref (refs/notes/commits). For more information, see Understanding the Git Integration features in Rational Team Concert 5.0


video icon Watch videos

CLM playlist
Jazz.net channel
User Education channel

learn icon Learn more

CLM learning circle
Agile learning circle
Learning circles

ask icon Ask questions

Jazz.net forum
developerWorks forums

support icon Get support

Support Portal
Deployment wiki
Support blog