Documentation

Unity Version Control

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 mr
is an alias of
cm mergerequest
. The following subcommands also have aliases.

Subcommand

Alias

create
mk
comment add
mk
comment delete
rm
reviewer list
ls

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 mergerequest
takes the following arguments.

Argument

Description

brspec
With
create
, the branch that is the source of the merge request. For more information about branch specs, refer to objectspec.
title
With
create
, the title of the new merge request.
id
,
mr_id
The merge request ID or GUID.
comment_guid
The GUID of a comment.
comment add
and
comment reply
print it, and
cm find changereviewcomment --format={guid}
lists it.
Use the following options with
create
,
edit
, and
merge
.

Option

Description

--destination
The branch to merge into. Required with
create
. With
edit
, sets a new destination branch.
--mergerequeststatus
Sets the status of the merge request:
Draft
,
Open
,
Closed
, or
Merged
. The default is
Open
.
--mergechangeset
Used with
edit
and
--mergerequeststatus=Merged
. Links the merge request to the changeset that resulted from the merge.
--title
Used with
edit
. Sets a new title.
--description
Sets the description of the merge request. Refer to Remarks for more information.
--descriptionfile
Reads the description from the specified file. Use
--descriptionfile=-
to read it from the standard input.
--merge
Used with
merge
. Runs the merge. Without
--merge
, the command prints the merge status and the operations, and changes nothing.
Use the following options with
comment
and its subcommands.
-c
and
-commentsfile
also work with
review
and
merge
.

Option

Description

-c
The text of a comment or reply.
comment add
,
comment reply
, and
comment edit
require
-c
or
-commentsfile
. With
review
, attaches a comment to the status change. With
merge --merge
, sets the comment of the changeset that the merge creates.
-commentsfile
Reads the text of a comment from the specified file. Use
-commentsfile=-
to read it from the standard input.
--path
Used with
comment add
. Sets the file to comment on, as a server path, such as
/Assets/Scripts/PlayerController.cs
.
--revision
Used with
comment add
. Sets the revision to comment on, as a revision spec, such as
revid:1234
.
--line
Used with
--path
or
--revision
. Sets the line to comment on, such as
42
, or a range of lines, such as
12-18
.
--location
Used with
--path
or
--revision
. Sets a location other than a line, such as a point in an image, in the form
<kind>:<text>
.
--type
Used with
comment add
and
--path
or
--revision
. Sets the type of comment:
Change
,
Question
, or
Comment
. The default is
Change
, which is a change request.
--changeset
With
comment add
and
--path
or
--revision
, shows the comment in the diff of the specified changeset instead of the diff of the whole branch. With
comment apply
, sets the changeset that applies the change request. The changeset must be in the repository of the merge request.
--discard
Used with
comment reply
. Discards the change request, so it's no longer pending.
Use the following options with
reviewer
and
review
.

Option

Description

--users
A comma-separated list of users. With
create
and
reviewer add
, adds them as reviewers. With
reviewer remove
, removes them as reviewers. With
review --re-request
, asks them to review again. Accepts the special user
me
.
--groups
A comma-separated list of groups. Works the same way as
--users
.
reviewer add
and
reviewer remove
require
--users
,
--groups
, or both.
--reviewed
,
--rework-required
,
--under-review
Used with
review
. Sets your own review status.
--re-request
Used with
review
. Sets reviewers back to
Under review
. Requires
--all
, or
--users
,
--groups
, or both.
--all
Used with
--re-request
. Asks every reviewer to review the merge request again.
--xml
Used with
reviewer list
. Prints the output in XML format, to the standard output or to a file with
--xml=<output_file>
. You can't combine it with
--format
.
--encoding
Used with
--xml
. Sets the encoding of the XML output, such as
utf-8
.
Use the following options with several subcommands.

Option

Description

--format
Used with
create
,
comment add
,
comment reply
,
reviewer list
, and
subscription
. Sets the format of the output. Refer to Remarks for more information.
--repository
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
--destination
. To edit or delete a merge request, set its ID or GUID.
The following table describes the outcome of each command.

Command

Outcome

create
Prints the ID of the new merge request. To print its GUID instead, or both, use
--format
. The merge request has the status
Open
, unless you set
--mergerequeststatus
, and each reviewer starts with the review status
Under review
.
edit
,
delete
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
edit
,
--description
replaces the description, or adds one if the merge request has none. An empty value,
--description=
, clears the description. If you set both
--description
and
--descriptionfile
, the file takes precedence.
If 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
    --format
    output.
  • Exits with an error code.

Comment on a merge request

comment add
posts a comment on the whole merge request. To comment on a file, set the file with
--path
or
--revision
, and then do one of the following:
  • To comment on a line or a range of lines, add
    --line
    . Lines count from 1, and a range includes its first and last lines, so
    12-18
    covers lines 12 to 18.
  • To comment on another location, such as a point in an image, add
    --location
    . You can't combine it with
    --line
    .
  • To comment on the whole file, don't add
    --line
    or
    --location
    .
The following rules apply to the file:
  • With
    --path
    , if the merge request deletes the file, the comment goes on the base revision, which is the one the diff shows.
  • With
    --revision
    , the revision must appear in the diff of the merge request, or in the diff of the changeset that you set with
    --changeset
    . Use the new revision of an added or changed file, or the base revision of a deleted file.
