The .doing-cli-config.yml config file
When running a command doing
searches for YAML config file named .doing-cli-config.yml
. This file is required and used to link issues to a repository (see discussion).
Required parameters
The config must contain the following parameters (in lowercase):
Parameter | Description |
---|---|
organization |
Azure DevOps organization URL. You can quickly find the organization in your devops url, right after https://dev.azure.com. Example: https://dev.azure.com/organization_name. |
project |
Name of the project. You can quickly find the organization in a devops url, right after the organization url. Example: The project for https://dev.azure.com/your_organization/your_project/... is your_project. |
team |
The name of your team. You can quickly find it when navigating on Azure Devops to Boards > Boards. Example: The team in https://dev.azure.com/organization_name/project_name/_boards/board/t/my_team/Stories is my_team. |
area |
The area path assigned to work items. You can find it by going to a work item (Azure Devops > Boards > Work items) and copying the Area field. This corresponds to the work item field System.AreaPath. More about area and iteration paths. |
iteration |
The iteration path assigned to work items. You can find it going by to a work item (Azure Devops > Boards > Work items) and copying the Iteration field. This corresponds to the work item field System.IterationPath. More about area and iteration paths. |
Example .doing-cli-config.yml
:
# .doing-cli-config.yml
organization: 'https://dev.azure.com/organization_name'
project: 'project_name'
team: 'team-name'
area: 'organization_name\repo_name\area_name'
iteration: 'organization_name\team_name\iteration_name'
Optional parameters
The config can also contain some optional parameters that are not required to be set. Here's a summary:
Optional Parameter | Description |
---|---|
verbose_shell |
Set to 'true' to print every shell command doing runs for you in the background. Meant for debugging and interested developers. Default is 'false'. |
user_aliases |
A list of user aliases that you can use when specifying reviewers or assignees. Note that the @me alias is always available. |
default_reviewers |
The default reviewers assigned when creating pull requests. Space separated list of user emails (case sensitive). Find your own with az ad signed-in-user show --query 'mail' . |
custom_states |
A dictionary of work item states or lists of states to use when filtering work items with doing list --state "state" . |
defaults |
Allows you to overwrite defaults of command options. See explanation below. |
merge_strategy |
Azure devops supports pull requests with rebase (see blogpost). Should be one of "basic merge", "squash merge", "rebase and fast-forward", "rebase with merge commit". If specified, it will update the policies on a repository level to only allow that merge strategy. |
encoding |
The encoding used to parse the response of terminal commands. This is auto-detected by default but can be set explicitly in case you have encoding trouble. |
Example .doing-cli-config.yml
with all optional parameters set:
# .doing-cli-config.yml
# ... other required parameters ...
verbose_shell: true
encoding: 'UTF-8'
user_aliases:
john: 'John.Doe@company.com'
jane: 'Jane.Doe@email.net'
default_reviewers: 'john.doe@domain.com'
custom_states:
removed: Removed
resolved: [Resolved, Closed]
defaults:
DOING_LIST_STATE: all
merge_strategy: "rebase and fast-forward"
Setting verbose_shell
Set to 'true' to print every shell command doing
runs for you in the background. Meant for debugging and interested developers. Default is 'false'.
# .doing-cli-config.yml
verbose_shell: true
Setting encoding
The encoding used to parse the response of terminal commands. This is auto-detected by default but can be set explicitly in case you have encoding trouble.
# .doing-cli-config.yml
encoding: 'UTF-8'
Setting user_aliases
Anywhere you can specify assignee
or reviewer
, you can fill in user email adress. These are case-sensitive, and lenghty, so you can also choose to define a set of user aliases:
# .doing-cli-config.yml
user_aliases:
john: 'John.Doe@company.com'
jane: 'Jane.Doe@email.net'
Now you can use aliases like:
doing issue create --assignee "john"
Setting default_reviewers
You might have a project where all pull requests have the same set of reviewers. Instead of using the lengthy doing pr create --reviewers 'email1@domain.com email2@domain.com'
, you can set a default set of reviewers in the .doing-cli-config.yml
(see config) by specifying default_reviewers
. For example:
# .doing-cli-config.yml
default_reviewers: 'email1@domain.com email2@domain.com'
You can also use the aliases specified in user_aliases
to specify the default_reviewers
.
Setting custom_states
When listing work items you can filter them by state with doing list --state "state"
. doing-cli
includes some default options for this filter:
open
: state not in['Resolved','Closed','Done','Removed']
closed
: state in['Resolved','Closed','Done']
all
: state different than'Removed'
You can overwrite these or specify your own custom state filters. For example:
# .doing-cli-config.yml
custom_states:
removed: Removed
resolved: [Resolved, Closed]
Which can be used as:
doing list --state "removed"
Setting defaults
For every doing
command, you can use --help
to see any default for an option (if applicable), as well as the name (in capital letters) of that option, listed after 'env var'. For example, doing issue create --help
has an option named DOING_ISSUE_CREATE_LABEL
(in the help, listed as [env var: DOING_ISSUE_CREATE_LABEL]
).
You can use those variable names to set different defaults for commands in your .doing-cli-config.yml
file.
Here's an example .doing-cli-config.yml
:
# .doing-cli-config.yml
# ... other settings ...
defaults:
DOING_LIST_STATE: all
DOING_WORKON_TYPE: Bug
DOING_LIST_LABEL: "some_tag another_tag something"
This is a great way to set defaults for your entire team. If you would like to set personal defaults you can choose to use environment variables instead.
Priority of settings
doing
uses the following order of priority:
- Options set directly on the command list, f.e.:
doing list --state all
- Options set as environment variable, f.e.:
export DOING_LIST_STATE=all
- Options set in the
.doing-cli-config.yml
file, f.e.: settingDOING_LIST_STATE: all
underdefaults
Setting merge_strategy
Azure devops supports 4 different types of merge strategies (blogpost). You can set a policy to allow a specific set of 1 or more strategies for each repository you work on, using the Azure Devops admin panel or az repos policy merge-strategy
.
Often a team agrees on a single merge strategy for all PRs. doing
makes it easy to set the merge-strategy for everyone in the .doing-cli-config.yml
file. For example:
# .doing-cli-config.yml
# ... other settings ...
merge_strategy: "rebase and fast-forward"
These are the merge strategies allowed:
Merge strategy | Description |
---|---|
basic merge | Basic merge (no fast-forward) - Preserves nonlinear history exactly as it happened during development. |
squash merge | Individual commits that made up the pull request are combined into a single commit onto the target without a merge commit. |
rebase and fast-forward | Creates a linear history by replaying the source branch commits onto the target without a merge commit. |
rebase with merge commit | Creates a semi-linear history by replaying the source branch commits onto the target and then creating a merge commit. |
If specified, everytime before a PR is created, doing
will check and if needed update the policies on a repository level to only allow that merge strategy to the default branch (often master
).
If not specified, doing
will not check any merge policies and a PR will be created with whatever the default policies in your azure devops organization/project are. Often this is a "basic merge".