https://github.com/timboudreau/gittattle

A simple, minimal web ui for git using node.js
https://github.com/timboudreau/gittattle

git http-server server

Last synced: about 2 months ago
JSON representation

A simple, minimal web ui for git using node.js

• Host: GitHub
• URL: https://github.com/timboudreau/gittattle
• Owner: timboudreau
• Created: 2013-08-16T05:22:14.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2013-11-08T04:47:57.000Z (about 11 years ago)
• Last Synced: 2023-04-04T00:38:15.012Z (almost 2 years ago)
• Topics: git, http-server, server
• Language: JavaScript
• Size: 218 KB
• Stars: 8
• Watchers: 2
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
Gittattle

=========

Implements a simple, read-only REST API on top of a directory of Git repositories,

allowing for basic browsing, and a simple single-page web UI on top of that.

Does not require a working directory - files are served using ``git show``.

The git repository subdirectory names must end with ``.git``.

Why?  Gitweb is awful, Cgit is painful to set up;  and for a lot of cases,

a full fledged push/pull-over-http server is more than you need.  It was 

written with [Gitolite](https://github.com/sitaramc/gitolite) in mind,

but it will work with any system that contains a folder of Git repositories. 

The idea is to painlessly 

provide a reasonable read-only UI on the web with minimum pain, and provide a REST

api for widgets showing recent commits and such.

It's written in node.js and can be run from the command-line.  You aim it at

a folder full of Git repositories and go (make sure it runs as a user account 

that can read them).  Then use the built-in, minimal web UI or roll your own.

Features

--------

The web API supports the following, returning JSON:

 * List repositories

 * List commits information for a repository, limiting the number of entries returned and the starting entry

 * List files for a repository, optionally specifying a branch name

 * Download an individual commit diff, specifying a repository and commit hash

 * Download an individual file, optionally specifying a branch

 * Download an archive of a repository, optionally specifying a branch, in one of

   * ``tar.xz`` format

   * ``tar.bz2`` format

   * ``tar.gz`` format

   * ``zip`` format

The web ui provides a single-page web application for doing the above in a

web browser.

Configuration

-------------

It looks for a file named ``gittattle.json`` in the process` working directory.

The following properties are relevant and shown with their defaults:

 * ``gitdir : /var/lib/gitolite/repositories`` - Path to the parent directory 

of git repos to serve

 * ``port : 9902`` - The port to run the HTTP server on

 * ``tar : tar`` - The name of the tar command, for platforms that call GNU 

tar ``gtar``

 * ``logEntriesPerPage : 30`` - The number of log entries to return if log is 

called with no ``count`` URL parameter

 * ``serveIndexPage : true`` - Should the built-in HTML client be used

 * ``failOnNoDir : true`` - Exit early if the git repositories directory does 

not exist when the program is started

 * ``blacklist : []`` - The list of repository names that must'nt be exposed to the world

 * ``whitelist : []`` - The exhaustive list of repository names that must be exposed to the world

 * ``listfilter: 'blacklist'`` - The filtering strategy (``blacklist`` by default) - 

Only necessary to enforce ``whitelist`` when both arrays are defined

Web UI

------

The application includes a simple web user interface which uses CDN-hosted

JQuery, Twitter Bootstrap and AngularJS to create a single-page web application

which uses the web API to browse Git repositories.

Run it and navigate in a browser to ``/git/index.html`` for that.

Web API

-------

The API aims to be simple and intuitive.  Since this is read-only, only GET and HEAD

requests are supported.

### ``/git/index.html``, ``/git/``

A minimal web ui for a git server which can show lists of commits and files for

a set of repositories which are subdirectories of the folder it was given on

startup.

### ``/git/list``

Lists the respositories being served as a JSON array, with some info about the

most recent commit if available

    [ { location: '/tmp/git/blog.git',

        dir: 'blog.git',

        name: 'blog',

        description: 'Yet another nodejs blog engine\n',

        lastCommit: 

         { hash: '92cb9cb',

           author: 'Joe Shmoe',

           date: '2013-03-24T16:12:23.000Z',

           email: '[email protected]',

           message: 'Fix utf8, more attempts to get working in IE8, filter obvious spam comments',

           commitDate: '2013-03-24 12:12:23 -0400',

           age: '5 months ago' }

    } ]

### ``/git/$REPO_NAME``

Get a commit log for one repository.  Example data:

        [{ hash: '56cbf59',

          author: 'Tim Boudreau',

          date: '2012-11-27T01:20:05.000Z',

          email: '[email protected]',

          message: 'Fix gzip length bug',

          commitDate: '2012-11-26 20:20:05 -0500',

          age: '9 months ago' }]

Optional parameters:

 * skip - integer number of log records to skip

 * count - the maximum number of log records to return

### ``/git/$REPO_NAME/list``

List the files in one repository, as they would be presented by ``tar tv``, JSON-ized.

Example data:

  [{ type: '-rw-rw-r--',

    size: 646,

    date: '2013-03-24T16:12:00.000Z',

    path: 'ui/package.json' }]

Add the parameter ``?branch=$BRANCH_NAME`` to download the version from a particular branch.

Directories are omitted from the file list.

### ``/git/$REPO_NAME.tar.gz``

Download an archive of this repository, specifying the compression type with

the file name.  The following are supported:  .tar, .tar.gz, .tar.bz2, .tar.xz, zip

Add the parameter ``?branch=$BRANCH_NAME`` to download the version from a particular branch.

### ``/git/$REPO_NAME/get/path/to/some.file``

Download the file ``path/to/some.file``.  Add ``?raw=true`` to have the server

attempt to set the content-type to the MIME type suggested by the extension.

Add the parameter ``?branch=$BRANCH_NAME`` to download the version from a particular branch.

### ``/git/$REPO_NAME/$COMMIT_HEX_ID``

Fetch the output of ``git diff-tree --patch-with-stat $COMMIT_HEX_ID`` - a basic

diff and stats output for that repository.

## Security

The web API *does* call ``git`` in a shell with arguments passed from an HTTP

request.  The usual precautions have been taken about not allowing characters

such as backticks, redirects, pipes, etc.  I make no promises that there isn't

some way for someone to do something nasty, but I've taken the basic 

precautions.  If you find any issues, please let me know.

The web api does not do any authentication/authorization.  It's easy enough to

proxy it behind something that does.

# To-Do / Issues

 * Would be nice to use a router and have permalinks

 * Appending ``.git`` should be optional but is actually currently required - probably some tweaks needed

 * ``git show`` on binary files such as images appears to be prepending a few bytes to output, corrupting "raw" links for those