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 |
|
28 | 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:
|
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 |
|
45 | 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.
|
46 | The repository contents can be accessed with the same url patterns you would use to request files managed on GitHub.
|
47 |
|
48 | The 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
|
57 | cd <checkout dir>
|
58 | npm 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
|
119 | cd ./repos
|
120 | # create org
|
121 | mkdir helix && cd helix
|
122 | # initialize new git repo
|
123 | mkdir test && cd test && git init
|
124 | # allow to remotely push to this repo
|
125 | git config receive.denyCurrentBranch updateInstead
|
126 | # add a README.md
|
127 | echo '# test repo'>README.md
|
128 | git add . && git commit -m '1st commit'
|
129 | cd ../../..
|
130 | ```
|
131 |
|
132 | ### 2. Start server
|
133 |
|
134 | ```bash
|
135 | npm start
|
136 | ```
|
137 |
|
138 | ### 3. Fetch raw content of file in Git repo over http
|
139 |
|
140 | ```bash
|
141 | curl 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 |
|
148 | Serving content of a file in a git repo.
|
149 |
|
150 | The 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 |
|
159 | GitHub 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 |
|
164 | Local `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 |
|
170 | Remote 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 |
|
175 | Local 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 |
|
185 | Support for `git clone, push, fetch`
|
186 |
|
187 | Documentation:
|
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 |
|
194 | 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:
|
195 |
|
196 | ```bash
|
197 | git 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 |
|
204 | Documentation: [GitHub API v3](https://developer.github.com/v3/)
|
205 |
|
206 | GitHub Endpoint: `https://api.github.com/`
|
207 |
|
208 | Local endpoint: `http://localhost:{port}/api` or e.g. `http://api.localtest.me:{port}` (using wildcarded DNS domain resolving to `127.0.0.1`)
|
209 |
|
210 | Only 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 |
|
232 | Local 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 |
|
243 | Endpoint: `https://github.com/`
|
244 |
|
245 | e.g.
|
246 |
|
247 | `https://github.com/{owner}/{repo}`,
|
248 | `https://github.com/{owner}/{repo}/blob/{branch}/path/to/file`
|