Branches

Branches in Legit FS are isolated workspaces where you can develop features, run experiments, or track different versions of your files. Each branch maintains its own commit history and current state, allowing you to work on multiple changes simultaneously without conflicts.

How Branches Are Stored

Braches sometimes called Sandboxes in Legit are stored as a directory structure under /.legit/branches/. Each Branch has its own .legit folder with metadata.

Branches in Legit are completely isolated and changes on one branch don’t affect other branches.

Storage Structure:


/.legit/branches/
  main/                    # branch name
    document.txt          
    .legit/                # branch metadata
  feature-xyz/             # another branch
    document.txt
    .legit/

Create a Branch

Branches in Legit are created using the standard mkdir filesystem operation. There’s no special branch creation command—just create a directory under /.legit/branches/ which is creating a new branch under /.legit/branches/<branchName>.

Create a Branch

To create a new branch, simply create a directory:


// Creates new branch
await legitFs.promises.mkdir('/.legit/branches/feature-xyz')
 
// Now you can write files to this branch
await legitFs.promises.writeFile(
  '/.legit/branches/feature-xyz/document.txt',
  'Content',
  'utf8'
)

Read a Branch

There are multiple ways to read branch information and access branch content:

Read directory in a specific branch

Read the directory at the current state in a specific branch.


// Get all files in a branch (including .legit)
const files = await legitFs.promises.readdir('/.legit/branches/main')
// → ['.legit', 'document.txt', 'other-file.txt', ...]

Note: The directory listing includes a .legit folder which contains branch metadata (head, history, operation, etc.)

Read file in a branch

readFile('/.legit/branches/<branchName>/<path>')

Read the file at the current version in a specific branch.


const content = await legitFs.promises.readFile('/.legit/branches/main/document.txt', 'utf8')
 
// → Hello World

List All Branches

Get a list of all branches in the repository:


// List all branches
const branches = await legitFs.promises.readdir('/.legit/branches')
// → ['main', 'feature-xyz', 'experiment-abc']

Get Current Branch OID

The HEAD is the most recent commit on a branch:


const head = await legitFs.promises.readFile(
  '/.legit/branches/main/.legit/head',
  'utf8'
)
// → "e96d6f7709aabbc5504781ae26b0eed7b59bb416"

Use cases:

Check if branch has new commits (compare with previous HEAD)
Get the latest commit OID to read commit snapshots
Monitor branch changes by polling the HEAD file

Working with Branches

Check if Branch Exists


// List all branches and check if specific branch exists
const branches = await legitFs.promises.readdir('/.legit/branches')
const branchExists = branches.includes('feature-xyz')