Get started

From a git repo on your computer to your first patch on main, in about ten commands.

1. Get the quilt command

Source control is part of Quilt's own command line, quilt. It ships in the npm package heyquilt and needs Node.js 22 or newer.

$ npm install -g heyquilt
$ quilt --version

Other ways to get the same command:

Run it without installing: npx heyquilt log works for every verb on this page.
On a Linux server or cloud machine: curl -fsSL https://heyquilt.com/install.sh | sh.
In the Quilt desktop app: Quilt → Install the Quilt Command…

The source control verbs are quilts, square, checkout, commit, log, show, diff, merge, rebase, revert, cherry-pick, blame, resolve, cat, ls, import, export and events. quilt status is source control's status inside a block folder, and a live Quilt session's status anywhere else.

Sign in with your heyquilt.com account. The command opens a page in your browser where you approve this computer; --no-browser prints the link instead.

$ quilt login
To sign in, open this page and approve this computer:

  https://heyquilt.com/…

Check it shows the code …. Waiting…
Signed in as Ada Lovelace (ada@example.com).

Every command then talks to https://api.heyquilt.com as you. Agents sign in with a key of their own instead: see For agents.

3. Bring in a git repo

Import makes a new quilt from the history of the repo's HEAD. Every commit on its first-parent chain becomes a patch on main, in order. The side commits of a merge become the commits of that patch's square, so nothing is lost. Authors are kept.

$ quilt import git ./my-app --validate
Importing 782 patches (1335 commits in all) into my-app…
  58 patches, 100 commits
  …
Imported 1335 commits (782 patches on main) into my-app (019a1f2c-…). Validated 782 trees against git.

The quilt is named after the folder. --into <slug> picks another name.
--validate checks, after the import, that every patch holds exactly the files of its git commit.
The import runs on your computer: it reads the repo with git and uploads only what the server does not have yet.

To start with nothing instead, make an empty quilt. Its main starts at an empty root commit.

$ quilt quilts new my-app
Made quilt my-app (019a1f2c-…).
$ quilt quilts
my-app  019a1f2c-…  (admin)

4. Open a square and check out a block

A square is your own piece of work. Open one from the tip of main and check it out into a new folder in one step. Paths after -- pick the block: only those folders and files are written. Leave them out to get the whole quilt.

$ quilt square open "Fix sign-in" --quilt my-app --dir fix-sign-in -- src docs
sq:1a2b3c4d "Fix sign-in" · open · no commits yet · held by person:7f3e…
Checked out into /Users/ada/fix-sign-in.

You can also open the square first and check it out later, or check out any revision to read it. A checkout of a revision is read-only, because only a square takes commits.

$ quilt checkout sq:1a2b3c4d --quilt my-app --dir fix-sign-in -- src
$ quilt checkout patch:780 --quilt my-app --dir old-copy

A checkout goes into an empty folder. Inside a block folder, quilt checkout <square or revision> switches the folder over, once its changes are committed.

5. Edit and commit

Edit the files with any editor or AI tool. Inside the folder you do not need --quilt: the quilt and the square come from .quilt/block.json.

$ cd fix-sign-in
$ quilt status
On square sq:1a2b3c4d "Fix sign-in" · open · no commits yet · held by person:7f3e…
Block: src, docs at 4d5bb0f2aacd
Changes not yet committed:
  modified  src/auth.js
$ quilt diff
$ quilt commit -m "Sign-in keeps the session"
Committed 9e8d7c6b5a49 "Sign-in keeps the session"
square sq:1a2b3c4d "Fix sign-in" · open · head 9e8d7c6b5a49 · held by person:7f3e…

There is no staging area: quilt commit takes every changed file in the block. Name paths to commit only some: quilt commit -m "Docs" docs/.
New files are picked up without an add step. The folder's top-level .gitignore is read, and .git, .quilt and node_modules are always left out.
A commit is on the server the moment it is made. There is nothing to push.

6. Merge into main

In the block folder, quilt merge merges the square into its line. The server replays the square onto the current tip of main as one commit and gives it the next patch number.

$ quilt merge --dry-run
Would merge as patch main:783 (no file touched on both sides).
$ quilt merge
Merged as patch main:783 (5f4e3d2c1b0a).

The patch's message is the square's title followed by its commit messages; -m sets your own. If the square clashes with a patch that merged after you opened it, the merge is refused and the clash is kept in your square to settle. Conflicts explains what to do.

7. Read the history

$ quilt log --oneline -n 3
5f4e3d2c1b0a [main:783] Fix sign-in
a1c5c9d77b1a [main:782] Source dashboard: its own app
4d5bb0f2aacd [main:781] Session email is live
$ quilt log -n 5 -- src/auth.js
$ quilt show patch:783 --stat
$ quilt diff patch:781 patch:783 --name-only
$ quilt blame src/auth.js
$ quilt cat README.md@patch:700
$ quilt ls main src

Outside a block folder, add --quilt my-app to any of these. Add --json to any command to get the server's record instead of text.

A quilt is private to its members. Its admins add people and agents by member id, at read, write or admin.

$ quilt quilts add agent:5c1e… --level write --quilt my-app
agent:5c1e…: write

An agent prints its id with quilt agent whoami. A member can see their own id under you in quilt quilts show <quilt> --json.

9. Back to git, any time

Export writes a line's patches as commits on a branch of a plain git repo, so CI and deploys that expect git keep working. It is one way: run it again and it adds the new patches.

$ quilt export git ../my-app-git --quilt my-app
Exported 783 patches to main in ../my-app-git: main is 3c9a… (patch 783).

More on import and export in Compare to git.