Git Branches

Create, list, and switch between Git branches in your Sandbox environment.

List Branches

Get all branches in a repository.

// Using SDK
const branches = await sandbox.git.branch.list({
  repoPath: '/opt/app',
  includeRemote: true
});

console.log('Local branches:', branches.local);
console.log('Remote branches:', branches.remote);

POST /git/branch/list HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "repoPath": "/opt/app",
  "includeRemote": true
}

Response:

{
  "success": true,
  "branches": {
    "local": ["main", "develop", "feature/new-feature"],
    "remote": ["origin/main", "origin/develop"]
  },
  "current": "main"
}

Parameters:

Parameter	Type	Required	Description
`repoPath`	string	Yes	Path to Git repository
`includeRemote`	boolean	No	Include remote branches

Get Current Branch

Get the currently checked out branch.

// Using SDK
const current = await sandbox.git.branch.current({
  repoPath: '/opt/app'
});

console.log('Current branch:', current.branch);

POST /git/branch/current HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "repoPath": "/opt/app"
}

Response:

{
  "success": true,
  "branch": "main",
  "commit": "a1b2c3d4",
  "detached": false
}

Create Branch

Create a new branch.

// Using SDK
await sandbox.git.branch.create({
  repoPath: '/opt/app',
  branchName: 'feature/new-feature',
  checkout: true // Also switch to new branch
});

POST /git/branch/create HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "repoPath": "/opt/app",
  "branchName": "feature/new-feature",
  "checkout": true
}

Response:

{
  "success": true,
  "message": "Branch created",
  "branch": "feature/new-feature",
  "checkedOut": true
}

Parameters:

Parameter	Type	Required	Description
`repoPath`	string	Yes	Path to Git repository
`branchName`	string	Yes	Name of new branch
`checkout`	boolean	No	Checkout after creating (default: false)

Checkout Branch

Switch to a different branch.

// Using SDK
await sandbox.git.branch.checkout({
  repoPath: '/opt/app',
  branchName: 'develop'
});

POST /git/branch/checkout HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "repoPath": "/opt/app",
  "branchName": "develop"
}

Response:

{
  "success": true,
  "message": "Switched to branch develop",
  "branch": "develop",
  "commit": "e5f6g7h8"
}

Parameters:

Parameter	Type	Required	Description
`repoPath`	string	Yes	Path to Git repository
`branchName`	string	Yes	Branch name to checkout

Common Workflows

Create Feature Branch

// 1. List branches to check current state
const branches = await sandbox.git.branch.list({
  repoPath: '/opt/app'
});

// 2. Create and checkout new feature branch
await sandbox.git.branch.create({
  repoPath: '/opt/app',
  branchName: 'feature/add-authentication',
  checkout: true
});

// 3. Make changes...
await sandbox.files.edit({
  filePath: '/opt/app/src/auth.js',
  content: authCode
});

// 4. Commit changes
await sandbox.git.add({ repoPath: '/opt/app', files: ['src/auth.js'] });
await sandbox.git.commit({ 
  repoPath: '/opt/app', 
  message: 'Add authentication module' 
});

Switch Between Branches

// Save current work first
await sandbox.git.add({ repoPath: '/opt/app', files: ['.'] });
await sandbox.git.commit({ 
  repoPath: '/opt/app', 
  message: 'WIP: Save current work' 
});

// Switch to another branch
await sandbox.git.branch.checkout({
  repoPath: '/opt/app',
  branchName: 'main'
});

// Do work on main branch...

// Switch back
await sandbox.git.branch.checkout({
  repoPath: '/opt/app',
  branchName: 'feature/add-authentication'
});

Work with Remote Branches

// List all branches including remote
const all = await sandbox.git.branch.list({
  repoPath: '/opt/app',
  includeRemote: true
});

// Checkout remote branch
await sandbox.git.branch.checkout({
  repoPath: '/opt/app',
  branchName: 'origin/feature/remote-feature'
});

// Create local tracking branch
await sandbox.git.branch.create({
  repoPath: '/opt/app',
  branchName: 'feature/remote-feature',
  checkout: true
});

Branch Naming Conventions

Best practices for branch names:

// Feature branches
'feature/user-authentication'
'feature/payment-integration'

// Bug fix branches
'fix/login-bug'
'fix/memory-leak'

// Hotfix branches
'hotfix/critical-security-patch'

// Release branches
'release/v1.2.0'

Error Handling

try {
  await sandbox.git.branch.checkout({
    repoPath: '/opt/app',
    branchName: 'nonexistent'
  });
} catch (error) {
  if (error.message.includes('does not exist')) {
    console.log('Branch not found');
    // Create it instead
    await sandbox.git.branch.create({
      repoPath: '/opt/app',
      branchName: 'nonexistent',
      checkout: true
    });
  }
}

Advanced Usage

Branch with Specific Commit

// Create branch from specific commit
await sandbox.git.branch.create({
  repoPath: '/opt/app',
  branchName: 'hotfix/from-prod',
  fromCommit: 'a1b2c3d4' // Commit hash
});

Delete Branch (Coming Soon)

// Delete local branch
await sandbox.git.branch.delete({
  repoPath: '/opt/app',
  branchName: 'feature/old-feature',
  force: false
});

Next Steps

Learn about Git Commits
Check Git Status
Explore Git Clone options

On this page