Specifying work items in Git Notes

Edit online

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. This enables linking and unlinking work items from commits without changing the commits.

Git notes objects can contain multiple lines of text – like a commit message text. IBM® Engineering Workflow Management 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.
Note: When you use post-receive hooks to link work items while pushing commits, notes are created on the remote repository for those commits if they do not already exist.
To enable Git notes to be created, set the Git configuration properties user.name and user.email for the operating system user who owns the Git process with the following commands:
$> git config -global user.name “TestUser”
$> git config -global user.email TestUser@somedomain.com

If these properties are not set, notes are not created when a commit is pushed.

You can still create notes in the client and push them. The following sections contain examples on how to create, modify and remove work item links through Git notes. You must fetch the notes from the remote repository before performing any other operation related to Git notes.

Creating links

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

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.