git-service-lite

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="[e-mail]"

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 = "[e-mail]"

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