gls — Git Local Server

Turn any folder on your machine into a Git remote server over HTTP using the Git Smart HTTP protocol. Supports clone, fetch, and push with HTTP Basic Authentication — no tokens required.

npm install -g git-local-server
gls start .
git clone http://admin:admin123@localhost:4006/admin/myproject.git

Features

• ✅ Git Smart HTTP — full git clone / git fetch / git push support
• ✅ HTTP Basic Auth — no tokens, no Bearer, no query-param auth
• ✅ Open access — set password to null/"" for password-less login
• ✅ SQLite storage — data.db auto-created with default users
• ✅ Auto-create repos — bare repo created on first push
• ✅ User isolation — users can only push to their own /<username>/ path
• ✅ Management API — create/delete repos and users programmatically
• ✅ Port fallback — if the port is busy, auto-increments until a free port is found
• ✅ Daemon mode (-d) — run as a background process
• ✅ Silent mode (--silent) — suppress all console output
• ✅ Cross-platform — Windows, macOS, Linux
• ✅ Single dependency — only Express.js (plus better-sqlite3)

Installation

npm install -g git-local-server

This makes the gls command available globally.

Requirements

• Node.js >= 16
• Git installed and available in PATH

Usage

Start the server

gls start [path] [options]

| Argument / Option | Description | |------------------|-------------| | path | Directory to serve as git server root (default: current directory) | | -p, --port <n> | Port to listen on (default: 4006). Auto-increments if busy. | | -H, --host <ip> | Host to bind to (default: 0.0.0.0) | | -s, --silent | Suppress all stdout output | | -d | Run as daemon (background process) |

Stop the daemon

gls stop

Reads the PID from <server-root>/.gls.pid and sends SIGTERM.

Help

gls --help
gls start --help

Examples

Basic usage

# Start server in current directory
gls start .

# Clone a repo
git clone http://admin:admin123@localhost:4006/admin/demo.git

# Make changes and push
cd demo
echo "hello" > README.md
git add README.md
git commit -m "initial"
git push origin main

Custom port and host

gls start /path/to/repos -p 3000 -H 127.0.0.1

Silent mode

gls start . --silent

Daemon (background) mode

gls start . -d
gls stop

All options together

gls start /path/to/repos --port 8080 --host 0.0.0.0 --silent -d

URL Structure

http://<host>:<port>/<username>/<project>.git

Examples:

http://localhost:4006/alice/myproject.git
http://127.0.0.1:3000/admin/demo.git

When cloning:

git clone http://<username>@<host>:<port>/<username>/<project>.git

The password is prompted interactively by Git, or you can embed it in the URL:

git clone http://username:password@host:port/username/project.git

Authentication

• HTTP Basic Authentication is the only auth mechanism
• No tokens, no Bearer tokens, no query-param authentication
• No /auth/login, /auth/verify, or /auth/logout endpoints
• If a user's password is null or "" (empty string), any password is accepted (open access)
• If a user's password is a non-empty string, it must match exactly

Default Users

| Username | Password | |----------|----------| | admin | admin123 | | alice | (no password — open access) |

These are auto-created when data.db is first initialized.

Data Storage

All data is stored in SQLite at <server-root>/data.db (auto-created).

Schema

CREATE TABLE users (
    username TEXT PRIMARY KEY,
    password TEXT,          -- NULL or '' means no password required
    projects TEXT DEFAULT '[]'  -- JSON array of project names
);

Repositories

Bare Git repositories are stored at:

<server-root>/repos/<username>/<project>.git/

They are auto-created on the first git push to a new project.

Management API

All management endpoints require HTTP Basic Authentication.

Repository Management

| Method | Endpoint | Description | Auth | |--------|----------|-------------|------| | POST | /api/create/<username>/<project> | Create a new bare repository | user must match | | DELETE | /api/delete/<username>/<project> | Delete a repository | user must match | | GET | /<username>/ | List user's repositories (HTML) | user must match |

User Management (admin only)

| Method | Endpoint | Description | Auth | |--------|----------|-------------|------| | GET | /api/users | List all users | admin only | | POST | /api/users | Create a new user | admin only | | DELETE | /api/users/<username> | Delete a user | admin only | | PUT | /api/users/<username>/password | Change a user's password | user or admin |

API Examples

# Create a repo
curl -u admin:admin123 -X POST http://localhost:4006/api/create/admin/myproject

# Delete a repo
curl -u admin:admin123 -X DELETE http://localhost:4006/api/delete/admin/myproject

# List users (admin only)
curl -u admin:admin123 http://localhost:4006/api/users

# Create a new user (admin only)
curl -u admin:admin123 -X POST http://localhost:4006/api/users \
  -H "Content-Type: application/json" \
  -d '{"username": "bob", "password": "secret"}'

# Change password (user or admin)
curl -u admin:admin123 -X PUT http://localhost:4006/api/users/alice/password \
  -H "Content-Type: application/json" \
  -d '{"password": "newpass"}'

How It Works

gls implements the Git Smart HTTP protocol, which is the standard protocol Git uses over HTTP(S). When you run git clone, git fetch, or git push against an HTTP remote, Git makes a series of HTTP requests:

1. Discovery — GET .../info/refs?service=git-upload-pack (or git-receive-pack) to discover available refs
2. Data transfer — POST .../git-upload-pack (for fetch) or POST .../git-receive-pack (for push) with binary packet data

All Git subprocesses use --stateless-rpc mode, and communication happens via stdin/stdout pipes. A 5-minute timeout is enforced on all Git operations.

Package Structure

git-local-server/
├── index.js          # Single-file Express app + CLI
├── package.json      # npm package config
├── README.md         # This file
├── .gitignore
├── .npmignore
├── TASK.md           # Task requirements
├── data.db           # SQLite database (created at runtime)
├── repos/            # Bare git repositories (created at runtime)
└── node_modules/

License

MIT