The command prints the GUID of the new comment, which
reply
,
edit
,
delete
,
apply
, and
unapply
take.
--location
stores the location exactly as you write it.
cm
only checks that it has the form
<kind>:<text>
, where
<kind>
contains only lowercase letters. Clients that read the comment decide what the location means. To print the location of a comment, use
cm find changereviewcomment
with
--format={location}
.
A reply goes on the same file, line, and changeset as the comment it replies to.
comment edit
changes only the text of the comment. If the comment is the description of the merge request, it stays the description. If
comment delete
can't delete one of the comments, it reports the error and deletes the rest.
To read the comments of a merge request, use
cm find changereviewcomment
and set
reviewid
to the merge request ID. For example:
cm find changereviewcomment "where reviewid=1367 on repositories 'myrep@myserver:8084'" --format="{guid} {type} line {line}: {comment}"
comment apply
marks a change request as applied in a changeset, and
comment unapply
marks it as not applied again. The following rules apply:
  • 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
    comment unapply
    first.
A check-in or
cm changeset editcomment
whose comment contains
[apply-change:<comment_guid>]
also marks the change request as applied in that changeset.

Manage reviewers and review status

reviewer add
adds the reviewers that you set, and keeps the existing ones.
reviewer remove
removes the reviewers that you set, and keeps the rest.
reviewer list
prints one line for each reviewer, with the review status that the reviewer set:
Under review
,
Reviewed
, or
Rework required
. With
--xml
, it prints the reviewers in the following structure:
<Reviewers> <Reviewer> <User>maria</User> <Status>Reviewed</Status> <Type>user</Type> </Reviewer></Reviewers>
To set your own review status with
review
, you must be a reviewer of the merge request, a member of a reviewer group, or a server administrator. Use only one of
--reviewed
,
--rework-required
,
--under-review
, or
--re-request
.
--re-request
doesn't accept a comment.

Manage email subscriptions

subscribe
and
unsubscribe
change your own subscription to the emails of a merge request. You can't change other users' subscriptions.
Unity 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
subscribe
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:
  • 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
prints whether you're subscribed, why, and whether review emails are enabled for the repository. Without
--format
, it prints one
name: value
line for each field:
subscribed: yesreason: owneremails: enabled
The
reason
field prints one of the following values.

Value

Meaning

owner
You own the merge request.
reviewer
You're a reviewer of the merge request.
commented
You commented on the merge request.
mentioned
Someone mentioned you in a comment.
manual
You subscribed yourself.
unsubscribed
You unsubscribed yourself.
none
You have no subscription of your own. You can still get the emails as a member of a reviewer group.
other
A reason that this version of the client doesn't recognize.

Merge a merge request

merge
merges the branch of a merge request into its destination branch. You can merge only open merge requests. Without
--merge
, the command only prints the merge status and the operations.
The merge runs on the server, like
cm merge <source> --to=<destination>
, so you don't need a workspace. For more information, refer to merge.
merge
never resolves file conflicts interactively. The command handles files that can be merged automatically. If any conflicts require manual intervention, the command fails and prints the
cm merge
command that merges the destination branch into the merge request branch. Run that command in a workspace to resolve the conflicts manually, then run
merge
again.
merge
uses the comment only with
--merge
. Without a comment, the changeset that the merge creates gets the comment
Merge merge request <mr_id> from br:<branch>: <title>
.

Find merge requests

To list merge requests, use
cm find mergerequest
with a
where
clause. Use the following fields for common searches:
  • To find merge requests by status, use
    mergerequeststatus
    , such as
    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
    target
    , such as
    target = 'br:/main/fix-login-crash'
    .
  • To find the merge requests that merge into a branch, use
    destination
    , such as
    destination = 'br:/main'
    .
When you run
cm find
outside a workspace, add an
on repositories
clause to the query to set the repositories to search, such as
on repositories 'myrep@myserver:8084'
. For more information about
cm find
queries, refer to find.

Format the output

With
create
,
comment add
, and
comment reply
, use the following parameters in
--format
to print the ID or GUID of the merge request or comment that the command creates.

Parameter

Description

{0}
The ID of the new merge request or comment.
{1}
The GUID of the new merge request or comment.
With
reviewer list
, use the following parameters in
--format
to set what the command prints for each reviewer. Without
--format
, the command prints the name, status, and type of each reviewer in columns.

Parameter

Description

{user}
or
{0}
The name of the reviewer.
{status}
or
{1}
The status that the reviewer set:
Under review
,
Reviewed
, or
Rework required
.
{type}
or
{2}
Whether the reviewer is a
user
or a
group
.
{tab}
Inserts a tab.
{newline}
Inserts a new line.
With
subscription
, use the following parameters in
--format
to set what the command prints about your subscription.

Parameter

Description

{subscribed}
or
{0}
Whether you're subscribed:
yes
or
no
.
{reason}
or
{1}
Why you're subscribed or not. For the values, refer to Manage email subscriptions.
{emails}
or
{2}
Whether review emails are enabled for the repository:
enabled
or
disabled
. This is the repository's Code Review Email Trigger. It also prints
disabled
if you can't view that trigger.
{tab}
Inserts a tab.
{newline}
Inserts a new line.

Examples

The following example creates a merge request to merge
/main/task001
into
/main
:
cm 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
/Assets/Scripts/PlayerController.cs
in merge request 1367:
cm 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.cs
:
cm 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
/art/logo.png
file:
cm 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
Reviewed
, with a comment:
cm 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-crash
    :
    cm find mergerequest "where target = 'br:/main/fix-login-crash' on repositories 'myrep@myserver:8084'"
  • The merge requests that merge into
    /main
    :
    cm find mergerequest "where destination = 'br:/main' on repositories 'myrep@myserver:8084'"

Additional resources