switchBranch

Switch Git branch

Since R2023b

Syntax

branchDetails = switchBranch(repo,name)

branchDetails = switchBranch(repo,name,Name=Value)

Description

branchDetails = switchBranch(repo,name) switches to the specified local branch name in the Git™ repository repo.

branchDetails = switchBranch(repo,name,Name=Value) specifies additional options as one or more name-value arguments. For example, switchBranch(repo,name,Create=true) first creates a local tracking branch if the specified branch name only exists in the remote repository.

Examples

Switch to Local Branch

Navigate to your repository folder and create a repository object.

repo = gitrepo;

Switch to the FeatureB branch.

branchDetails = switchBranch(repo,"FeatureB")

branchDetails = 

  GitBranch with properties:

          Name: "FeatureB"
    LastCommit: [1×1 GitCommit]  (1376b77)

Tip

Use tab completion to get the list of available local branches in your repository.

Switch to Remote Branch

Navigate to your repository folder and create a repository object.

repo = gitrepo;

Switch to a FeatureB branch that only exists remotely. To automatically create a local branch and set the upstream branch to the remote tracking branch before switching to it, set Create to true.

branchDetails = switchBranch(repo,"FeatureB",Create=true);

If the remote branch exists in multiple remotes, specify which remote branch to track using the StartPoint argument.

switchBranch(repo,"remoteBranch",Create=true,StartPoint="origin/remoteBranch");

You can also create a tracking local branch from a specific commit on a remote branch and switch to it in one step.

investigateBugBranch = switchBranch(repo,"ReleaseBranch",Create=true,StartPoint="1376b77");

Input Arguments

repo — Git repository

matlab.git.GitRepository object

Git repository, specified as a matlab.git.GitRepository object.

name — Name of branch

string scalar | character vector | matlab.git.GitBranch object

Name of branch, specified as a string scalar or a character vector.

Example: "BugIssue1032", 'FeatureB'

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: switchBranch(repo,"remoteBranch",Create=true,StartPoint="origin/remoteBranch");

Create — Option to create tracking branch

true or 1 (default) | false or 0

Since R2026a

Option to automatically create a local tracking branch when you attempt to switch to a remote branch, specified as a numeric or logical 1 (true) or 0 (false).

Data Types: logical

StartPoint — Revision specifiers of start point commit

string scalar | character vector | matlab.git.GitBranch object

Since R2026a

Revision specifiers (ID) of start point commit, specified as a string scalar or a character vector. If you do not specify this input, the function creates a local tracking branch from the most recent commit.

If the start point is a remote branch, the switchBranch function creates a local branch that tracks the remote branch automatically.

You must specify StartPoint if you attempt switch to a remote branch that exists in multiple remotes.

Commit IDs support short, full, and relative commits.

Example: "08a4c49","HEAD^1", "08a4c49d249a4dc3d998b473cdda186f1c05dfd0", "origin/Dev"

Data Types: char | string

Output Arguments

branchDetails — Details of branch

matlab.git.GitBranch object

Details of the branch, returned as a matlab.git.GitBranch object.

Version History

Introduced in R2023b

R2026a: New arguments to create local tracking branch for remote branch and switch in one step

Starting in R2026a, you can switch to a branch that only exists in the remote repository. To create a local branch and set the upstream branch to the remote tracking branch before switching to it in one step, set the Create argument to true.

repo = gitrepo;
branchDetails = switchBranch(repo,"remoteBranch");

If the remote branch exists in more than one remote, specify which remote branch to track using the StartPoint argument.

switchBranch(repo,"remoteBranch",Create=true,StartPoint="origin/remoteBranch");