Skip to main content

​
Overview

Neo Git Graph provides comprehensive branch management capabilities directly from the graph interface. All operations are executed using Git commands and reflect immediately in the graph view.

​
Creating Branches

​
From Any Commit

Create a new branch pointing to any commit in the graph:
  1. Right-click on a commit
  2. Select “Create Branch”
  3. Enter branch name
  4. Branch is created at the selected commit

​
Implementation

// From dataSource.ts:270-272
public createBranch(repo: string, branchName: string, commitHash: string) {
  return this.runGitCommand(
    "branch " + escapeRefName(branchName) + " " + commitHash, 
    repo
  );
}
Branch names are automatically escaped to handle special characters safely.

​
Naming Rules

Git branch names must follow these rules:
  • Cannot contain .., ~, ^, :, ?, *, [
  • Cannot start or end with /
  • Cannot end with .lock
  • Cannot contain consecutive slashes //
The extension validates branch names before executing the Git command. Invalid names will show an error message.

​
Checking Out Branches

​
Local Branches

Checkout an existing local branch: 
// From dataSource.ts:274-282
public checkoutBranch(repo: string, branchName: string, remoteBranch: string | null) {
  return this.runGitCommand(
    "checkout " + (remoteBranch === null 
      ? escapeRefName(branchName)
      : " -b " + escapeRefName(branchName) + " " + escapeRefName(remoteBranch)
    ),
    repo
  );
}

​
Remote Branches

Checkout a remote branch to create a local tracking branch:
  1. Enable “Show Remote Branches”
  2. Right-click on remote branch
  3. Select “Checkout Branch”
  4. Local branch is created and set to track remote
git checkout <branch-name>

​
Checkout Commit (Detached HEAD)

Checkout a specific commit to enter detached HEAD state: 
// From dataSource.ts:284-286  
public checkoutCommit(repo: string, commitHash: string) {
  return this.runGitCommand("checkout " + commitHash, repo);
}
Detached HEAD state means you’re not on any branch. New commits won’t belong to a branch unless you create one.

​
Renaming Branches

​
Local Branch Rename

Rename any local branch: 
// From dataSource.ts:295-299
public renameBranch(repo: string, oldName: string, newName: string) {
  return this.runGitCommand(
    "branch -m " + escapeRefName(oldName) + " " + escapeRefName(newName),
    repo
  );
}
  1. Right-click on branch ref in graph
  2. Select “Rename Branch”
  3. Enter new name
  4. Press Enter to confirm
Renaming a branch updates all local references but does not affect remote branches.

​
Deleting Branches

​
Safe Delete

Delete a branch that has been fully merged: 
// From dataSource.ts:288-292 (forceDelete: false)
public deleteBranch(repo: string, branchName: string, forceDelete: boolean) {
  return this.runGitCommand(
    "branch --delete" + (forceDelete ? " --force" : "") + " " + escapeRefName(branchName),
    repo
  );
}

​
Force Delete

Delete a branch even if it hasn’t been merged:
Force delete will permanently remove the branch pointer. Commits may become unreachable if not merged elsewhere.
git branch --delete <branch-name>

​
Deletion Workflow

  1. Right-click on branch in graph
  2. Select “Delete Branch”
  3. Choose delete mode:
    • Normal: Only if merged
    • Force: Delete regardless of merge status
  4. Confirm deletion
Deleting a branch only removes the branch pointer. Commits remain in the repository and are visible in Git Graph if:
  • They’re reachable from other branches
  • They’re within the graph’s commit load range
  • “Show all branches” is enabled
Orphaned commits will eventually be garbage collected by Git.

​
Merging Branches

​
Merge Branch into Current

Merge any branch into your current branch: 
// From dataSource.ts:302-307
public mergeBranch(repo: string, branchName: string, createNewCommit: boolean) {
  return this.runGitCommand(
    "merge " + escapeRefName(branchName) + (createNewCommit ? " --no-ff" : ""),
    repo
  );
}

​
Merge Options

If possible, move branch pointer forward without creating merge commit:
git merge <branch-name>
Creates a linear history when merging branches that are direct descendants.

​
Merge Commit

Merge a specific commit into current branch: 
// From dataSource.ts:309-311
public mergeCommit(repo: string, commitHash: string, createNewCommit: boolean) {
  return this.runGitCommand(
    "merge " + commitHash + (createNewCommit ? " --no-ff" : ""), 
    repo
  );
}

​
Merge Conflicts

1

Conflict Detection

If merge conflicts occur, Git Graph shows the error message from Git
2

Manual Resolution

Resolve conflicts using VS Code’s merge conflict editor
3

Stage Changes

Stage resolved files using Source Control view
4

Complete Merge

Commit the merge using git commit or VS Code Source Control
5

Refresh Graph

Click “Refresh” button to update the graph
Git Graph does not automatically refresh after merge conflicts. Click the refresh button to see the current state.

​
Branch Visualization

​
Branch Colors

Branches are automatically assigned colors from the configured palette: 
{
  "neo-git-graph.graphColours": [
    "#0085d9", "#d9008f", "#00d90a", // ...
  ]
}

​
Remote Branches

Toggle remote branch visibility:

Show Remote Branches

Enable the checkbox to display remote tracking branches in the graph

Hide Remote Branches

Disable to show only local branches and tags

​
Branch Filtering

​
View Specific Branch

Use the branch dropdown to filter commits:
  1. Click “Branch” dropdown
  2. Select a branch name
  3. Graph shows only commits reachable from that branch

​
Default View

Configure which branches are shown by default: 
{
  "neo-git-graph.showCurrentBranchByDefault": true
}
Show only the currently checked out branch when opening Git Graph

​
Error Handling

All branch operations provide feedback:
Operation completes silently and graph refreshes automatically
Error message from Git is displayed in a notification:
  • Branch name conflicts
  • Merge conflicts
  • Uncommitted changes preventing checkout
  • Protected branch restrictions
For operations involving remotes, network errors are caught and displayed

​
Repository File Watching

Git Graph watches for file system changes: 
// From gitGraphView.ts:117-121
this.repoFileWatcher = new RepoFileWatcher(() => {
  if (this.panel.visible) {
    this.sendMessage({ command: "refresh" });
  }
});
When .git/ directory changes are detected, the graph automatically refreshes to reflect new commits, branches, or tags.

Tag Management

Create and manage tags alongside branches

Multi-Repo Support

Switch between multiple repositories

​
Best Practices

  • Verify branch is merged or obsolete
  • Check if others are using the branch
  • Consider archiving with tags instead
  • Use --no-ff for feature branches to preserve history
  • Use fast-forward for simple updates
  • Communicate merge strategy with your team
  • Use consistent naming conventions
  • Include ticket/issue numbers
  • Prefix by type: feature/, bugfix/, hotfix/

Build docs developers (and LLMs) love

Get started for freeTalk to us