Express middleware that acts as a git-http-backend
Usage:
var express = require("express");
var expressGit = require("express-git");
var app = express();
app.use("/git", expressGit.serve("path/torepos/", {
auto_init: true,
serve_static: true,
auth: function (service, next) {
// Authorize a service
// this.req holds the request object
// this.res holds the response object
next();
},
hooks: {
'post-receive': function (changes, next) {
// Do something after a push
// this.req holds the request object
// this.res holds the response object
next();
}
}
});
app.listen(3000);
After which you can
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.
default: true
Enable the git_http_backend service.
If set to false
push/pull operations will not be possible over http
.
default: true
Enable the raw service.
default: true
Enable the browse service.
default: true
Enable the commit service.
default: {}
Set to and object with key-value pairs of hook - callback.
All hook callbacks take a callback as the last argument for
asynchronous hook logic.
All hook callbacks will be bound to an object so that
this.req
is the request object and
this.res
is the response object.
The currenctly implemented hooks are
-
pre-init: (repo, callback)
Whererepo
is the name of the repo to be created. Specify individual repoinit_options
withcallback(null, options)
. See Init Options. Prevent the initialization of the repo by passing an error to the callback. -
post-init: (repo, callback)
Whererepo
is anodegit.Repository
object for the new repo. -
pre-receive: (repo, changes, callback)
Wherechanges
is anArray
of{before, after, ref}
objects. Passing an error to the callback will prevent the push request. -
update: (repo, change, callback)
Wherechange
is a{before, after, ref}
object. Passing an error to the callback will prevent the push for this specific ref. -
post-receive: (repo, changes, callback)
Wherechanges
is anArray
of{before, after, ref}
objects. Any error passed to the callback will be reported to the client but will not prevent the request. -
pre-commit: (repo, commit, callback)
Whererepo
is thenodegit.Repository
instance where the commit will happen,commit
is anobject
withref, message, author, tree, parents, committer
keys. Passing an error to the callback will abort the commit. -
post-commit: (repo, commit, callback)
Whererepo
is thenodegit.Repository
instance where the commit happened andcommit
is an object with commit details.
See Git Hooks for more info.
default: noop
A (service, callback)
hook to use to authorize requests.
As with hooks this.req
and this.res
will be bound to the request and response objects. To prevent an action, pass an error to the callback.
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
.
default: true
Allow repos to be created on-demand.
If set to false
only already existing repos will be used.
default: {}
Default init_options
for new repos. See Init options
To override per-repo init_options use hooks['pre-init']
.
default: A year in seconds
The max_age
Cache-Control
header to use for served blobs
default: 2K
The max size of truncated blob data to include in browse requests.
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.
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)
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 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
.
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 theparent
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.
message The commit message
author The commit author (accepts name <email>
format)
committer The committer (accepts name <email>
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.
All form file fields will be added, using the fieldname as path (stemming from basepath if provided).
default: true
default: true
Create the dir for the repository if does not exist
default: true
Create the all required dirs for the repository path
default: null
Permission mask to apply to the repository dir (git init --shared)
default: 'master'
The branch to which HEAD will point.
default: null
A default origin remote to use for this remote. Usually not needed as the repo will probably act as origin for others.
default: null
A GIT_TEMPLATE_PATH to use for the repo.
Each request handled by express-git is assigned a frozen object git
property with
the following properties:
A (name, args...)
function trigerring hooks
The current repository for this request
The service name for this request
Possible service names are:
raw
for raw file requests (ifoptions.serve_static
is enabled)browse
for json browsing of the repos (ifoptions.browse
is enabled)commit
for commits over http (ifoptions.allow_commits
is enabled)receive-pack
for push requestsupload-pack
for fetch requestsadvertise-refs
for ref advertisement before push/pull requests
A (service)
callback for authorising services.
The path relative to the repo root for this request