Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 CLI Documentation | 2025.2

# p4 branch

Create or edit a branch mapping and its view.

## Syntax

    p4 [g-opts] branch [-f] branchspec
    p4 [g-opts] branch -d [-f] branchspecp4 [g-opts] branch -i [-f]
    p4 [g-opts] branch [-S stream] -o placeholderForStreamBranchSpecName
    p4 [g-opts] branch [-S stream -P parent] -o placeholderForStreamBranchSpecName

Syntax and naming conventions

## Description

`p4 branch` enables you to create a mapping between two sets of files for use with `p4 integrate` or `p4 copy`. A branch view A specification of the branching relationship (branch mapping) between two codelines in the depot. Each branch view has a unique name and defines how files are mapped from the originating codeline to the target codeline. defines the relationship between the files you’re integrating from (the `fromFiles`) and the files you’re integrating to (the `toFiles`). Both sides of the view are specified in depot syntax.

After you have created a branch mapping, you can:

- integrate files: `p4 integrate `-b branchspec``

- copy files: `p4 copy `-b branchspec``

Saving a `p4 branch` form has no immediate effect on any files in the depot or your client workspace.

Note that each branch, depot, label, and workspace must have a unique name.

### Streams require a placeholder value for branchspec

placeholderForStreamBranchSpecName indicates that you can use any value you want, because the stream will generate its own name for the branch spec.

The first syntax variant for streams:

p4 [g-opts] branch [-S stream] -o placeholderForStreamBranchSpecName

displays the branch spec of the specified stream and its actual parent.

The second syntax variant for streams:

`p4 [g-opts] branch [-S stream -P parent] -o placeholderForStreamBranchSpecName`

acts as if stream were the child of parent, which currently might or might not be true.

See Examples for stream.

## Form fields

Field Name | Type | Description
--- | --- | ---
`Branch:` | read-only | The branch name, as provided on the command line.
`Owner:` | mandatory | The owner of the branch mapping. By default, the owner is the user that created the branch. When the `Option` field value is `locked`, knowing who the owner is can be helpful. The specified owner does not have to be a P4 Server user or group. You might want to use an arbitrary name if the owner does not yet exist, or if you have deleted the owner and need a placeholder until you can assign the spec to a new owner.
`Access:` | read-only | The date the branch spec was last used.
`Update:` | read-only | The date the branch mapping was last changed.
`Options:` | mandatory | Either `unlocked` (the default) or `locked`. If `locked`, only the `Owner:` can modify the branch mapping, and the mapping can’t be deleted until it is `unlocked`.
`Description:` | optional | A short description of the branch’s purpose.
`View:` | mandatory | A set of mappings from one set of files in the depot (the `source files`) to another set of files in the depot (the `target files`). The view maps from one location in the depot to another. It can’t refer to a client workspace. Comments are preceded by `##` as shown in this example:
    View:
             ## Comment line
            //depot/main/...  //depot/r2.1  ## comment appended

## Options

Option | Description
--- | ---
`-d` | Delete the named branch mapping. Files are not affected by this operation; only the stored mapping from one codeline to another is deleted. Normally, only the user who created the branch can use this option.
`-f` | Force option. Combined with `-d`, permits P4 Server administrators to delete branches they don’t own. Also permits administrators to change the modification date of the branch mapping (the `Update` field is writable when using the `-f` option).
`-i` | Read the branch mapping from standard input without invoking an editor.
`-o` | Write the branch mapping to standard output without invoking an editor.
`-P parent` | For a specified stream, display the mapping that is generated by hypothetically treating the stream as if it were a child of the specified parent. Requires `-S`. One use case is to evaluate whether you want to establish a new parent for this stream.
`-S stream` | Display the mapping generated for the specified stream. This option enables you to see how change is propagated between the stream and its parent.
`g-opts` | See Global options.

## Usage notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required
--- | --- | ---
N/A | N/A | `open`

- A branch view defines the relationship between two related codelines. For example, if the development files for a project are stored under `//depot/project/dev/...`, and you want to create a related codeline for the 2.0 release of the project under `//depot/project/r2.0/...`, specify the branch view as:

  `//depot/project/dev/... //depot/project/r2.0/...`

  Branch views can contain multiple mappings. To specify a view, see Views .

- If a path or file name contains spaces, use quotes around the path. For instance:

  `//depot/project/dev/... "//depot/project/release 2.0/..."`

- Paths can be excluded from a branch view to prevent a subset of files from being merged. For example, the following view entry prevents any files named `AssemblyInfo.cs` from being merged between `MAIN` and `REL`:

  `-//depot/MAIN/.../AssemblyInfo.cs //depot/REL/.../AssemblyInfo.cs`

  Similarly, entire directories can be excluded from a branch view:

  `-//depot/MAIN/bin/... //depot/REL/bin/...`

  To specify a view, see Views .

- Branch views can also be used with `p4 diff2` with the syntax `p4 diff2 -b branchnamefromFiles`. This will diff the files that match the pattern `fromFiles` against their corresponding `toFiles` as defined in the branch view.

## Examples for stream

Display the mapping generated for the 5dev1 stream and its actual parent: `p4 branch -S //depotstream1/5dev1 -o placeholder1`
Display the mapping generated for the 5dev1 stream and the main5 stream, treating 5dev1 as the child of main5 (which might or might be the case): p4 branch -S //stream1/5dev1 -P //stream1/main5 -o placeholder2

## Related commands

To view a list of existing branch mappings | `p4 branches`
To copy changes from one set of files to another | `p4 integrate`
To copy files and/or the stream spec from one location in the depot to another | `p4 copy`
To branch a set of files as a one-step operation | `p4 populate`
To view differences between two codelines | `p4 diff2`

Your search for returned results