gritHEAD → docs/serve
Commands / RemotesMarkdown

grit serve

Serve repositories over HTTP, with a web view where people sign in with email and password.

grit serve [--root <path>] [--db <file>] [--bind <host:port>] [--bundle-interval <duration>] [--no-bundles] [--header-timeout <duration>] [--idle-timeout <duration>] [--max-git-requests <n>] [--shutdown-timeout <duration>]
grit serve --setup [--email <email>] [--root <path>] [--db <file>]
grit serve add-user <email> [--admin] [--root <path>] [--db <file>]
grit serve token <email> [--root <path>] [--db <file>]
grit serve grant <email> <repository> [--write] [--root <path>] [--db <file>]
grit serve users [--root <path>] [--db <file>]

Description

grit serve runs a Git server over HTTP. Any Git client, git or grit, can clone, fetch and push through it, and a browser shows each repository's branches and recent commits. Fetch speaks Git protocol v0, v1 and v2 (whichever the client asks for); push uses receive-pack, which has no v2 form. Everything runs in-process: the server needs no git or other grit binary.

Fetch and clone POST bodies (git-upload-pack) are streamed as they arrive; the server rejects decoded bodies larger than 1 GiB with HTTP 413 (matching a generous reading of Git's http.maxRequestBuffer), which is enough for several million want lines. Push bodies are streamed separately and are limited only by each repository's receive.maxInputSize.

When a client is still uploading a large POST body, early responses such as 401, 404, 403 or 413 drain the remainder of that body (up to the same 1 GiB cap) before the connection closes, so a reverse proxy relays the real status instead of answering 502 Bad Gateway.

--root names what to serve:

  • a directory of repositories: each child directory that is a repository (bare project.git or a working tree project) is served as project. New repositories show up without a restart.
  • a single repository: it is the only one served, under its directory name.

Clients reach a repository at http://<host>:<port>/<name>.git (the .git is optional).

Users and passwords

A user is an email address with a password. Users, their access and their tokens live in a SQLite database, grit-serve.db in the root by default (or in the root's .git directory when the root is a working tree, so the file never shows up as untracked). Pick another path with --db.

Path strings in the startup banner, errors, and --json fields such as database use forward slashes and no Windows \\?\ verbatim prefix, matching other grit commands.

  • grit serve --setup creates the database and the first admin user. It asks for the admin's email (or takes --email) and a password. An admin can read and write every repository, and add users in the web view.
  • grit serve add-user <email> adds a user. Add --admin for another admin.
  • grit serve grant <email> <repository> gives a user read access (fetch and clone) to one repository; --write also allows pushing. Granting again replaces the earlier access.
  • grit serve users lists every user, their token count and their access.

Both --setup and add-user ask for the password twice without echoing it. Leave it empty to have one generated instead: a temporary password like 5qy3-ewqt-mgjj-3jnv, printed once, which the user must replace with their own the first time they sign in. Without a terminal, the password is read from the first line of stdin, and empty input generates one. Passwords need at least 8 characters; the database keeps only an Argon2 hash.

Signing in

People sign in to the web view at http://<host>:<port>/ with their email and password. There they can change their password, and admins get a Users page to add users and give them access. Adding a user there generates a temporary password to send them, together with their email address, yourself.

Git uses access tokens instead of passwords. To get one, run grit auth <url> (or grit login <url>) with the server's address or any repository URL on it. It opens the server's sign-in page in your browser and waits; after you sign in and approve the code it shows, it saves a new token with your credential helper, so grit and git clone, fetch and push without asking.

For scripts and CI, which cannot sign in in a browser, an admin can make a token with grit serve token <email> and hand it over: grit auth <url> --token <token> stores it, a URL carries it (git clone http://bob:<token>@host:8080/project.git, where the user name is ignored), or a client can send Authorization: Bearer <token>. Each token is printed once; the database keeps only a SHA-256 hash of it. A token starts with grit_.

A Git request without a valid token gets 401, and a browser without a session is sent to the sign-in page. A repository the user cannot read answers 404, the same as one that does not exist, and a push from a user with read access answers 403.

Clone bundles

The server keeps a prebuilt bundle of each repository's branches and tags in grit-serve/bundles/ inside its Git directory. A background thread builds a repository's first bundle as soon as the server starts (or as soon as the repository gets its first branch), and builds a new one after pushes have changed its refs, once the current bundle is older than --bundle-interval (24 hours by default; 0s rebuilds right after every push). Each bundle gets a new file name and the previous one is kept, so a client part way through downloading the old bundle can still finish it.

Fetches over protocol v2 see the bundle-uri command in the server's capabilities. It answers with the current bundle's URL, http://<host>:<port>/<name>/bundles/<file>, which serves the file with Range support so an interrupted download can resume. grit clone downloads the bundle first and then fetches only what is newer; credentials embedded in the clone URL apply to that same-origin bundle download as well. git clone does the same with -c transfer.bundleURI=true and a credential helper that knows the token, because Git's advertised bundle URL has no userinfo. Downloading a bundle needs read access, like fetching.

--no-bundles turns this off: nothing is built and nothing is advertised.

A repository with promisor remotes gets no bundle, and any bundle built earlier is removed. This covers a repository offloaded with grit gc offload: some of its blobs live elsewhere, and a bundle holding them would undo the offload. Its clients clone through upload-pack, which points them at the promisor.

Partial clone filters

grit clone --blobs and filtered fetches need the server to advertise Git's filter capability. On each served bare repository, enable it the same way as with git upload-pack:

$ git -C /path/to/root/project.git config uploadpack.allowFilter true

Filter support is off by default (matching stock git upload-pack). Without it, clients that pass --blobs or --filter still connect, but the server sends a full pack; grit warns when that happens.

Resumable pushes

The push advertisement carries a pushBundle=/push capability: a TUS upload endpoint at http://<host>:<port>/<name>/push. grit push sends a large push there as a bundle, in chunks that survive a dropped connection, then posts the usual ref updates to …/push/<id>/receive. The server applies them exactly as for a normal push (the same checks, policy and hooks) and answers with the usual push report. Uploading needs write access, and an upload belongs to the user who started it. Unfinished uploads are deleted after a week. Git clients ignore the capability and push the usual way.

Hook scripts on push see the token user's email as REMOTE_USER and GRIT_USER (not the username in the clone URL), on both git-receive-pack and …/push/<id>/receive.

Request Answer
OPTIONS /<name>/push TUS version and extensions (creation)
POST /<name>/push with Upload-Length 201 and the upload's Location
HEAD /<name>/push/<id> Upload-Offset: bytes received so far
PATCH /<name>/push/<id> with Upload-Offset appends the body; answers the new offset
POST /<name>/push/<id>/receive applies the bundle with the posted ref updates

Snapshot checkouts

grit checkout <url> starts work on a repository without its history: the server makes a snapshot commit of the target branch (where HEAD points), cut down to the paths asked for, and serves it as a resumable download. These requests have their own endpoint, apart from Git's, and need read access:

Request Answer
GET /.grit/checkouts/<name> the repository's name, target branch and its tip
POST /.grit/checkouts/<name> makes a checkout of the paths in the JSON body
GET /.grit/checkouts/<name>/<id> the checkout
GET /.grit/checkouts/<name>/<id>/bundle its snapshot as a bundle, with Range support
POST /.grit/checkouts/<name>/<id>/update a snapshot of the newest tip of the branch the checkout was made from, on top of the checkout's last one, at refs/checkouts/<id>/target (grit pull)
POST /.grit/checkouts/<name>/<id>/checkin grafts branches pushed to refs/checkouts/<id>/out/heads/* onto the real history and sets them (grit checkin; write access)
POST /.grit/checkouts/<name>/<id>/branch shows the checkout the server's branch named in the JSON body (name): its commits the target lacks, cut down to the checkout's paths on its snapshots, at refs/checkouts/<id>/in/heads/<branch> (grit pull <branch>)
POST /.grit/checkouts/<name>/<id>/work reserves a fresh work-branch name for the checkout, from the work name in the JSON body, as making a checkout does (grit integrate, moving you off the branch it merged)
POST /.grit/checkouts/<name>/integrate merges a branch into the target with a merge commit (grit integrate; write access)
GET /.grit/checkouts/<name>/slices the slices in .grit/slices.toml on the target
PUT, DELETE /.grit/checkouts/<name>/slices/<slice> changes a slice with a commit on the target (grit slice; write access)

The server keeps checkouts in grit-serve/checkouts/ inside the Git directory (each checkout's record in <id>.json, replaced whole so a crash never leaves half of one, the work-branch names it has given out under names/, so a name is never given out twice, and the graft log under grafts/: which real commit each checkout commit stands for, filed by the first two hex digits of each side and only ever appended to) and points refs/checkouts/<id>/target at each one's snapshot. Requests on one checkout take turns, and so do check-ins setting the repository's branches: of several check-ins of one branch at once, the first sets it and the others are refused. Branches are set with a compare-and-swap, so a branch that moved meanwhile is decided again rather than overwritten. A branch the server has moves only as a fast-forward, when the same checkout set it last, when the new branch keeps every commit the old one had beyond the target by change id (a rebase of it whose copies keep what the originals changed outside the checking-in checkout's paths), or when the check-in is forced; the server's log line and the check-in's answer name the rule (see grit checkin). A grafted commit with no change-id header gets the one derived from the checkout commit's own id. Check-ins record the commits they graft in the graft log once the branch is set (a log that can't be written is reported in the server's log, and the check-in still succeeds), and so does showing a checkout a branch, so work built on a branch a checkout was shown grafts onto the real commits it stands for, and a check-in replays only commits it hasn't grafted before; a check-in's walk stops at the target branch, so a branch built on the real history is refused at once. A shown commit keeps its author, date and message, gets a change id derived from the real commit when it has none, and drops signatures; a checkout's own commits (those its pushed branches at refs/checkouts/<id>/out/heads/* reach) come back as they are, and another checkout's only when they have the tree the projection would make. Where the repository ignores case (core.ignorecase), a branch asked for in another case is shown under the server's spelling (see grit pull).

Once a repository has checkouts, its target branch changes only through integrations and slice changes. Pushes that create, update or delete it are refused, by git and grit clients alike, over smart HTTP and the resumable endpoint (and by grit receive-pack); branches whose names differ from it only in case are refused too. The refusal (main is the target branch; it changes only through integrate, or Git's own branch is currently checked out when the repository has it checked out) comes with instructions, which Git clients show as remote: lines: push another branch and run grit integrate <branch>. A repository without checkouts keeps Git's rules for pushes, including refusing to delete the branch HEAD names (receive.denyDeleteCurrent).

Integrations and slice changes take turns, one at a time per repository, and each starts over on the new tip if the target moves while it is made (by another process). Integrating refuses names that are not valid branch names, the target itself and branches that share no history with it. A server-made commit's author comes from the request (the client's own author identity) or is the signed-in user; <, > and line breaks are cleaned out of it, so it can't break the commit's header. When the repository has a working tree with the target checked out (HEAD names it), that tree and its index move with each integration and slice change, keeping uncommitted changes there as git reset --keep does; a change that would overwrite them is refused and the target stays where it was. Every ref move the server makes is logged where the repository keeps reflogs (core.logAllRefUpdates, on by default in a repository with a working tree), as checkin: from checkout <id>, integrate: Merge branch '<branch>' into <target> or slice: <message>, so git reflog <branch> shows it and <branch>@{1} undoes it.

Large-object promisors

A repository can point clients at promisor remotes that hold some of its objects, such as a large-object promisor (LOP) with the big blobs. Set promisor.advertise = true and give the repository a promisor remote (remote.<name>.url and remote.<name>.promisor = true); the protocol v2 capabilities then carry a promisor-remote line naming it, and promisor.sendFields adds its partialCloneFilter and token. A LOP served by grit serve needs uploadpack.allowFilter and uploadpack.allowAnySHA1InWant, so clients can fetch blobs no ref points at. See grit upload-pack for the exchange, and grit clone for the client side.

Over smart HTTP every request stands alone, so the server only knows a client accepted a promisor remote when the fetch request itself says so. grit clients send their acceptance with every command; git clients send it with ls-refs only, so for them the server behaves as if nothing was accepted. A git fetch whose filter is no looser than the promisor remotes' partialCloneFilter still gets its pack without the offloaded blobs, since its filter leaves them out anyway (see upload-pack).

To keep a repository's big blobs out of it, host the LOP as a second repository next to it and run grit gc offload on the main one. Point remote.<lop>.url at the URL clients should use (for example http://<host>:<port>/<lop>.git on this server), and pass --lop-dir with the LOP's directory on disk. The main repository then serves clients that accept the LOP without the offloaded blobs. A client that accepts nothing is refused with a hint, unless the server may fetch the blobs itself: set uploadpack.lazyFetch = true in the main repository, or start grit serve with GIT_NO_LAZY_FETCH=0. Only those requests get a promisor fetcher, upload-pack and snapshot checkouts alike; clone bundles and pushes never do. So a server without lazy fetch never fetches anything, and nothing pulls an offloaded blob back into the main repository. A snapshot holds every file it names, so a snapshot checkout follows the same rule as a client that accepted nothing: with lazy fetch on, the server first fetches the offloaded blobs the snapshot needs, all in one request, and they stay in the main repository until the next grit gc offload; with it off, POST /.grit/checkouts/<name> (and update) answer 409 naming the first missing blob and how many there are, and a fetch that fails answers 502. Pushes may name offloaded blobs in their trees. If the LOP sits behind this server's authentication, the server needs credentials for it, like any other client. See Serving a repository whose large blobs live elsewhere.

Running it

grit serve with no subcommand and no --setup runs the server until interrupted. It refuses to start until --setup has created a user. It listens on 127.0.0.1:8080; use --bind 0.0.0.0:8080 to accept connections from other machines. The server speaks plain HTTP, so put it behind a TLS-terminating proxy before sending passwords and tokens across a network you don't trust.

Git smart HTTP connections drop peers that stop sending: --header-timeout (default 30s) closes incomplete request headers, and --idle-timeout (default 60s) closes POST bodies or upload-pack responses that stall between chunks (a large push that keeps sending is unaffected). When --max-git-requests concurrent Git operations (default 128) are already in flight, further info/refs, fetch, push and resumable-push apply requests get HTTP 503 immediately instead of queuing, so the web UI and sign-in still have threads to answer.

On SIGTERM, SIGINT or SIGHUP (Ctrl+C on Windows), the server logs that it is closing the listener, stops accepting new connections, and lets in-flight clone and push requests finish. The clone-bundle background thread stops after its current build. By default it waits up to --shutdown-timeout (30 seconds) for those requests; --shutdown-timeout 0s waits with no cap until they finish. When the grace period ends, remaining connections are closed and in-flight receive-pack hook processes are terminated so the server process can exit. A second signal in that window stops those hooks and exits immediately without waiting.

Options

Option Description
--root <path> A repository, or a directory of repositories, to serve. Defaults to the current directory. Also accepted after a subcommand.
--db <file> The user database. Defaults to grit-serve.db in the root (in its .git directory for a working tree). Also accepted after a subcommand.
--bind <host:port> Address to listen on. Defaults to 127.0.0.1:8080.
--setup Create the database and its first admin user, then exit. Prompts for a password, or generates a temporary one. Fails when the database already has users.
--email <email> Email address of the admin --setup creates. Asked for on a terminal when omitted. Requires --setup.
--bundle-interval <duration> How old a changed repository's clone bundle gets before a new one is built: a number with s, m, h or d. Defaults to 24h.
--no-bundles Do not build or advertise clone bundles.
--header-timeout <duration> How long to wait for a complete HTTP request header on a new connection before closing it. Defaults to 30s.
--idle-timeout <duration> How long to wait between bytes on a Git smart HTTP POST body or upload-pack response before closing the connection. Defaults to 60s.
--max-git-requests <n> Maximum concurrent Git smart HTTP operations (info/refs, fetch, push, resumable push). Further requests get HTTP 503. Defaults to 128.
--shutdown-timeout <duration> After a shutdown signal, how long to keep serving in-flight requests before closing remaining connections. Defaults to 30s; 0s waits until they finish. A second signal exits immediately.
add-user <email> Add a user, named by their email address. Prompts for a password, or generates a temporary one.
add-user --admin Make the new user an admin.
token <email> Create an access token for a user and print it, for scripts and CI.
grant <email> <repository> Give a user read access to a repository, by name with or without .git.
grant --write Give write (push) access instead of read access.
users List users, their tokens and their access.

JSON output

Schema: v1 · serve.add-user v1 · serve.token v1 · serve.grant v1 · serve.users v1

Pass --json with --setup or a subcommand for one JSON object on stdout. The running server has no JSON output: it logs to stderr.

grit serve --setup and grit serve add-user:

Field Type Meaning
database string The user database the user was added to.
user string The new user's email address.
admin boolean Whether the user is an admin (read and write on every repository).
password string or omitted The generated temporary password, shown only once. Omitted when the password was typed in.
temporary boolean Whether the user must choose a new password at their first sign-in (true for a generated password).

grit serve token:

Field Type Meaning
user string The user's email address.
token string The new access token. It is shown only once.

grit serve grant:

Field Type Meaning
user string The email address of the user given access.
repository string The repository name, without .git.
access string read or write.

grit serve users:

Field Type Meaning
database string The user database read.
users array Every user, sorted by email address.
users[].email string The user's email address.
users[].admin boolean Admins read and write every repository.
users[].temporary_password boolean The user still has a generated password and must choose their own at the next sign-in.
users[].tokens integer How many access tokens the user has.
users[].grants array Repository grants, sorted by repository: repository and access (read or write).

Markdown output

Pass --markdown for agent-friendly output.

Schema: v1 · serve.add-user v1 · serve.token v1 · serve.grant v1 · serve.users v1

Markdown uses headings, bullet lists, and tables; pipe characters inside table cells are escaped. See the JSON output section for the stable field contract.

Exit status

Code Meaning
0 Success (success).
1 Command failed (failure): no database, already set up, unknown user, an invalid email address or too short a password, or the server could not start.
2 Invalid flags or arguments (usage).

See Exit codes for shared rules and structured --json kind values.