Node.js Git Server

Common errors

• Error: This version of Node.js is not supported.

  cause Attempting to run `node-git-server` version 1.0.0 or higher on Node.js versions older than 16.
  fix Upgrade your Node.js runtime to version 16 or newer. For example, using nvm: `nvm install 16 && nvm use 16`.

• ERR_REQUIRE_ESM

  cause Attempting to `require()` an ESM-only package in a CommonJS context without proper configuration.
  fix Switch to ESM imports: `import { GitServer } from 'node-git-server';` and ensure your `package.json` has `"type": "module"` or files end with `.mjs`.

• TypeError: callback is not a function

  cause Incorrect signature provided to the `authenticate` or `authorize` functions, leading to `callback` being undefined or not a function.
  fix Verify that your `authenticate` and `authorize` function callbacks match the expected `(error, success)` signature and that all arguments are correctly passed as per the documentation (e.g., `(type, repository, username, password, callback)`).

Warnings

• breaking Version 1.0.0 and subsequent versions no longer support Node.js environments older than Node.js 16. Running on unsupported versions will lead to errors.
  Fix: Upgrade your Node.js runtime to version 16 or newer. Use a Node Version Manager (NVM) for easy switching.
• breaking The `authenticate` function signature changed in version 0.6.0. It now accepts an object as the first argument, followed by a callback, allowing for more flexible introspection (e.g., on headers).
  Fix: Update your `authenticate` function to match the new `(type, repository, username, password, callback)` signature, or `(options: { type: string, repository: string, username?: string, password?: string, headers?: object }, callback)`. Refer to the 0.6.0 release notes for details.
• gotcha The library migrated to TypeScript in version 1.0.0-beta.1. While this improves type safety, it implies that the package is primarily consumed as an ESM module. Older CommonJS `require()` statements might encounter issues if not correctly configured or if the package no longer provides a CJS entry point.
  Fix: Ensure your project uses ESM imports (`import ... from '...'`) and is configured for TypeScript. If using CommonJS, check for potential compatibility issues or adjust your `tsconfig.json` and build setup.

Install

• npm install node-git-server npm
• yarn add node-git-server yarn
• pnpm add node-git-server pnpm

Imports

• GitServer
  wrong:

  const GitServer = require('node-git-server');

  correct:

  import { GitServer } from 'node-git-server';

  The library primarily uses ESM and ships TypeScript types. Use named import for the main server class.
• GitServerOptions

  import type { GitServerOptions } from 'node-git-server';

  Import types explicitly for configuration objects or event payloads.
• PushEvent

  import type { PushEvent } from 'node-git-server';

  Type definitions for event payloads like 'push' and 'pull' are available for better type safety.

Quickstart

This quickstart code demonstrates how to set up a basic configurable Git server using node-git-server. It initializes a Git server instance, defines a directory for repositories, implements a simple username/password authentication mechanism, and handles push/fetch events. The server listens on a specified port, allowing users to clone and push to repositories managed by this instance.

import { GitServer } from 'node-git-server';
import path from 'path';
import fs from 'fs';

const REPOS_DIR = path.resolve(process.env.GIT_REPOS_DIR ?? './tmp/repos');

// Ensure the repository directory exists
if (!fs.existsSync(REPOS_DIR)) {
  fs.mkdirSync(REPOS_DIR, { recursive: true });
}

const git = new GitServer(REPOS_DIR, {
  autoCreate: true, // Automatically create repositories on first push
  authenticate: (type, repository, username, password, callback) => {
    console.log(`Authentication attempt: ${type} for ${repository} by ${username}`);
    // In a real application, validate username and password against a database
    if (username === 'gituser' && password === 'gitpass') {
      console.log('Authentication successful.');
      return callback(null, true); // Authentication successful
    }
    console.log('Authentication failed.');
    return callback(new Error('Authentication failed'), false); // Authentication failed
  },
  authorize: (type, repository, username, callback) => {
    console.log(`Authorization attempt: ${type} for ${repository} by ${username}`);
    // In a real application, check permissions based on user and repository
    if (username === 'gituser') {
      console.log('Authorization successful.');
      return callback(null, true); // Authorization successful
    }
    console.log('Authorization failed.');
    return callback(new Error('Authorization failed'), false); // Authorization failed
  },
});

git.on('push', (push) => {
  console.log(`Push event: ${push.repo}/${push.commit} by ${push.branch}`);
  push.accept(); // Accept the push
});

git.on('fetch', (fetch) => {
  console.log(`Fetch event: ${fetch.repo} by ${fetch.branch}`);
  fetch.accept(); // Accept the fetch
});

const PORT = parseInt(process.env.GIT_SERVER_PORT ?? '7000', 10);

git.listen(PORT, () => {
  console.log(`node-git-server running on port ${PORT}`);
  console.log(`Serving repositories from: ${REPOS_DIR}`);
  console.log(`Try cloning: git clone http://localhost:${PORT}/my-repo.git`);
});

// Handle process exit to close server gracefully
process.on('SIGINT', () => {
  console.log('Shutting down git server...');
  git.close(() => {
    console.log('Git server closed.');
    process.exit(0);
  });
});