git-server serves a hierarchy of local Git repositories to Git clients accessing the repository over http:https:// and https:// protocol.

git-server expects the local Git repositories (either cloned or created with git init) to be organized as follows in the local file system:

<repos_root_dir>/
├── <owner_1>/
│   └── <repo_1>
│   └── <repo_2>
├── <owner_2>/
│   └── <repo_1>
│   └── <repo_2>

Alternatively, a virtual repository mapping allows to 'mount' repositories independent of their location in the file system into a <owner>/<repo> hierarchy. A configuration example:

  virtualRepos: {
    owner1: {
      repo1: {
        path: './repo1',
      },
    },
    owner2: {
      repo2: {
        path: '/repos/repo2',
      },
    },
  },

Repositories exposed via git-server can be used just like any repository hosted on GitHub, i.e. you can clone them and push changes to. The repository contents can be accessed with the same url patterns you would use to request files managed on GitHub.

The following protocols and APIs are currently supported:

• Git Raw protocol
• Git HTTP Transfer Protocols
• GitHub API v3

git-server includes the nodegit dependency, a native addon which will be built from source on npm install. A proper C/C++ compiler toolchain (gcc etc) is therefore required. See the platorm specific information below to install/enable the compiler toolchain (if not done so already).

Run the following commands in a shell:

sudo xcode-select --install

More information

Once you've made sure you meet above prerequisites you can build & install git-server using

npm install

git-server is configured via the config.js file which is expected to exist in the current working directory. Here's the default configuration:

{
  appTitle: 'Helix Git Server',
  repoRoot: './repos',
  // repository mapping. allows to 'mount' repositories outside the 'repoRoot' structure.
  virtualRepos: {
    demoOwner: {
      demoRepo: {
        path: './virtual/example',
      },
    },
  },
  listen: {
    http: {
      port: 5000,
      host: '0.0.0.0',
    },
    /*
    // https is optional
    https: {
      // cert: if no file is specfied a selfsigned certificate will be generated on-the-fly
      // cert: './localhost.crt',
      // key: if no file is specfied a key will be generated on-the-fly
      // key: './localhost.key',
      port: 5443,
      host: '0.0.0.0',
    },
    */
  },
  subdomainMapping: {
    // if enabled, <subdomain>.<baseDomain>/foo/bar/baz will be
    // resolved/mapped to 127.0.0.1/<subdomain>/foo/bar/baz
    enable: true,
    baseDomains: [
      // some wildcarded DNS domains resolving to 127.0.0.1
      'localtest.me',
      'lvh.me',
      'vcap.me',
      'lacolhost.com',
    ],
  },
  logs: {
    level: 'info', // error, warn, info, verbose, debug, silly
    logsDir: './logs',
    reqLogFormat: 'short', // used for morgan (request logging)
  },
}

git-server comes with a built-in winston logger. The log level (error, warn, info, verbose, debug, silly) can be set via the logs.level property in the config (see above).

Alternatively you can pass your own winston logger instance:

// git server
const gitServer = require('@adobe/git-server/lib/server.js');
// git server config
const config = require('./config.js');
// inject winston logger instance
config.logger = require('winston').createLogger({ /* ... */ });

gitServer.start(config);

cd ./repos
# create org
mkdir helix && cd helix
# initialize new git repo 
mkdir test && cd test && git init
# allow to remotely push to this repo
git config receive.denyCurrentBranch updateInstead
# add a README.md
echo '# test repo'>README.md
git add . && git commit -m '1st commit'
cd ../../..

npm start

curl http:https://localhost:5000/raw/helix/test/master/README.md

Serving content of a file in a git repo.

The requested file is specified by:

• {owner}: GitHub organization or user
• {repo}: repository name
• {ref}: Git reference
  • branch name (e.g. master)
  • tag name (e.g. v1.0)
  • (full or shorthand) commit id (e.g. 7aeff3d)

GitHub URLs:

• https://raw.githubusercontent.com/{owner}/{repo}/{ref}/path/to/file
• https://github.com/{owner}/{repo}/raw/{ref}/path/to/file

Local git-server URLs:

• http:https://localhost:{port}/raw/{owner}/{repo}/{ref}/path/to/file
• http:https://localhost:{port}/{owner}/{repo}/raw/{ref}/path/to/file
• http:https://raw.localtest.me:{port}/{owner}/{repo}/{ref}/path/to/file (using wildcarded DNS domain resolving to 127.0.0.1)

Remote examples:

• https://raw.githubusercontent.com/adobe/project-helix/master/README.md
• https://github.com/adobe/project-helix/raw/master/README.md

Local examples:

• http:https://raw.localtest.me:5000/adobe/project-helix/master/README.md
• http:https://localhost:5000/adobe/project-helix/raw/master/README.md
• http:https://localhost:5000/raw/adobe/project-helix/master/README.md

raw.githubusercontent.com serves certain file types (e.g. JavaScript, CSS, HTML) with incorrect Content-Type: text/plain header. 3rd party solutions like rawgit.com address this issue. git-server serves files with correct content type.

Support for git clone, push, fetch

Documentation:

• 10.6 Git Internals - Transfer Protocols
• Git HTTP transport protocol documentation

The served local repo needs to be either a bare repo (git clone --bare or git init --bare) or the following option needs to be set:

git config receive.denyCurrentBranch updateInstead

more information

Documentation: https://developer.github.com/v3/

GitHub Endpoint: https://api.github.com/

Local endpoint: http:https://localhost:{port}/api or e.g. http:https://api.localtest.me:{port} (using wildcarded DNS domain resolving to 127.0.0.1)

Only a small subset of the GitHub API will be supported:

• Get contents

  Note: The GitHub implementation supports files up to 1 megabyte in size.

• Get blob

  Note: The GitHub implementation supports blobs up to 100 megabytes in size.

• Get tree

• Get commits

• Get archive link

  Note: This method returns a 302 to a URL to download a tarball or zipball archive for a repository. git-server also supports an unofficial https://codeload.github.com endpoint that is not rate limited and that doesn't redirect:

  • https://codeload.github.com/{owner}/{repo}/[zip|tar.gz]/master

  Related issue/discussion: #5 Support codeload.github.com

Local examples:

• http:https://api.localtest.me:5000/repos/adobe/project-helix/contents/README.md?ref=master
• http:https://api.localtest.me:5000/repos/adobe/project-helix/git/blobs/bf13fe66cbee379db6a3e4ebf0300b8bbc0f01b7
• http:https://localhost:5000/api/repos/adobe/project-helix/contents/README.md?ref=master
• http:https://localhost:5000/api/repos/adobe/project-helix/git/blobs/bf13fe66cbee379db6a3e4ebf0300b8bbc0f01b7

(not yet implemented)

Endpoint: https://github.com/

e.g.

https://github.com/{owner}/{repo}, https://github.com/{owner}/{repo}/blob/{branch}/path/to/file