Quick Start

This guide starts with the free CLI and the Personal Provider. No GitBraints account is required. SaaS key hosting and Grant are optional upgrades, not a prerequisite for encryption.

Prerequisites

1. Install the CLI: Install GitLocker globally with npm, then confirm gitl is on your PATH:

   npm install -g gitlocker@latest
   gitl --version
   

   On Linux or macOS, a global install may need extra permissions unless your npm prefix points to a user directory; on Windows, run the command in PowerShell or Command Prompt.
2. Enter a Git repository:

   cd /path/to/your/repo
   

Step 1: Initialize (Personal Provider)

At the repository root:

gitl init

GitLocker will:

1. Detect the current repository.
2. Register Git filters (invoked by Git, not daily user commands).
3. Create a local Personal Provider project key. GitBraints does not receive this key.
4. Write .gitlocker/config.

If you later want hosted keys, switch to the Server Provider and sign in to GitBraints. You do not need SaaS on the first gitl init.

Step 2: Encrypt selected paths

Use gitl encrypt to choose files or directories that should become ciphertext in Git:

gitl encrypt "config/production.json" "secrets/**"

This is the user-facing repository encryption entry. It does not rewrite older Git history into ciphertext by default.

When git status shows changes, commit them:

git add -A
git commit -m "Encrypt production config and secrets"

Step 3: Keep using Git as usual

git add config/production.json secrets/api-key.env
git commit -m "Update encrypted secrets"
git push origin main

The remote stores ciphertext blobs. The Git host can still see paths, authors, and timestamps. It should not see readable contents of encrypted files.

Step 4: The working tree is plaintext after checkout

git checkout main

After a successful checkout, editors see plaintext. GitLocker does not protect an already-checked-out working tree. Keep using OS permissions and Git hosting ACL for the machine and private repositories.

Optional: SaaS key hosting and Grant

When you need hosted keys across machines or Grant-based fetch for collaborators, use the Server Provider:

1. Sign in to GitBraints in the browser (including MFA).
2. Complete Device or PKCE login from the CLI.
3. Bind the Server Provider, then issue a Grant from /home/gitlocker or the team page.
4. Collaborators keep using their own gitl login. Remove Git hosting access first when someone leaves.

SaaS is not zero-knowledge. Revoke does not instantly wipe cached keys. Rotation does not rewrite Git history.

Done. Continue with the GitLocker overview for boundaries and the collaboration model.