UNPKG

8.49 kBMarkdownView Raw
1# git-server
2
3## Status
4
5[![codecov](https://img.shields.io/codecov/c/github/adobe/git-server.svg)](https://codecov.io/gh/adobe/git-server)
6[![CircleCI](https://img.shields.io/circleci/project/github/adobe/git-server.svg)](https://circleci.com/gh/adobe/git-server)
7[![GitHub license](https://img.shields.io/github/license/adobe/git-server.svg)](https://github.com/adobe/git-server/blob/master/LICENSE.txt)
8[![GitHub issues](https://img.shields.io/github/issues/adobe/git-server.svg)](https://github.com/adobe/git-server/issues)
9[![Renovate](https://badges.renovateapi.com/github/adobe/git-server)](https://github.com/marketplace/renovate)
10[![LGTM Code Quality Grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/adobe/git-server.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/adobe/git-server)
11
12## Description
13
14`git-server` serves a hierarchy of local Git repositories to Git clients accessing the repository over `http://` and `https://` protocol.
15
16`git-server` expects the local Git repositories (either cloned or created with `git init`) to be organized as follows in the local file system:
17
18```ascii
19<repos_root_dir>/
20├── <owner_1>/
21│   └── <repo_1>
22│   └── <repo_2>
23├── <owner_2>/
24│   └── <repo_1>
25│   └── <repo_2>
26```
27
28Alternatively, a virtual repository mapping allows to 'mount' repositories independent of their location in the file system into a `<owner>/<repo>` hierarchy. A configuration example:
29
30```js
31 virtualRepos: {
32 owner1: {
33 repo1: {
34 path: './repo1',
35 },
36 },
37 owner2: {
38 repo2: {
39 path: '/repos/repo2',
40 },
41 },
42 },
43```
44
45Repositories exposed via `git-server` can be used just like any repository hosted on GitHub, i.e. you can clone them and push changes to.
46The repository contents can be accessed with the same url patterns you would use to request files managed on GitHub.
47
48The following protocols and APIs are currently supported:
49
50* [Git Raw protocol](#1-git-raw-protocol)
51* [Git HTTP Transfer Protocols](#2-git-http-transfer-protocols)
52* [GitHub API v3](#3-github-api-v3)
53
54## Installation
55
56```bash
57cd <checkout dir>
58npm install
59```
60
61## Getting started
62
63`git-server` is configured via the `config.js` file which is expected to exist in the current working directory. Here's the default configuration:
64
65```javascript
66{
67 appTitle: 'Helix Git Server',
68 repoRoot: './repos',
69 // repository mapping. allows to 'mount' repositories outside the 'repoRoot' structure.
70 virtualRepos: {
71 demoOwner: {
72 demoRepo: {
73 path: './virtual/example',
74 },
75 },
76 },
77 listen: {
78 http: {
79 port: 5000,
80 host: '0.0.0.0',
81 },
82 /*
83 // https is optional
84 https: {
85 // cert: if no file is specfied a selfsigned certificate will be generated on-the-fly
86 // cert: './localhost.crt',
87 // key: if no file is specfied a key will be generated on-the-fly
88 // key: './localhost.key',
89 port: 5443,
90 host: '0.0.0.0',
91 },
92 */
93 },
94 subdomainMapping: {
95 // if enabled, <subdomain>.<baseDomain>/foo/bar/baz will be
96 // resolved/mapped to 127.0.0.1/<subdomain>/foo/bar/baz
97 enable: true,
98 baseDomains: [
99 // some wildcarded DNS domains resolving to 127.0.0.1
100 'localtest.me',
101 'lvh.me',
102 'vcap.me',
103 'lacolhost.com',
104 ],
105 },
106 logs: {
107 level: 'info', // fatal, error, warn, info, verbose, debug, trace
108 logsDir: './logs',
109 reqLogFormat: 'short', // used for morgan (request logging)
110 },
111}
112```
113
114`git-server` uses [helix-log](https://github.com/adobe/helix-log) for logging. The log level (`fatal`, `error`, `warn`, `info`, `verbose`, `debug`, `trace`) can be set via the `logs.level` property in the config (see above). For more information please refer to the [helix-log](https://github.com/adobe/helix-log) project.
115
116### 1. Create a local Git repository
117
118```bash
119cd ./repos
120# create org
121mkdir helix && cd helix
122# initialize new git repo
123mkdir test && cd test && git init
124# allow to remotely push to this repo
125git config receive.denyCurrentBranch updateInstead
126# add a README.md
127echo '# test repo'>README.md
128git add . && git commit -m '1st commit'
129cd ../../..
130```
131
132### 2. Start server
133
134```bash
135npm start
136```
137
138### 3. Fetch raw content of file in Git repo over http
139
140```bash
141curl http://localhost:5000/raw/helix/test/master/README.md
142```
143
144## Git Protocols and APIs
145
146### <a name="raw_prot"></a>1. Git Raw Protocol
147
148Serving content of a file in a git repo.
149
150The requested file is specified by:
151
152* `{owner}`: GitHub organization or user
153* `{repo}`: repository name
154* `{ref}`: Git reference
155 * branch name (e.g. `master`)
156 * tag name (e.g. `v1.0`)
157 * (full or shorthand) commit id (e.g. `7aeff3d`)
158
159GitHub URLs:
160
161* `https://raw.githubusercontent.com/{owner}/{repo}/{ref}/path/to/file`
162* `https://github.com/{owner}/{repo}/raw/{ref}/path/to/file`
163
164Local `git-server` URLs:
165
166* `http://localhost:{port}/raw/{owner}/{repo}/{ref}/path/to/file`
167* `http://localhost:{port}/{owner}/{repo}/raw/{ref}/path/to/file`
168* `http://raw.localtest.me:{port}/{owner}/{repo}/{ref}/path/to/file` (using wildcarded DNS domain resolving to `127.0.0.1`)
169
170Remote examples:
171
172* `https://raw.githubusercontent.com/adobe/project-helix/master/README.md`
173* `https://github.com/adobe/project-helix/raw/master/README.md`
174
175Local examples:
176
177* `http://raw.localtest.me:5000/adobe/project-helix/master/README.md`
178* `http://localhost:5000/adobe/project-helix/raw/master/README.md`
179* `http://localhost:5000/raw/adobe/project-helix/master/README.md`
180
181`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.
182
183### <a name="xfer_prot"></a>2. Git HTTP Transfer Protocols
184
185Support for `git clone, push, fetch`
186
187Documentation:
188
189* [10.6 Git Internals - Transfer Protocols](https://git-scm.com/book/en/v2/Git-Internals-Transfer-Protocols)
190* [Git HTTP transport protocol documentation](https://github.com/git/git/blob/master/Documentation/technical/http-protocol.txt)
191
192#### `git push` support
193
194The 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:
195
196```bash
197git config receive.denyCurrentBranch updateInstead
198```
199
200[more information](https://stackoverflow.com/questions/804545/what-is-this-git-warning-message-when-pushing-changes-to-a-remote-repository/28262104#28262104)
201
202### 3. GitHub API v3
203
204Documentation: [GitHub API v3](https://developer.github.com/v3/)
205
206GitHub Endpoint: `https://api.github.com/`
207
208Local endpoint: `http://localhost:{port}/api` or e.g. `http://api.localtest.me:{port}` (using wildcarded DNS domain resolving to `127.0.0.1`)
209
210Only a small subset of the GitHub API will be supported:
211
212* [Get contents](https://developer.github.com/v3/repos/contents/#get-contents)
213
214 _Note:_ The GitHub implementation supports files up to 1 megabyte in size.
215
216* [Get blob](https://developer.github.com/v3/git/blobs/#get-a-blob)
217
218 _Note:_ The GitHub implementation supports blobs up to 100 megabytes in size.
219
220* [Get tree](https://developer.github.com/v3/git/trees/#get-a-tree-recursively)
221
222* [Get commits](https://developer.github.com/v3/repos/commits/#list-commits-on-a-repository)
223
224* [Get archive link](https://developer.github.com/v3/repos/contents/#get-archive-link)
225
226 _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:
227
228 * `https://codeload.github.com/{owner}/{repo}/[zip|tar.gz]/master`
229
230 Related issue/discussion: [#5 Support codeload.github.com](https://github.com/adobe/git-server/issues/5#issuecomment-403072428)
231
232Local examples:
233
234* `http://api.localtest.me:5000/repos/adobe/project-helix/contents/README.md?ref=master`
235* `http://api.localtest.me:5000/repos/adobe/project-helix/git/blobs/bf13fe66cbee379db6a3e4ebf0300b8bbc0f01b7`
236* `http://localhost:5000/api/repos/adobe/project-helix/contents/README.md?ref=master`
237* `http://localhost:5000/api/repos/adobe/project-helix/git/blobs/bf13fe66cbee379db6a3e4ebf0300b8bbc0f01b7`
238
239### 4. GitHub-like Web Server
240
241_(not yet implemented)_
242
243Endpoint: `https://github.com/`
244
245e.g.
246
247 `https://github.com/{owner}/{repo}`,
248 `https://github.com/{owner}/{repo}/blob/{branch}/path/to/file`