Documentation

Unity Version Control

CODEREVIEW

Manage code reviews with the Unity Version Control CLI.
Read time 11 minutesLast updated 13 days ago

Description

Creates, edits, or deletes code reviews, and manages their comments, reviewers, and review status.

Usage

Use the following syntax to create a code review:
cm codereview <spec> <title> [--status=<status_name>] [--assignee=<user_name>] [--users=<user_list>] [--groups=<group_list>] [--description=<text> | --descriptionfile=<file>] [--format=<str_format>] [--repository=<rep_spec>]
Use the following syntax to edit a code review:
cm codereview -e <id> [--status=<status_name>] [--assignee=<user_name>] [--title=<title>] [--description=<text> | --descriptionfile=<file>] [--repository=<rep_spec>]
Use the following syntax to delete one or more code reviews:
cm codereview -d <id> [ ...] [--repository=<rep_spec>]
Use the following syntax to add, reply to, edit, or delete review comments, or to mark a change request as applied or not applied:
cm codereview comment add <review_id> | reply <guid> | edit <guid> | delete <guid> ...cm codereview comment apply <guid> --changeset=<csetspec>cm codereview comment unapply <guid>
Use the following syntax to add, remove, or list the reviewers of a code review:
cm codereview reviewer add | remove <review_id>cm codereview reviewer list <review_id> [--format=<str_format> | --xml[=<output_file>]] [--encoding=<name>]
Use the following syntax to set your own review status, or ask reviewers to review again:
cm codereview review <review_id> --reviewed | --rework-required | --under-reviewcm codereview review <review_id> --re-request (--all | [--users=<list>] [--groups=<list>])
Use the following syntax to subscribe to or unsubscribe from the emails of a code review, or to check your subscription:
cm codereview subscribe | unsubscribe <review_id>cm codereview subscription <review_id> [--format=<str_format>]

Options

Option / Argument

Description

-eEdits the parameters of an existing code review.
-dDeletes one or more existing code reviews. Use a whitespace to separate the code reviews IDs.
--statusSets the new status of a code review. See Remarks for additional information.
--users
A comma-separated list of users. When you create a code review, sets its reviewers. With
reviewer add
,
reviewer remove
, and
review --re-request
, sets the users to act on. Accepts the special user
me
.
--groups
A comma-separated list of groups. Works the same way as
--users
.
--title
Used with
-e
, sets the new title of a code review.
--assigneeSets the new assignee of a code review. Can't be combined with
--users
or
--groups
.
--description
Used when you create a code review, or when you edit one with
-e
. Sets the description of the code review. Refer to Remarks for additional information.
--descriptionfile
Used when you create a code review, or when you edit one with
-e
. Reads the description from the specified file. Use
--descriptionfile=-
to read it from the standard input.
--formatRetrieves the output message in a specific format. See Remarks for additional information.
--repositorySets the repository to be used as default. (Use 'cm help objectspec' to learn more about repository specs.)
--path
Used with
comment add
. Posts the comment on a line of the specified file. Specify the file as a server path, such as
/src/foo.cs
, and the line with
--line
. For a file that the code review deletes, the comment goes on the base revision, which is the one the diff shows. In a shelve review, the file must be one of the shelve's changes.
--revision
Used with
comment add
. Posts the comment on a line of the specified revision. Specify the revision as a revision spec, such as
revid:1234
, and the line with
--line
. The revision must be one that the diff of the code review, or of
--changeset
, shows: the new revision of an added or changed file, or the base revision of a deleted file.
--line
Used with
--path
or
--revision
. Sets the line of the file to comment on. Lines count from 1.
--type
Used with
comment add
and
--path
or
--revision
. Sets the type of a comment on a file:
Change
,
Question
, or
Comment
. The default is
Change
, which is a change request.
--changeset
Used 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.
--discard
Used with
comment reply
, discards a change request.
-c
The text of a comment.
-commentsfile
Reads the text of a comment from the specified file. Use
-commentsfile=-
to read it from the standard input.
--reviewed
|
--rework-required
|
--under-review
Used with
review
, sets your own review status. You can add a comment with
-c
.
--re-request
Used with
review
, sets reviewers back to "Under review". Requires
--all
, or
--users
,
--groups
, or both. Doesn't accept a comment.
--all
Used with
--re-request
, asks every reviewer to review 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
.
specIt can be either a changeset spec, a shelve spec or a branch spec. It will be the target of the new code review. (Use 'cm help objectspec' to learn more about changeset or branch specs.)
titleA text string to be used as title of the new code review.
idThe code review identification number. A GUID can be used as well.
review_idThe code review identification number. A GUID can be used as well.
guidThe GUID of a review comment.
comment add
prints it, and
cm find changereviewcomment --format={guid}
lists them.

Help

Remarks

This command allows users to manage code reviews: create, edit, and delete code reviews for changesets or branches.
To create a new code review, a changeset/branch spec and a title are required. The initial status and assignee can be set, too. An ID (or GUID if requested) will be returned as a result.
To edit or delete an existing code review, the target code review ID (or GUID) is required. No messages are displayed if there are no errors.
When you edit a code review,
--status
fails if the code review has no reviewers. Add them with
cm codereview reviewer add
, and each reviewer sets their own status with
cm codereview review
.
The description is the text that the Desktop GUI shows at the top of the code review.
When you edit a code review with
-e
,
--description
works as follows:
  • If the code review has a description,
    --description
    replaces it.
  • If the code review has no description,
    --description
    adds one.
  • An empty value,
    --description=
    , clears the description.
