◈ Backup your code anywhere

Turn any drive into a
git backup remote

Git-Drive transforms external storage volumes into git remote repositories. Backup your code offline, transport it physically, or keep complete control of your data.

Get Started View on GitHub
Terminal
$ git-drive init /Volumes/Backup
✓ Initialized git-drive on Backup
$ git-drive link
✓ Linked my-project → Backup
$ git-drive push
✓ Pushed 3 branches, 12 commits
$

Why Git-Drive?

Simple, reliable, offline-first code backup

Offline Backups

No internet required. Backup directly to USB drives, external HDDs, or network storage.

Full Git Support

Works with all git features—branches, tags, history. Your complete repo, preserved.

Web UI

Beautiful dashboard to manage drives, view repos, and monitor backup status.

Multi-Drive

Handle multiple connected drives simultaneously. Backup to different destinations.

Companion Mode

Run git-drive directly from the drive itself. Portable and self-contained.

Push-All

Backup entire directories of repos with a single command. Bulk operations made easy.

Quick Start

01

Install

npm install -g git-drive
02

Initialize Drive

git-drive init /Volumes/MyDrive
03

Link & Push

git-drive link && git-drive push

See it in Action

A clean, minimal dashboard to manage drives, repos, and backups

localhost:4484
Git-Drive dashboard showing connected drives Repository file browser with branch selector and README preview Companion mode with pending changes indicator

Installation

Choose your preferred package manager or run via Docker

Terminal 
npm install -g git-drive
Terminal 
pnpm add -g git-drive
Terminal 
yarn global add git-drive
Terminal 
# Build the Docker image
docker compose build

# Run the container
docker compose up -d

# Use the CLI through Docker
docker compose run git-drive-cli

Verify Installation

After installation, verify git-drive is working:

git-drive --version

Commands

Complete reference for all git-drive CLI commands

init [path]

Initialize git-drive on an external drive. Prompts for drive selection if no path provided.

Example 
git-drive init /Volumes/MyDrive
link

Link current repo to a drive (interactive selection). Creates the repo in git-drive if it doesn't exist.

Example 
git-drive link
push

Push current repo to the linked drive. Pushes all branches and tags.

Example 
git-drive push
list

Show connected drives and their status. Lists all repos on each drive.

Example 
git-drive list
status

Show detailed status of drives and repos. Includes sync status and last backup time.

Example 
git-drive status
server aliases: start, ui

Start the git-drive web UI server at http://localhost:4483

Example 
git-drive server
companion [path]

Run git-drive from a drive (companion mode). Useful for portable usage.

Example 
git-drive companion /Volumes/MyDrive
push-all

Backup all repos in a directory to a drive. See the Push-All page for detailed options.

Example 
git-drive push-all ~/Developer/
-v, --version

Show the installed version of git-drive.

Example 
git-drive --version

Companion Mode

Run git-drive directly from your external drive

Companion mode allows you to run git-drive directly from an external drive, making it portable and self-contained. This is useful when:

  • You want to use git-drive on multiple computers without installing it
  • You're at a different machine and need to access your backups
  • You want the drive to be completely self-contained

Using Companion Mode

When you run git-drive init on a drive, it automatically installs a companion copy of git-drive on that drive.

Terminal 
# Interactive selection - shows drives with git-drive initialized
git-drive companion

# Direct path - run companion mode from a specific drive
git-drive companion /Volumes/MyDrive
localhost:4484
Git-Drive running in companion mode showing the Companion badge and pending changes

What Happens

1

Finds an available port (starting from 4484)

2

Starts the git-drive server in companion mode

3

Opens your browser to the web UI

4

Shows only the companion drive in the UI

Press Enter to stop the companion server.

Features

◈
Portable

The companion is stored on the drive itself

◈
Self-updating

The companion can be updated from the web UI

◈
Version tracking

Shows companion version and update availability

◈
Port detection

Automatically finds an available port if the default is in use

Push-All Command

Backup all repositories in a directory with a single command

Terminal 
# Backup all repos in a directory
git-drive push-all ~/Developer/

# With options
git-drive push-all ~/Developer/ --drive /Volumes/MyUSB    # Non-interactive drive selection
git-drive push-all ~/Developer/ --init-all                # Initialize non-git directories as repos
git-drive push-all ~/Developer/ --skip-non-git            # Skip non-git directories
git-drive push-all ~/Developer/ --force                   # Override existing drive links

Features

◈
Auto-discovery

Scans directory for git repositories and non-git projects

◈
Non-git handling

Offers to initialize non-git projects as git repos before backing up

◈
Full backup

Pushes all branches and tags for each repository

◈
Auto-link

Automatically links each repo to the selected drive

◈
Progress tracking

Shows real-time progress and summary

Options

Flag Description
--drive Specify the target drive (non-interactive)
--init-all Automatically initialize all non-git projects
--skip-non-git Skip non-git directories without prompting
--force Re-link repos that are already linked to a different drive

Development

Contributing to git-drive

Getting Started

Terminal 
# Clone the repository
git clone https://github.com/josmanvis/git-drive.git
cd git-drive

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run in development mode
pnpm dev

Project Structure

packages/
cli/ Command-line interface
server/ Backend server
ui/ Web UI (React + Vite)

Publishing (Maintainers)

The project uses GitHub Actions for automated publishing to npm. To publish a new version:

  1. Update the version in packages/cli/package.json
  2. Create a new git tag and push to main
  3. The CI will automatically build and publish to npm
⚠

Make sure to set the NPM_TOKEN secret in your GitHub repository settings.

How It Works

Git-drive creates a .git-drive/ directory on the target drive where it stores bare git repositories. The CLI communicates with a local server that manages drive connections and repository operations.

When you run git-drive link, it:

  1. Creates a bare repo on the drive (if needed)
  2. Adds a git remote named "git-drive" to your local repo
  3. Push operations go directly to the drive via standard git protocols

The CLI automatically starts the git-drive server in the background when needed, so commands like link, push, list, and status work immediately without manually starting the server first.

License

MIT License - see LICENSE for details.