Manage project branches

Project branches define the depot paths associated with a project and control how files, reviews, and workflows are managed.

Use branches to:

  • Map depot paths to a project.

  • Control which files appear in reviews.

  • Apply workflows and approval requirements.

  • Assign moderators and default reviewers.

  • Set the number of approvals required for reviews in the branch.

Add a project branch

To add a branch:

  1. Open the project.

  2. Go to Settings and click on Branches.

  3. Click Add new branch.

  4. Enter a Name for the branch.

  5. Enter one or more Depot paths, one per line. For example:

    //depot/main/swarm/...
//depot/main/swarm/test/ResultSummary.html

    Branch paths are case sensitive and accept wildcards. To learn more, see LINK HERE.

  6. Click Confirm.

Once a project branch has been created, you can configure the following:

  • Workflows

  • Minimum up votes

  • Depot paths

  • Branch moderators

  • Default reviewers

Click branch name to expand settings pane and start the configuration. All branch settings are optional and can be configured as needed.

Workflows

Assign a workflow to a project branch to control the approval rules, tests, and conditions for all associated reviews. If set at the project level, the workflow applies to all branches unless overridden.

Choose to:

  • Inherit from project - (Default) Uses the project workflow. If the project is set to No workflow, global workflow rules apply.

  • Select a specific workflow - Overrides the project workflow for this branch.

  • No workflow - The branch does not use any automated review process.

You can only see the workflows you own or shared workflows.

Minimum up votes

Use Minimum up votes to set the minimum number of up votes required for reviews in this branch.

A review cannot be approved until both of the following conditions are met:

  • All required reviewers have voted up on the review.

  • The Minimum up votes requirement has been satisfied.

  • If a review spans multiple branches, the minimum up votes requirement for each branch must be satisfied before the review can be approved.

In open projects, who can vote may differ. See Open projects.

If the Minimum up votes requirement is higher than the number of available reviewers, the review cannot be approved, even if every reviewer votes up.

Inheritance and overrides

By default, branches use the project-level setting (Inherit from project). Setting a value of 1 or higher overrides the project setting.

Branch settings override project-level settings.

Vote counting and workflows

Vote counting can be affected by workflow rules:

  • If Count votes up from is set to Members, only workflow member votes are counted.

  • If workflows are disabled, all votes are counted.

For more information, see Workflow rules

Depot paths

Multiple paths can be defined per branch. Paths are processed top to bottom. Files are included or excluded based on path order.

Excluding paths

To exclude paths, use the - prefix. For example, the follow depot path:

  • Includes everything under swarm

  • Excludes everything under test

  • Re-includes a specific file.

 //depot/main/swarm/...
 -//depot/main/swarm/test/...
 //depot/main/swarm/test/ResultSummary.html

Wildcards in branch paths

Branch paths support two wildcards:

  • Use ... to match everything under a path (including all subdirectories).

  • Use * to match patterns within a single directory only.

... wildcard

This matches all files and subdirectories. It must be used at the end of a path.

Example:

//depot/Jam/src/...

* wildcard

This matches within a single directory only and does not match subdirectories. It cannot be used at the start of a path, only in the middle. For example:

//ProjectY/UserZ/*/LibA/SubLib1/Data1/...

Paths do not need to exist in order to add a wildcard. This is useful for defining future structure. Once the paths are in place, click Expand workflows.

Supported wildcard formats

Using ...

 //depot/project/...
 //depot/project/src/...
 //depot/*/src/...

Using *

 //depot/Project/*
 //depot/Project/MA*
 //depot/Project/REL*/src
 //depot/*/*/src
 //depot/*/*/*

Using both 

 //depot/*/src/...
 //ProjectY/UserZ/*/src/...
 //depot/Project/REL*/...
 //depot/Project/*/modules/...
 //depot/*/R*/src/...

Handling new subdirectories

If new subdirectories are added after branch creation:

  • Click Expand wildcards to expand * paths.

  • Or edit and save the branch again.

Expanding wildcards can match large directory sets (tested up to 30,000 paths).

Branch paths are not validated when saved.

If a path does not exist, attempting to access it may result in a 404 error.

Troubleshooting: commits not displayed in the top-level view

The Project Commits tab might not display all commits in the top-level view, even though they appear correctly in individual branches.This can happen when branch paths overlap or exclude each other.

The top-level commits view is built from all project branches. Branches are processed in the order they were created, and each path is evaluated from top to bottom.

If a path in one branch includes files that are later excluded by another branch, some commits might not appear in the top-level view.

Example

A project has the following branches:

QA branch:

//depot/alpha/dev/QA/...

Dev branch

//depot/alpha/dev/...
-//depot/alpha/dev/QA/...

In this setup:

  • The Dev branch includes all files under //depot/alpha/dev/...

  • It then excludes //depot/alpha/dev/QA/...