If you set both
--description
and
--descriptionfile
,
--descriptionfile
takes precedence.
If the command creates the code review but can't add its description, it does the following:
  • Shows the error with the code review ID.
  • Prints the ID, or the
    --format
    output.
  • Exits with an error code.
The 'status parameter' must only be one of the following: "Under review" (default), "Reviewed", or "Rework required".
The 'repository' parameter is available to set the default working repository. This is useful when the user wants to manage reviews on a server different than the one associated to the current workspace, or when there is no current workspace at all.

Comments, reviewers, and review status

The
comment
,
reviewer
, and
review
subcommands work on branch, changeset, and shelve reviews.
cm mergerequest
has the same
comment
,
reviewer
,
review
,
subscribe
,
unsubscribe
, and
subscription
subcommands.
cm cr
is an alias of
cm codereview
.
comment add
also accepts
mk
,
comment delete
accepts
rm
, and
reviewer list
accepts
ls
.
comment add
posts a comment on the whole review. To comment on a line of a file, add
--path
or
--revision
, and
--line
. The command prints the GUID of the new comment, which
reply
,
edit
,
delete
,
apply
, and
unapply
take.
comment edit
changes only the text of the comment. If the comment is the review description, it stays the description.
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:<guid>]
also marks the change request as applied in that changeset.
reviewer list
prints one line for each reviewer, with the status that the reviewer set. With
--xml
, it prints a
Reviewers
root element with one
Reviewer
element for each reviewer. Each
Reviewer
element contains
User
,
Status
, and
Type
elements. Status values are always in English, regardless of the client language.
To set your own review status with
review
, you must be a reviewer of the code review, a member of a reviewer group, or a server administrator.

Email subscriptions

subscribe
and
unsubscribe
change your own subscription to a code review's emails. You can't change other users' subscriptions.
Unity Version Control automatically subscribes the following users to a code review:
  • The owner
  • The reviewers
  • Users who comment on the code review
  • Users that someone mentions in a comment
After you unsubscribe, Unity Version Control subscribes you again if any of the following happens:
  • You comment on the code review.
  • Someone mentions you in a comment.
  • Someone adds you, or a group you belong to, as a reviewer again.
Unity Version Control sends review emails only while they're 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. The values are always in English, regardless of the client language, so scripts can parse them. Without
--format
, it prints one
name: value
line for each field:
subscribed: yesreason: owneremails: enabled
subscription
accepts the following
--format
fields:

Format field

Description

{subscribed}
|
{0}
Whether you're subscribed:
yes
or
no
.
{reason}
|
{1}
Why you're subscribed or not. For the values, refer to the following table.
{emails}
|
{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.
{reason}
prints one of the following values:

Value

Meaning

owner
You own the code review.
reviewer
You're a reviewer of the code review.
commented
You commented on the code review.
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.

Output format parameters (--format option)

This command accepts a format string to show the output.

The output parameters of this command are the following

Option / Argument

Description

{0}id
{1}guid
Please note that the '--format' parameter only takes effect when creating a new code review.

Examples

cm codereview cs:1856@myrepo@myserver:8084 "My code review" --assignee=dummy
cm codereview br:/main/task001@myrepo@myserver:8084 "My code review" --status="Rework required" --assignee=newbie --format="{id} -> {guid}"
cm codereview 1367 -e --assignee=new_assignee
cm codereview -e 27658884-5dcc-49b7-b0ef-a5760ae740a3 --status=Reviewed
cm codereview -d 1367 --repository=myremoterepo@myremoteserver:18084
cm codereview 27658884-5dcc-49b7-b0ef-a5760ae740a3 -d
The following example creates a code review of branch
/main/task001
, and sets its reviewers:
cm cr br:/main/task001 "Login fixes" --users=maria --groups=leads
The following example changes the title of code review 1367:
cm cr -e 1367 --title="Fix the login crash"
The following example posts a change request on line 42 of
/src/foo.cs
in code review 1367:
cm cr comment add 1367 -c="Rename this" --path=/src/foo.cs --line=42
The following example adds reviewers to code review 1367:
cm cr reviewer add 1367 --users=maria,me --groups=leads
The following example sets your review status to "Reviewed", with a comment:
cm cr review 1367 --reviewed -c="Looks good"
The following example asks every reviewer of code review 1367 to review again:
cm cr review 1367 --re-request --all
The following example creates a code review with a description:
cm cr br:/main/task001 "Fix the login crash" --description="Retries the token refresh once."
The following example replaces the description of code review 1367 with the content of a file:
cm cr -e 1367 --descriptionfile=description.md
The following example comments on line 12 of a revision that code review 1367 deletes:
cm cr comment add 1367 -c="Why remove it?" --revision=revid:5821 --line=12
The following example marks a change request as applied in changeset 1520, and then as not applied:
cm cr comment apply 27658884-5dcc-49b7-b0ef-a5760ae740a3 --changeset=cs:1520cm cr comment unapply 27658884-5dcc-49b7-b0ef-a5760ae740a3
The following example writes the reviewers of code review 1367 to an XML file:
cm cr reviewer list 1367 --xml=reviewers.xml --encoding=utf-8
The following example shows your subscription to code review 1367, and then unsubscribes you from its emails:
cm cr subscription 1367cm cr unsubscribe 1367