An express middleware acting as git-http-backend and more
npm install express-git2javascript
var express = require("express");
var expressGit = require("express-git2");
var app = express();
app.use("/git", expressGit.serve("path/torepos/", {
auto_init: true,
serve_static: true,
authorize: function (service, req, next) {
// Authorize a service
next();
}
});
app.on('post-receive', function (repo, changes) {
// Do something after a push
next();
});
app.listen(3000);
`
After which you can
`sh
git clone http://localhost:3000/git/foo.git
cd foo
echo "# Hello Git" > README.md
git add README.md
git commit -m "Initial commit"
git push
`
Which will create an empty repo at path/torepos/foo.git to which you can
pull and push as usual.
Options
$3
> default: true
Enable the git_http_backend service.
If set to false push/pull operations will not be possible over http.
$3
> default: true
Enable the raw service.
$3
> default: true
Enable the browse service.
$3
> default: true
Enable the commit service.
$3
> default: true
Enable the refs service.
$3
> default: noop
A (service, req, callback) hook to use to authorize requests.
To prevent an action, pass an error to the callback.
$3
> default: /.*/
All repo names must match this pattern.
Any captured groups will be passed on to a req.git.repo.args object
for use in options.auth.
$3
> default: true
Allow repos to be created on-demand.
If set to false only already existing repos will be used.
$3
> default: {}
Default init_options for new repos. See Init options
To override per-repo init_options use hooks['pre-init'].
$3
> default: A year in seconds
The max_age Cache-Control header to use for served blobs
$3
> default: 2K
The max size of truncated blob data to include in browse requests.
$3
> default: shelljs.which('git')
For git_http_backend service to work you need git installed on the server.
You can specify the git executable to use with the git_executable option.
Hooks
Git hooks are implemented using events. Async event handlers are supported
via Promises. Event cancellation is possible (for cancellable events)
by rejecting a promise or throwing an error.
Register event listeners via expressGit.on(hook, handler)
Events to listen for:
$3
> Cancellable: yes
Where name is the name of the repo to be created and params is a parameter
array parsed via options.pattern. The 3rd argument init_options
is an object that you can modify to change the initialization options for this repo.
You can return a promise if you need to perform an async operation.
Rejecting will prevent the initialization of the repo.
See [Git Hooks][Git Hooks] for more info.
$3
> Cancellable: no
Where repo is a nodegit.Repository object for the new repo.
$3
> Cancellable: yes
Where changes is an Array of {before, after, ref} objects.
Rejecting will prevent the push request.
$3
> Cancellable: yes
Where change is a {before, after, ref} object.
Rejecting will prevent the push for this specific ref.
$3
> Cancellable: no
Where changes is an Array of {before, after, ref} objects.
Rejecting will be report the error to the client but will not prevent the request.
$3
> Cancellable: yes
Where repo is the nodegit.Repository instance where the commit will happen,
commit is an object with ref, message, author, tree, parents, committer keys.
Rejecting will abort the commit.
$3
> Cancellable: no
Where repo is the nodegit.Repository instance where the commit happened
and commit is an object with commit details.
Services
git_http_backend service
Allow push/pull over http at
`
GET /path/to/repo.git/info/refs?service=(git-receive-pack|git-upload-pack)
POST /path/to/repo.git/(git-receive-pack|git-upload-pack)
`
raw service
Serve blobs from any ref at
`
GET /path/to/repo.git/(ref?)/raw/path/to/file.txt
`
The default ref is HEAD.
The blob's id is added as an Etag header tho the response. The must-revalidate
Cache-Control property is also added, because the ref of the blob-serving url
might point to a different blob after a repository modification. Thus the proxy
must revalidate the freshness on each request.
See HTTP Cache Headers for more info.
browse service
Browse repositories as json
`
GET /path/to/repo.git/(ref?)/blob/(path/to/file.txt)
GET /path/to/repo.git/(ref?)/tree/(path/to/dir)?
GET /path/to/repo.git/(ref?)/commit/
GET /path/to/repo.git/(ref?)/object/(object-id)
`
The default ref is HEAD.
commit service
Git commits using multipart forms
`
POST /path/to/repo.git/(ref?)/commit/(path/to/basepath)?parent=(object-id)
`
> Commit parent id should either be specified by an x-parent-id header
> or the parent query parameter. It will default to the empty object id (40 zeros)
If the provided parent id is not the current target of the ref,
the commit will be rejected with a 409 Confict error response.
$3
- message The commit message
- author The commit author (accepts name format)
- committer The committer (accepts name format), fallback to author
- created_at The of the commit creation (author date)
- remove (can repeated be multiple times) The paths to remove (stemming from basepath if provided). Removals occur before additions.
$3
All form file fields will be added, using the fieldname as path.
(basepath url parameter will be prepended to this path)
refs service
Git ref manipulation via REST
`
PUT /path/to/repo.git/(ref)
DELETE /path/to/repo.git/(ref)
`
$3
- target (str) The target to set the ref to point to
- current (str) The current ref target (to spot conflicts)
- message (str) The commit message
- symbolic (bool)
- signature {name, email, date} A signature to use for the commit
Init options
$3
> default: true
$3
> default: true
Create the dir for the repository if does not exist
$3
> default: true
Create the all required dirs for the repository path
$3
> default: null
Permission mask to apply to the repository dir (git init --shared)
$3
> default: 'master'
The branch to which HEAD will point.
$3
> default: null
A default origin remote to use for this remote.
Usually not needed as the repo will probably act as origin for others.
$3
> default: null
A GIT_TEMPLATE_PATH to use for the repo.
The
req.git object
Each request handled by express-git is assigned a frozen object git property with
the following properties:
$3
A (name, args...) function trigerring hooks
$3
The current repository for this request
$3
The service name for this request
Possible service names are:
- raw for raw file requests (if options.serve_static is enabled)
- browse for json browsing of the repos (if options.browse is enabled)
- commit for commits over http (if options.allow_commits is enabled)
- receive-pack for push requests
- upload-pack for fetch requests
- advertise-refs for ref advertisement before push/pull requests
$3
A (service)` callback for authorising services.