@adobe/git-server 中文文档教程

Question

git-server

GitHub 协议 & API 模拟。

• Status
• Description
• Installation
• Getting started
• 1. Create a local Git repository
• 2. Start server
• 3. Fetch raw content of file in Git repo over http
• Git Protocols and APIs
• 1. Git Raw Protocol
• 2. Git HTTP Transfer Protocols
  • git push support
• 3. GitHub API v3
• 4. GitHub-like Web Server

---

Status

Description

git-server 为 Git 提供本地 Git 存储库的层次结构客户端通过 http:// 和 https:// 协议访问存储库。

git-server 期望本地 Git 存储库（克隆的或使用 git init 创建的）在本地文件系统中按如下方式组织：

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

或者，虚拟存储库映射允许独立于它们在文件系统中的位置的“挂载”存储库到 / 层次结构中。 一个配置示例：

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

通过 git-server 公开的存储库可以像 GitHub 上托管的任何存储库一样使用，即您可以克隆它们并将更改推送到。 可以使用与请求 GitHub 上管理的文件相同的 url 模式访问存储库内容。

目前支持以下协议和 API：

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

Installation

cd <checkout dir>
npm install

Getting started

git-server 通过 config.js 文件配置，该文件预计存在于当前工作目录中。 这是默认配置：

{
  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', // fatal, error, warn, info, verbose, debug, trace
    logsDir: './logs',
    reqLogFormat: 'short', // used for morgan (request logging)
  },
}

git-server 使用 helix-log 进行日志记录。 日志级别（fatal、error、warn、info、verbose、< code>debug, trace) 可以通过配置中的 logs.level 属性设置（见上文）。 有关详细信息，请参阅 helix-log 项目。

1. Create a local Git repository

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 ../../..

2. Start server

npm start

3. Fetch raw content of file in Git repo over http

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

Git Protocols and APIs

1. Git Raw Protocol

在 git 仓库中提供文件内容。

请求的文件指定为：

• {owner}: GitHub organization or user
• {repo}: repository name
• {ref}: Git reference
• branch name (e.g. main)
• 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

本地 git-server URLs：

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

远程示例：

• https://raw.githubusercontent.com/adobe/git-server/main/README.md
• https://github.com/adobe/git-server/raw/main/README.md

本地示例：

• http://raw.localtest.me:5000/adobe/git-server/main/README.md
• http://localhost:5000/adobe/git-server/raw/main/README.md
• http://localhost:5000/raw/adobe/git-server/main/README.md

raw.githubusercontent.com 服务于某些文件类型（例如 JavaScript、CSS , HTML) 带有不正确的 Content-Type: text/plain 标头。 像 rawgit.com 这样的第三方解决方案解决了这个问题。 git-server 提供内容类型正确的文件。

2. Git HTTP Transfer Protocols

支持 git clone、push、fetch

文档：

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

git push support

服务的本地 repo 需要是 bare repo（git clone --bare 或 < code>git init --bare) 或需要设置以下选项：

git config receive.denyCurrentBranch updateInstead

更多信息

3. GitHub API v3

文档：GitHub API v3< /a>

GitHub 端点：https://api.github.com/

本地端点：http://localhost:{port}/api 或例如 http ://api.localtest.me:{port}（使用通配符 DNS 域解析为 127.0.0.1）

仅支持 GitHub API 的一小部分：

• 获取内容

  注意： GitHub 实现支持最​​大 1 兆字节的文件。

• 获取 blob

  注意： GitHub 实现支持 blob up到 100 兆字节的大小。

• 获取树

• 获取提交

• 获取存档链接

  注意：此方法返回 302 到 URL 以下载存储库的 tarball 或 zipball 存档。 git-server 还支持非官方的 https://codeload.github.com 端点，该端点不受速率限制且不重定向：

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

  相关问题/讨论：#5 支持 codeload.github.com

本地示例：

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

4. GitHub-like Web Server

（尚未实现）

端点：https://github.com/

例如

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