Branches

Learn and practice the branch operations using GitHub API.

We'll cover the following

Overview

Branches are separate areas within a repository where we can perform multiple tasks. For example, we can code in isolation and debug codes. We can also work on a specific branch without affecting the code in other branches. There is one default branch in a repository from which we can have multiple branches.

List branches

Since there can be numerous branches of a single repository, it becomes challenging to remember all of them. Therefore, the feature of listing a branch is quite helpful.

Press + to interact
List branches endpoint
List branches endpoint

The following code shows how we use the GitHub API to list the branches of a particular repository:

Request Parameters

Parameters

Type

Description

username

String

The username of the repository owner

repository

String

The name of the repository whose branches are to be listed

Press + to interact
const endpointUrl = 'https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/branches';
const headers = {
  Authorization: 'token {{ACCESS_TOKEN}}',
  Accept: 'application/vnd.github.v3+json',
};
const options = {
  method: 'GET',
};
async function GetBranches() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printErrors(error);
  }
};
GetBranches();

In case of successful execution of the above code, it will return the response code 200.

Let’s look at a brief explanation of the above code:

  • Line 1: We define the URL of the endpoint.
  • Lines 13–21: We define the async function that will call the defined endpoint.
    • Line 15: In case of a successful request, the response of the API call is printed by invoking the printResponse function.
    • Line 17: Otherwise, the error is printed by calling printErrors function.
  • Line 21: We call the async function.

Get a branch

We can get a particular branch from a repository of the specified user. We need to specify the branch name in the URL.

Press + to interact
Get a branch endpoint
Get a branch endpoint

Let's specify the branch name in place of <branch-name> the code below and run it to fetch the details of the specified branch.

Request Parameters

Parameters

Type

Description

username

String

Username of the repository owner

repository

String

The name of the repository whose branch is to be listed

branch-name

String

The name of the branch that we want to get

Press + to interact
const endpointUrl = 'https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/branches/<branch-name>';
const headers = {
  Authorization: 'token {{ACCESS_TOKEN}}',
  Accept: 'application/vnd.github.v3+json',
};
const options = {
  method: 'GET',
};
async function GetBranch() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printErrors(error);
  }
};
GetBranch();

In case of successful execution of the above code, it will return the response code 200.

Let’s look at a brief explanation of the above code:

  • Line 1: We define the URL of the endpoint.
  • Lines 13–21: We define the async function that will call the defined endpoint.
    • Line 15: In case of a successful request, the response of the API call is printed by invoking printResponse function.
    • Line 17: Otherwise, the error is printed by calling the printErrors function.
  • Line 21: We call the async function.

Rename a branch

We can use the GitHub API for branch operations like renaming branches. The users with admin rights or permission to change the branch name can rename the branch. Whenever a branch is renamed, the URLs in the other branches that redirect to the changed branch are automatically updated.

Press + to interact
Rename branch endpoint
Rename branch endpoint

Let’s run the following code to rename a branch. Replace <branch-name> to be renamed in the URL with the branch’s name in line 1. The new name of the branch is sent as a parameter and is specified in line 9.

Request Parameters

Parameters

Type

Description

username

String

The username of the repository owner

repository

String

The name of the repository whose branch is to be listed

branch-name

String

The name of the branch that we want to rename

new_name

String

The new name of the branch

Press + to interact
const endpointUrl = 'https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/branches/<branch-name>/rename';
const headers = {
  Authorization: 'token {{ACCESS_TOKEN}}',
  Accept: 'application/vnd.github.v3+json',
};
const body = JSON.stringify({
  new_name: 'develop',
});
const options = {
  method: 'POST',
  headers,
  body,
};
async function RenameBranch() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printErrors(error);
  }
};
RenameBranch();

In case of successful execution of the above code, it will return the response code 201.

Let’s look at a brief explanation of the above code:

  • Line 1: We define the URL of the endpoint.
  • Lines 8–10: We define the required body parameters.
  • Lines 18–27: We define the async function that will call the defined endpoint.
    • Line 21: In case of a successful request, the response of the API call is printed by invoking the printResponse function.
    • Line 23: Otherwise, the error is printed by calling printErrors function.
  • Line 27: We call the async function.

Merge a branch

Working on a separate branch does not mean that we can’t link two branches. There will be cases when we take a chunk of code from a default branch and move it to another. Then, we’d want to make changes in the other branch and merge the changed code back to the default. We can use the merge operation to merge the chunks of code of multiple branches.

Press + to interact
Merge a branch endpoint
Merge a branch endpoint

Let’s try to merge two branches using the GitHub API. The names of the two branches to be merged are required to be specified in places of <base-name> and <head-name> in lines 9 and 10. Some important parameters for the endpoint of merging a branch are given below:

Request Parameters

Parameters

Type

Description

username

String

The username of the repository owner

repository

String

The name of the repository whose branch is to be listed

base

String

Specifies the name of the branch that the head will be merged into

head

String

Specifies the branch name or a commit SHA1 to be merged

commit_message

String

This is the message used when a merge commit occurs. If no message is specified, the default message is used.

Press + to interact
const endpointUrl = 'https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/merges';
const headers = {
  Authorization: 'token {{ACCESS_TOKEN}}',
  Accept: 'application/vnd.github.v3+json',
};
const body = JSON.stringify({
  base: '<base-name>',
  head: '<head-name>',
});
const options = {
  method: 'POST',
  headers,
  body,
};
async function MergeBranch() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printErrors(error);
  }
}
MergeBranch();

The following can be the responses:

  • 201: When the existing branches have been successfully merged.

  • 204: When the existing branches have already been merged.

Let’s look at a brief explanation of the above code:

  • Line 1: We define the URL of the endpoint.
  • Lines 8–11: We define the required body parameters.
  • Lines 19–28: We define the async function that will call the defined endpoint.
    • Line 22: In case of a successful request, the response of the API call is printed by invoking the printResponse function.
    • Line 24: Otherwise, the error is printed by calling the printErrors function.
  • Line 28: We call the async function.