The Issue: This exclusion can prevent QA branch commits from appearing in the top-level commits view.

Recommendation:

To avoid this issue

  • Use a simple and consistent branch structure

  • Plan branch order carefully when creating branches

  • Avoid overlapping include and exclude paths where possible

For example, creating the Dev branch first and the QA branch second can ensure commits appear correctly in the top-level view.

Branch moderators

Branch moderators control review approval and state transitions for reviews associated with the branch. When moderators are configured, only moderators can approve or reject reviews for that branch.

Below is a summary of branch moderator roles and review state rules.

Role Allowed actions Restrictions

Moderators

Can move a review to any state.

Can approve or reject reviews.

Can prevent automatic approvals.

None (unless disable_self_approve is enabled for self-approval). For more information, see disable_self_approve.

Authors (not moderators)

Can change state to:

  • Needs review

  • Needs revision

  • Archived

Can attach committed changelists.

Cannot approve or reject reviews.

Authors (also moderators)

Can change state to:

  • Approve

  • Rejected

  • Needs review

  • Needs revision

  • Archived

Can attach committed changelists.

Cannot approve their own reviews if disable_self_approve is enabled. For more information, see disable_self_approve.

Project members

Can change state to:

  • Needs review

  • Needs revision

Can attach committed changelists.

Cannot approve, reject, or archive reviews.

Other users

None

Cannot change review states.

All roles

Can start a review.

Cannot change state if it’s not in their allowed states (for example, can’t change from Rejected).

To add branch moderators:

  1. Click Manage moderators.

  2. Select the Users or Groups tab.

    • If you add a group, all members of the group are assigned moderator permissions.

    • Use groups to manage multiple moderators at once.

  3. Add users or groups.

  4. Click Add.

Behavior across multiple branches

If a review spans multiple branches with different moderators:

  • By default, one moderator approval is required.

  • Optionally, you can require one moderator per branch (configured globally).

  • If a moderator belongs to multiple branches, one approval counts for each branch.

Moderators can override automatic approval rules defined in workflows.

To remove a moderator, delete them from the moderator list.

Default reviewers

To add default reviewers:

  1. Click Manage default reviewers.

  2. Select the Users or Groups tab.

  3. Add users or groups (maximum 25 combined).

  4. Click Add.

Vote requirements

After adding default reviewers, you can define whether their vote is required.

For users:

  • Optional - the user’s vote is not required.

  • Required - the user must vote for approval.

For groups:

  • Optional - group members’ votes are not required.

  • Required one - at least one group member must approve, and no member votes down.

  • Required all - all group members must approve.

Default reviewer behavior

Reviews across multiple projects or branches

When a review is associated with multiple projects or branches:

  • Default reviewers from all sources are combined.

  • The most restrictive vote requirement is applied.

For example:

  • In Project A: Reviewer is Optional.

  • In Project B: Reviewer is Optional.

  • In a branch associated with the review: Reviewer is Required.

This means the reviewer is Required because the most restrictive requirement is applied.

Retaining default reviewers

To prevent default reviewers from being removed:

  • Enable Retain default reviewers.

  • This ensures default reviewers remain on reviews even if the review is modified.

If a project branch adds a reviewer through default reviewers and Retain default reviewers is enabled, that reviewer is locked to the review while the branch remains in scope for the review.

Reviewer updates when file matching changes

When a new revision changes the files in a review, P4 Code Review re-evaluates which project branches apply to the review.

If the revision removes the last file that matches a branch's depot paths:

  • The branch no longer applies to the review.

  • Default reviewers contributed only by that branch are removed automatically.

  • Retained default reviewers contributed only by that branch are also removed automatically.

  • Reviewers added manually are not removed automatically.

  • If a later revision adds matching files again, the branch's default reviewers are added back automatically.

For detailed information about default reviewer behavior and retained reviewers, see Membership.

When project branch settings change

If project branch settings change, existing reviews are not updated automatically. To recalculate the project branches that apply to a review, run Refresh Projects on the review.

  • If a reviewer is no longer retained by an applicable project branch, the reviewer becomes available for manual removal.

  • P4 Code Review does not remove retained reviewers automatically.

  • If the reviewer is still retained by another applicable project branch, the reviewer remains locked to the review.

For detailed information about retained reviewer behavior, review updates, and reviews spanning multiple projects or branches, see When retained reviewers can be removed from existing reviews.

Mentions and automatic reviewers

If users or groups are mentioned using #review:

  • They are added as reviewers.

  • If they are already present on the review, the reviewer is not duplicated and the most restrictive requirement is applied.

Removal and cleanup

Default reviewers that are not retained can be removed using the delete icon.

Retained reviewers can be removed only after they are no longer retained by an applicable project branch.

If a user is deleted from P4 Server, they are not added to new reviews.