Legit FS API Reference

The LegitFS instance exposes a virtual filesystem under .legit. All operations on this tree are done with standard fs.promises methods (readFile, readdir, etc.), but the paths themselves encode the data.

Overview:

/
├─ document.txt                   # checked-out file
└─ .legit/
   ├─ branches/
   │  └─ main/
   │     ├─ document.txt          # current HEAD content
   │     └─ .legit/
   │        ├─ head
   │        ├─ history
   │        ├─ operation
   │        └─ operationHistory
   └─ commits/
      └─ ab/                      # first 2 chars of SHA
         └─ cdef1234567890.../    # remaining 38 chars of SHA
            └─ document.txt       # snapshot of the file in that commit

Example paths:

• Working directory file: /document.txt
• Branch head file: /.legit/branches/main/document.txt
• Commit snapshot: /.legit/commits/ab/cdef1234567890.../document.txt
• Metadata files: /.legit/branches/main/.legit/head

Below are the main endpoints:

Root

Contains the .legit folder and the working directory

readdir('/')

Contains the .legit folder and the working directory of the files.

Example:

await legitFs.promises.readdir("/")
// → ['.legit', 'document.txt']

Writing (commit, versioning)

writeFile('/.legit/branches/<branchName>/<path>', content)

Example usage:

await legitFs.promises.writeFile('/.legit/branches/main/text.txt', Hello World)

Branches

Lists all branches in the repository

readdir('/.legit/branches')

Example usage:

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

Creates a branche in the repository

mkdir('/.legit/branches/<branchName>')

Example usage:

await legitFs.promises.mkdir('/.legit/branches/feature-xyz')
 
 

Read current version

Read directory in a specific branch

readdir('/.legit/branches/<branchName>')

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

const content = await legitFs.promises.readdir('/.legit/branches/main')
 
// → ['.legit', 'document.txt']

Also contains a .legit folder for more meta information

Read file in a specific 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', 'utf')
 
// → Hello World

Branch meta

Contains metadata for a specific branch:

• head → the current commit SHA ( Secure Hash Algorithm) of the branch.
• history → JSON array of commits in this branch.
• operation → last operation performed (commit, merge, etc.).
• operationHistory → chronological list of operations. Read Tracking intent to learn more
• threadName → optional name.

Read a head hashe from branch

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

Read the head SHA from the branch.

Example:

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

Get History of a branch

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

Get the history of the branch.

Example:

const historyJson = await legitFs.promises.readFile('/.legit/branches/main/.legit/history', 'utf8')
const history = JSON.parse(historyJson)
 
/* -> [
    {
        "oid": "e96d6f7709aabbc5504781ae26b0eed7b59bb416",
        "message": "💾 Change 'document.txt'\n",
        "parent": [
            "e9e9656a54238e339d4e550f9ddbed2ee8be70d0"
        ],
        "tree": "c9991edf45847ff7eb51abff35169a6b6228c5cc",
        "author": {
            "name": "Legit",
            "email": "hello@legitcontrol.com",
            "timestamp": 1761664398,
            "timezoneOffset": 0
        },
        "committer": {
            "name": "Legit",
            "email": "hello@legitcontrol.com",
            "timestamp": 1761664398,
            "timezoneOffset": 0
        }
    },
    ...
   ]
*/

Commits

Read files from a commit

readdir('/.legit/commits/<sha1_2>/[sha3__40]'

Stores snapshots of all commits, organized by SHA prefix.

Access any historical commit by its SHA:

const commitPath = '/.legit/commits/ab/cdef1234567890.../document.txt'
const oldContent = await legitFs.promises.readFile(commitPath, 'utf8')

Structure:

/.legit/commits/
  ab/          # first 2 chars of SHA
    cdef1234567890.../
      document.txt   # snapshot of the file in that commit

Notes

• You can traverse .legit with standard FS methods (readdir, readFile, writeFile) — no special SDK methods are needed.
• This design allows you to programmatically inspect any commit, branch, or operation without relying on a separate API.