# AZD: Branches and commits from work items

> For the complete documentation index, see [llms.txt](https://edgafner.github.io/llms.txt).

## Create a branch from a work item

Procedure: Create a branch

1. Right-click a work item in the AZD Boards list, a project page, a card or the work item's details tab, and select Create Branch….

2. In the Create Branch for #<id> dialog, check the Branch name. It is filled in from the branch name template.

![Create Branch dialog with the branch name, the Checkout branch option and the Start from option](images/azd_boards_create_branch.png)

3. The branch starts from the current branch. To start from another one, select Start from and choose a local branch, remote branch or tag. The note under it says where the branch will start.

In a project with several repositories, select the Repository, or All repositories.

4. Leave Checkout branch selected to switch to the new branch, and click Create.

* If the branch already exists locally or on the remote, the dialog offers to check it out instead. AZD does not fetch first.

* Create Branch… is disabled while a rebase, merge, cherry-pick or revert is in progress, and in an empty repository.

* AZD does not link the branch to the work item in Azure DevOps.

When you check out a branch for a work item that has not started yet, AZD asks whether to move it to the in-progress state. Click Move to move it, or Never Ask to stop asking.

Set the branch name template and what happens to the work item's state in the Development group of [Boards and Work Items settings](azd-settings-configuration.html#boards-and-work-items).

## Current work item in the status bar

When the name of the current branch contains a work item ID, the status bar shows the work item, for example `#412`. AZD reads the ID at the position the branch name template puts it. It ignores release, hotfix, Dependabot and Renovate branches, and numbers that look like dates.

![Status bar showing the current work item, #412](images/azd_boards_status_bar.png)

Click it to open the work item. If the branch name matches several work items, select one in the list, or select Ignore this branch to hide the widget for this branch until you restart the IDE. To hide the widget, right-click the status bar and clear Current Work Item.

## Start commit messages with the work item

When the current branch belongs to one work item, a new commit message starts with its reference: `#412` when the repository is in Azure Repos, or `AB#412` when it is not. Azure DevOps uses this reference to link the commit to the work item.

AZD does not fill in the message when:

* The message is not empty, for example when it comes from a Git commit template or a merge.

* The project mixes Azure Repos and other remotes.

* The Git staging area is enabled.

To turn it off, clear Start new commit messages with the current work item in the Development group of [Boards and Work Items settings](azd-settings-configuration.html#boards-and-work-items).

## Add work items to a commit message

Reference several work items in a commit message, from a template or with AI. The AZD button (the AZD logo) appears in the commit message toolbar when Enable AI assistance is selected and the Commit message prompt is enabled in `Settings | Version Control | AZD | AI Settings`; see [Configure prompts](azd-ai.html#configure-prompts). The work item option also needs Enable work item commit message action, which is on by default.

Procedure: Write a commit message from work items

1. In the Commit tool window, click the arrow next to the AZD button in the commit message toolbar and select Select Work Item....

2. In the Select Work Item for Commit Message dialog, select one or more work items. By default the list shows your own work items and hides those in the Done, Closed, Removed and Resolved states. Clear Only my work items or use the state filter to see more.

3. In Generate with AI, select None - Use template only to fill in the template, or select an AI provider to write the message from the work items and your changes.

4. Click Generate Message.

Change the template in `Settings | Version Control | AZD | Boards and Work Items`, in the Commit Message Template group. The default template is `{id} - {title}`; the placeholders are `{id}`, `{title}`, `{type}` and `{state}`. Max work items per commit limits the selection (5 by default).

To generate a commit message from your changes only, see [Generate commit messages](ai-title-description-generation.html#commit-message).

## Use work items as IDE tasks

With the Issue Trackers plugin (formerly Task Management), you can open Azure DevOps work items as IDE tasks and switch context between them. AZD adds an AzureDevOps server type to it. The Issue Trackers plugin is not bundled with every IDE; install it from JetBrains Marketplace if your IDE lacks it.

Procedure: Add Azure DevOps as a task server

1. Open `Settings | Tools | Tasks | Servers`.

2. Click + and select AzureDevOps.

3. Fill in Host (`https://dev.azure.com` by default), Organization and PAT token, and click Test.

4. After a successful test, select the project in Project. Include issues not assigned to me is selected by default; clear it to list only the work items assigned to you.

5. Click OK.

Open a work item as a task with `Tools | Tasks & Contexts | Open Task…`. To change its state in Azure DevOps at the same time, select Update issue state in the Open Task dialog.

While a work item is the active task, AI-generated commit messages refer to it. With the default prompt, they start with the work item ID. See [Generate commit messages](ai-title-description-generation.html#commit-message).

## See also

### Related topics

[AZD: Boards and work items](azd-boards.html) [Boards and Work Items settings](azd-settings-configuration.html#boards-and-work-items) [Generate commit messages](ai-title-description-generation.html#commit-message)

### Useful resources

[Link GitHub commits with AB#ID (Microsoft Learn)](https://learn.microsoft.com/en-us/azure/devops/boards/github/link-to-from-github) [Tasks and contexts (IntelliJ IDEA help)](https://www.jetbrains.com/help/idea/managing-tasks-and-context.html)