MERGEREQUEST
Find the commands you can use to manage merge requests with the Unity Version Control CLI.
Read time 17 minutesLast updated 8 hours ago
Description
Creates, edits, and deletes merge requests, and manages their comments, reviewers, review status, and email subscriptions. A merge request is a request to merge a source branch into a destination branch after a review.
cm mrcm mergerequestSubcommand | Alias |
|---|---|
| |
| |
| |
| |
Usage
Use the following syntax to create a merge request:
cm mergerequest create <brspec> <title> --destination=<brspec> [--mergerequeststatus=<mr_status_name>] [--users=<users_list>] [--groups=<groups_list>] [--description=<text> | --descriptionfile=<file>] [--format=<str_format>] [--repository=<rep_spec>]
Use the following syntax to edit a merge request:
cm mergerequest edit <id> [--title=<title>] [--description=<text> | --descriptionfile=<file>] [--destination=<brspec>] [--mergerequeststatus=<mr_status_name>] [--mergechangeset=<csetspec>] [--repository=<rep_spec>]
Use the following syntax to delete one or more merge requests:
cm mergerequest delete <id> [<id> ...] [--repository=<rep_spec>]
Use the following syntax to add a comment:
cm mergerequest comment add <mr_id> (-c=<str_comment> | -commentsfile=<comments_file>) [(--path=<serverpath> | --revision=<revspec>) [--line=(<line>|<first>-<last>) | --location=<kind>:<text>] [--changeset=<csetspec>] [--type=(Change|Question|Comment)]] [--format=<str_format>] [--repository=<rep_spec>]
Use the following syntax to reply to a comment:
cm mergerequest comment reply <comment_guid> (-c=<str_comment> | -commentsfile=<comments_file>) [--discard] [--format=<str_format>] [--repository=<rep_spec>]
Use the following syntax to edit a comment:
cm mergerequest comment edit <comment_guid> (-c=<str_comment> | -commentsfile=<comments_file>) [--repository=<rep_spec>]
Use the following syntax to delete one or more comments:
cm mergerequest comment delete <comment_guid> [<comment_guid> ...] [--repository=<rep_spec>]
Use the following syntax to mark a change request as applied:
cm mergerequest comment apply <comment_guid> --changeset=<csetspec> [--repository=<rep_spec>]
Use the following syntax to mark a change request as not applied:
cm mergerequest comment unapply <comment_guid> [--repository=<rep_spec>]
Use the following syntax to add reviewers to a merge request:
cm mergerequest reviewer add <mr_id> [--users=<users_list>] [--groups=<groups_list>] [--repository=<rep_spec>]
Use the following syntax to remove reviewers from a merge request:
cm mergerequest reviewer remove <mr_id> [--users=<users_list>] [--groups=<groups_list>] [--repository=<rep_spec>]
Use the following syntax to list the reviewers of a merge request:
cm mergerequest reviewer list <mr_id> [--format=<str_format> | --xml[=<output_file>]] [--encoding=<name>] [--repository=<rep_spec>]
Use the following syntax to set your own review status:
cm mergerequest review <mr_id> --reviewed | --rework-required | --under-review [-c=<str_comment> | -commentsfile=<comments_file>] [--repository=<rep_spec>]
Use the following syntax to ask reviewers to review the merge request again:
cm mergerequest review <mr_id> --re-request (--all | [--users=<users_list>] [--groups=<groups_list>]) [--repository=<rep_spec>]
Use the following syntax to merge a merge request:
cm mergerequest merge <mr_id> [--merge] [-c=<str_comment> | -commentsfile=<comments_file>] [--repository=<rep_spec>]
Use the following syntax to subscribe to the emails of a merge request:
cm mergerequest subscribe <mr_id> [--repository=<rep_spec>]
Use the following syntax to unsubscribe from the emails of a merge request:
cm mergerequest unsubscribe <mr_id> [--repository=<rep_spec>]
Use the following syntax to check your subscription to a merge request:
cm mergerequest subscription <mr_id> [--format=<str_format>] [--repository=<rep_spec>]
Options
cm mergerequestArgument | Description |
|---|---|
| With |
| With |
| The merge request ID or GUID. |
| The GUID of a comment. |
Use the following options with , , and .
createeditmergeOption | Description |
|---|---|
| The branch to merge into. Required with |
| Sets the status of the merge request: |
| Used with |
| Used with |
| Sets the description of the merge request. Refer to Remarks for more information. |
| Reads the description from the specified file. Use |
| Used with |
Use the following options with and its subcommands. and also work with and .
comment-c-commentsfilereviewmergeOption | Description |
|---|---|
| The text of a comment or reply. |
| Reads the text of a comment from the specified file. Use |
| Used with |
| Used with |
| Used with |
| Used with |
| Used with |
| With |
| Used with |
Use the following options with and .
reviewerreviewOption | Description |
|---|---|
| A comma-separated list of users. With |
| A comma-separated list of groups. Works the same way as |
| Used with |
| Used with |
| Used with |
| Used with |
| Used with |
Use the following options with several subcommands.
Option | Description |
|---|---|
| Used with |
| Sets the default repository. Use it to manage merge requests on a server other than the one your workspace uses, or when you don't have a workspace. For more information about repository specs, refer to objectspec. |
Help
Remarks
To create a merge request, set the source branch, a title, and the destination branch with . To edit or delete a merge request, set its ID or GUID.
--destinationThe following table describes the outcome of each command.
Command | Outcome |
|---|---|
| Prints the ID of the new merge request. To print its GUID instead, or both, use |
| Prints nothing if there are no errors. |
The description is the text that the desktop application shows at the top of the merge request. With , replaces the description, or adds one if the merge request has none. An empty value, , clears the description. If you set both and , the file takes precedence.
edit--description--description=--description--descriptionfileIf the command creates the merge request but can't add its description, it does the following:
- Shows the error with the merge request ID.
- Prints the ID, or the output.
--format - Exits with an error code.
Comment on a merge request
comment add--path--revision- To comment on a line or a range of lines, add . Lines count from 1, and a range includes its first and last lines, so
--linecovers lines 12 to 18.12-18 - To comment on another location, such as a point in an image, add . You can't combine it with
--location.--line - To comment on the whole file, don't add or
--line.--location
The following rules apply to the file:
- With , if the merge request deletes the file, the comment goes on the base revision, which is the one the diff shows.
--path - With , the revision must appear in the diff of the merge request, or in the diff of the changeset that you set with
--revision. Use the new revision of an added or changed file, or the base revision of a deleted file.--changeset
The command prints the GUID of the new comment, which , , , , and take.
replyeditdeleteapplyunapply--locationcm<kind>:<text><kind>cm find changereviewcomment--format={location}A reply goes on the same file, line, and changeset as the comment it replies to. changes only the text of the comment. If the comment is the description of the merge request, it stays the description. If can't delete one of the comments, it reports the error and deletes the rest.
comment editcomment deleteTo read the comments of a merge request, use and set to the merge request ID. For example:
cm find changereviewcommentreviewidcm find changereviewcomment "where reviewid=1367 on repositories 'myrep@myserver:8084'" --format="{guid} {type} line {line}: {comment}"
comment applycomment unapply- You can mark only comments of type .
Change - The changeset can be any changeset in the repository, not only one under review.
- To apply a change request in a different changeset, run first.
comment unapply
A check-in or whose comment contains also marks the change request as applied in that changeset.
cm changeset editcomment[apply-change:<comment_guid>]Manage reviewers and review status
reviewer addreviewer removereviewer listUnder reviewReviewedRework required--xml<Reviewers> <Reviewer> <User>maria</User> <Status>Reviewed</Status> <Type>user</Type> </Reviewer></Reviewers>
To set your own review status with , you must be a reviewer of the merge request, a member of a reviewer group, or a server administrator. Use only one of , , , or . doesn't accept a comment.
review--reviewed--rework-required--under-review--re-request--re-requestManage email subscriptions
subscribeunsubscribeUnity Version Control automatically subscribes the following users to a merge request:
- The owner
- The reviewers
- Users who comment on the merge request
- Users that someone mentions in a comment
Use to follow a merge request that you have no role in, or to get its emails again after you unsubscribe. After you unsubscribe, Unity Version Control subscribes you again if any of the following happens:
subscribe- You comment on the merge request.
- Someone mentions you in a comment.
- Someone adds you, or a group you belong to, as a reviewer again.
Unity Version Control sends merge request emails only while review emails are enabled for the repository and your notification settings include reviews. If either is off, your subscription doesn't change.
subscription--formatname: valuesubscribed: yesreason: owneremails: enabled
The field prints one of the following values.
reasonValue | Meaning |
|---|---|
| You own the merge request. |
| You're a reviewer of the merge request. |
| You commented on the merge request. |
| Someone mentioned you in a comment. |
| You subscribed yourself. |
| You unsubscribed yourself. |
| You have no subscription of your own. You can still get the emails as a member of a reviewer group. |
| A reason that this version of the client doesn't recognize. |
Merge a merge request
merge--mergeThe merge runs on the server, like , so you don't need a workspace. For more information, refer to merge.
cm merge <source> --to=<destination>mergecm mergemergemerge--mergeMerge merge request <mr_id> from br:<branch>: <title>Find merge requests
To list merge requests, use with a clause. Use the following fields for common searches:
cm find mergerequestwhere- To find merge requests by status, use , such as
mergerequeststatus.mergerequeststatus = 'Open' - To find your own merge requests, use .
owner = 'me' - To find the merge requests that you review, use .
reviewer = 'me' - To find the merge requests for a source branch, use , such as
target.target = 'br:/main/fix-login-crash' - To find the merge requests that merge into a branch, use , such as
destination.destination = 'br:/main'
When you run outside a workspace, add an clause to the query to set the repositories to search, such as . For more information about queries, refer to find.
cm findon repositorieson repositories 'myrep@myserver:8084'cm findFormat the output
With , , and , use the following parameters in to print the ID or GUID of the merge request or comment that the command creates.
createcomment addcomment reply--formatParameter | Description |
|---|---|
| The ID of the new merge request or comment. |
| The GUID of the new merge request or comment. |
With , use the following parameters in to set what the command prints for each reviewer. Without , the command prints the name, status, and type of each reviewer in columns.
reviewer list--format--formatParameter | Description |
|---|---|
| The name of the reviewer. |
| The status that the reviewer set: |
| Whether the reviewer is a |
| Inserts a tab. |
| Inserts a new line. |
With , use the following parameters in to set what the command prints about your subscription.
subscription--formatParameter | Description |
|---|---|
| Whether you're subscribed: |
| Why you're subscribed or not. For the values, refer to Manage email subscriptions. |
| Whether review emails are enabled for the repository: |
| Inserts a tab. |
| Inserts a new line. |
Examples
The following example creates a merge request to merge into :
/main/task001/maincm mergerequest create /main/task001 "Add the login screen" --destination=/main
The following example creates a draft merge request with reviewers, and prints its ID and GUID:
cm mergerequest create /main/task001 "Add the login screen" --destination=/main --mergerequeststatus=Draft --users=maria --groups=developers --format="{0} -> {1}"
The following example creates a merge request with a description from a file:
cm mr create /main/task001 "Add the login screen" --destination=/main --descriptionfile=description.md
The following example changes the destination branch of merge request 1367:
cm mergerequest edit 1367 --destination=/main/release
The following example marks merge request 1367 as merged, and links it to the merge changeset:
cm mr edit 1367 --mergerequeststatus=Merged --mergechangeset=cs:5678
The following example deletes merge requests 1367, 1368, and 1369:
cm mergerequest delete 1367 1368 1369
The following example posts a change request on line 42 of in merge request 1367:
/Assets/Scripts/PlayerController.cscm mergerequest comment add 1367 -c="Rename this" --path=/Assets/Scripts/PlayerController.cs --line=42 --type=Change
The following example posts a change request on lines 42 to 58 of :
/Assets/Scripts/PlayerController.cscm mr comment add 1367 -c="Extract a method" --path=/Assets/Scripts/PlayerController.cs --line=42-58
The following example posts a comment on the whole file:
/art/logo.pngcm mr comment add 1367 -c="Use the new logo" --path=/art/logo.png
The following example marks a change request as applied in changeset 1520:
cm mergerequest comment apply 27658884-5dcc-49b7-b0ef-a5760ae740a3 --changeset=cs:1520
The following example adds a reviewer to merge request 1367:
cm mr reviewer add 1367 --users=sam
The following example sets your review status to , with a comment:
Reviewedcm mergerequest review 1367 --reviewed -c="Looks good"
The following example asks every reviewer of merge request 1367 to review it again:
cm mr review 1367 --re-request --all
The following example prints what the merge of merge request 1367 would do, without merging:
cm mergerequest merge 1367
The following example merges merge request 1367 with the default comment:
cm mr merge 1367 --merge
The following example merges merge request 1367 and sets the comment of the merge changeset:
cm mr merge 1367 --merge -c="Add the login screen"
The following example shows your subscription to merge request 1367:
cm mr subscription 1367 --format="{subscribed} {reason}"
The following examples find merge requests:
-
Your open merge requests:cm find mergerequest "where mergerequeststatus = 'Open' and owner = 'me' on repositories 'myrep@myserver:8084'"
-
The open merge requests that you're a reviewer of:cm find mergerequest "where reviewer = 'me' and mergerequeststatus = 'Open' on repositories 'myrep@myserver:8084'"
-
The merge requests for branch:
/main/fix-login-crashcm find mergerequest "where target = 'br:/main/fix-login-crash' on repositories 'myrep@myserver:8084'" -
The merge requests that merge into:
/maincm find mergerequest "where destination = 'br:/main' on repositories 'myrep@myserver:8084'"