git-service-lite

A lightweight Node.js Git HTTP service designed for single‑user scenario. It provides a simple HTTP interface to interact with local Git repositories, making it ideal when a full‑featured Git server would be unnecessary.

Features

• Clone, fetch, push, and pull over HTTP (default access limited to the service host IP)
• Basic authentication using a randomly generated key
• Configurable repository root directory
• Uses the local user's Git configuration for committing (name & email)

Installation

npm install -g git-service-lite

Quick Start

Example: Linux (bash)

# Create a directory to store your repositories
mkdir -p ~/git-repos
cd ~/git-repos

# Create a group folder and initialize a bare repository
mkdir -p ./my-project-group
cd ./my-project-group
git init --bare my-project.git

# Start the service (default port 3000)
GIT_SERVICE_REPOSITORIES_ROOT=~/git-repos git-service

Example: Windows (PowerShell)

# Create a directory to store your repositories
New-Item -ItemType Directory -Path "$HOME\git-repos" -Force
Set-Location "$HOME\git-repos"

# Create a group folder and initialize a bare repository
New-Item -ItemType Directory -Path ".\my-project-group" -Force
Set-Location ".\my-project-group"
git init --bare my-project.git

# Start the service (default port 3000)
$env:GIT_SERVICE_REPOSITORIES_ROOT = "$HOME\git-repos"
git-service

The service will now listen on http://localhost:3000. You can clone the repository with:

git clone http://localhost:3000/git/my-project-group/my-project.git

Usage

Run the service with the following environment variables. All variables are optional; defaults are shown in the table.

| Environment Variable | Type | Default | Description | |--------------------------------------------|--------|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | LOG_LEVEL | string | debug | Log output level. Options: error, warn, info, debug. Affects both console and file logs. | | LOG_FILE_PATH | string | (empty) | Full path to the log file. If omitted and ENABLE_CONSOLE_LOG is off, the service will fail to start because there is no log destination. | | ENABLE_CONSOLE_LOG | string | on (equivalent to true) | Set to any value other than on to disable console logging. | | GIT_REPOSITORIES_ROOT | string | ./repos (relative to the user's home directory) | Root directory for all managed Git repositories. All repositories must reside under this directory. | | GIT_SERVICE_ADDRESS | string | 127.0.0.1 | IP address the service binds to. | | GIT_SERVICE_PORT | string | 3000 | TCP port the service listens on. | | GIT_SERVICE_BASE_URL | string | Auto‑generated from GIT_SERVICE_ADDRESS and GIT_SERVICE_PORT | Public base URL (e.g., http://localhost:3000). Override to force http or https. | | GIT_SERVICE_ALLOWED_REQUEST_ADDRESS_LIST | string | <GIT_SERVICE_ADDRESS> | Whitelist of IPs allowed to access the service, separated by semicolons (;). Example: 192.168.0.101;192.168.0.102. | | GIT_SERVICE_KEY_UPDATE_TIMESPAN | string | 86400 (seconds) | Interval for regenerating the service’s certificate, in seconds. | | GIT_COMMITTER_NAME | string | Read from ~/.gitconfig or must be provided manually | Name used for Git commits. If empty, a ConfigError is thrown. | | GIT_COMMITTER_EMAIL | string | Read from ~/.gitconfig or must be provided manually | Email used for Git commits. If empty, a ConfigError is thrown. | | GIT_COMMITTER_SECRET | string | (empty) | Secret used for authenticating access to the service. If this variable is left empty or deemed insecure, a random secret will be generated automatically. |

Example: Linux (bash)

export LOG_LEVEL=info
export LOG_FILE_PATH=/var/log/git-service.log
export ENABLE_CONSOLE_LOG=off
export GIT_REPOSITORIES_ROOT=/srv/git-repos
export GIT_SERVICE_ADDRESS=192.168.0.100
export GIT_SERVICE_PORT=8080
export GIT_SERVICE_ALLOWED_REQUEST_ADDRESS_LIST=192.168.0.101;192.168.0.102   # The service host address (192.168.0.100) is added by default
export GIT_SERVICE_KEY_UPDATE_TIMESPAN=43200   # 12 hours
export GIT_COMMITTER_NAME="Qfield"
export GIT_COMMITTER_EMAIL="[email protected]"

Example: Windows (PowerShell)

$env:LOG_LEVEL = "info"
$env:LOG_FILE_PATH = "C:\Logs\git-service.log"
$env:ENABLE_CONSOLE_LOG = "off"
$env:GIT_REPOSITORIES_ROOT = "D:\git-repos"
$env:GIT_SERVICE_ADDRESS = "192.168.0.100"
$env:GIT_SERVICE_PORT = "8080"
$env:GIT_SERVICE_ALLOWED_REQUEST_ADDRESS_LIST = "192.168.0.101;192.168.0.102"
$env:GIT_SERVICE_KEY_UPDATE_TIMESPAN = "43200"
$env:GIT_COMMITTER_NAME = "Qfield"
$env:GIT_COMMITTER_EMAIL = "[email protected]"

Safe Mode

The --safe flag can be used to verify all repositories under the configured root directory before starting the service. It runs git fsck on each repository and exits with a non‑zero status if any errors are found.

git-service --safe