gitwrit

Private, versioned writing for people who live in the terminal.

Made for git-ters and writ-ters.

gitwrit watches your Markdown files and quietly commits and pushes them to your Git repository—no manual git add, no git commit, no git push. You write. gitwrit handles the rest.

It is built for engineers writing internal specs, researchers building private knowledge bases, AI practitioners documenting models and experiments, and anyone who wants the safety of version control without the overhead of Git discipline. Your files stay in your own repository, on your own terms—not in someone else's cloud.

How it works

gitwrit runs as a background daemon—but not the scary kind you have to exorcise. When you save a file, it waits a few seconds and then commits it locally. Every few minutes, it pushes everything to your remote. If your laptop sleeps, it catches up automatically when you wake it.

The result feels like writing in Google Docs. Your work is always saved—except as plain Markdown without artifacts that sometimes pop up in text editors when you export to Markdown. The files also remain yours, where you want them, and fully versioned.

Install

npm

npm install -g gitwrit

Yarn

yarn global add gitwrit

Updating

To update gitwrit to the latest version:

npm install -g gitwrit@latest

Starting from v0.2.1, gitwrit will automatically notify you when a new version is available after every command—so you will never need to check manually again.

Quick start

cd ~/notes
gitwrit init    # first run sets up global defaults + registers this directory
gitwrit start   # start watching

That's it. Write something, save it, and gitwrit commits it.

Commands

| Command | What it does | |---|---| | gitwrit init | Set up gitwrit in the current directory | | gitwrit start | Start watching your registered directories | | gitwrit stop | Stop the daemon gracefully | | gitwrit restart | Stop and restart (useful after config changes) | | gitwrit status | Show what gitwrit is watching and what it has done lately | | gitwrit logs | Tail the activity log | | gitwrit config | Edit global defaults or local directory overrides | | gitwrit add [path] | Add a directory to your watch list | | gitwrit remove [path] | Remove a directory from your watch list | | gitwrit help | List all available commands |

Configuration

gitwrit stores your global config at ~/.gitwritrc.json. Run gitwrit config to edit it interactively.

Global defaults:

{
  "fileTypes":    [".md", ".mdx"],
  "debounce":     3000,
  "pushInterval": 300000,
  "branchMode":   "current",
  "watch":        []
}

Per-directory overrides:

Run gitwrit config from inside a watched directory to set local overrides. Overrides are stored in .gitwrit.json in that directory. Anything not overridden falls through to your global defaults.

Branch modes

gitwrit supports two branch modes, configurable globally or per directory.

current—Commits to whatever branch you currently have checked out. Switch branches freely; gitwrit follows you.

autogenerated—Creates a fresh named branch at the start of each session. Branch names are generated by combining a random adjective, noun, and verb—like crimson-walrus-stumbling or teal-fox-bouncing. 64,000 possible combinations. Good for keeping autosave history separate from your main branch.

Updates

gitwrit checks for updates automatically after every command. If a newer version is available, you will see a single note at the bottom of your output:

  · Update available: 0.2.1 → 0.3.0   Run npm install -g gitwrit to update.

The check runs in the background, caches for 24 hours, and fails silently if you are offline. It will never interrupt or slow down your workflow.

Compatibility

| Platform | Status | |---|---| | macOS | ✅ Fully supported | | Linux | ✅ Fully supported | | Windows | ❌ Not currently supported |

gitwrit is built for macOS and Linux. Windows is not currently supported—the daemon process management and file system watching rely on POSIX signals (SIGTERM, SIGCONT) that are not available on Windows.

If you are a Windows user and would like to contribute Windows support, please open an issue on GitHub—it is a welcome contribution.

Requirements

• Node.js ≥ 18
• Git
• A configured Git remote (git remote add origin <url>)—gitwrit requires one before it will initialize a directory

Troubleshooting

gitwrit isn't committing my changes

gitwrit watches for file save events. Make sure your editor is actually saving to disk—some terminal editors like Pico and Nano require an explicit save (Ctrl+X → Y) before changes hit the filesystem. gitwrit cannot commit changes that haven't been written to disk yet.

Push failed notification

If gitwrit notifies you that a push failed, first verify that git can push manually from your terminal:

git push

If that works, restart gitwrit with gitwrit restart. If it fails, fix your Git authentication first—gitwrit can only push if git itself can push from a non-interactive terminal session. Make sure your SSH key is configured and registered with your Git provider, or that your HTTPS credentials are cached.

Something else feels off

gitwrit logs is always your first stop. It shows a timestamped record of every commit, push, and error the daemon has encountered.

Why not cloud-based writing tools?

Most cloud-based writing and note-taking tools store your files on their infrastructure. gitwrit does not. Your writing lives in a plain Git repository that you control, pushed wherever you want—GitHub, GitLab, a private server, anywhere that accepts a Git remote.

Just to be clear, there is absolutely nothing wrong with using cloud-based tools. Many people use them every day for good reason!

But gitwrit might be especially useful when cloud storage isn't an option—for proprietary documentation like internal specs, research notes, model cards, experiment logs, etc. For when putting files into a third-party cloud is not an option, or when you want to keep everything essential to your codebase all in one place.

Open source

gitwrit is open source and built to be extended. Contributions are welcome at every level—word lists, new file type support, commit message formatters, and more. See CONTRIBUTING.md and EXTENSIONS.md to get started.

License

MIT