Grit v0.1 documentation

Grit is a simple and light-weight git repository manager or git-compatible digital asset management system with limited remote object proxying, a http back-end and easy to use command line, python and web user interfaces.


This is early prototype code, is missing many important features and probably won’t work for you


  • Python WSGI “Smart HTTP” server
  • Limited remote object proxying
  • Stream blob data from remote repositories
  • Hierarchical repos with top-down inheritance
  • Check out individual blobs
  • Python and HTTP+JSON read/write API
  • Supports a centralized workflow
  • Command line, Python and web UIs
  • Git not required

Some noted differences from git

  • A branch in grit is different from a branch in git in that a branch is a child of a repo and inherits its files automatically. Files can be overwritten at the branch level.
  • Grit supports (limited) remote object proxying, so you can browse and get information about an object without checking it out.
  • Checkouts in grit are different in that you can check out a given version (latest by default) of a repo, or a single file.

Known issues as of this release

  • Currently no support for diff, status, submodule or tag
  • Renaming a repo breaks external references
  • Items tab shows flat list of items, not heirarchical
  • Checking in files over HTTP is broken (use git instead)
  • Poor performance with large binary files
  • Can only checkout repos and blobs, not trees
  • Blobs lack icons in the web UI
  • Parent links in web UI are broken

Get Grit

Installing Grit is easily done using setuptools. Assuming it is installed, just run the following from the command-line:

$ easy_install grit
  • setuptools
  • install setuptools <>

Alternatively, you can install from the distribution using the script:

$ git clone
$ python install


Python and the following Python packages are required for Grit to work. Currently, git is required for checking in files and some operations like clone.

  • Python (2.6.5)
  • Dulwich (0.7.0)
  • Git (optional)


This is a simple tutorial using the command line interface for grit. The Python API is documented below. Note that grit is git-compatible, so you can also use git for many operations albiet with different syntax.

Create a new repo

The new command creates the equivalent of a bare git repository. This “projects” repo will act as a starting point for creating branches later.

$ grit new /tmp/projects

Serving repos

Start the grit server on localhost port 80 and serve the “projects” repository.

$ grit serve /tmp/projects -p 80

Creating branches

Let’s branch some repositories off of the main “projects” repository. You can use either URLs or local paths here.

$ grit new http://localhost/animal
$ grit new http://localhost/animal/mammal
$ grit new http://localhost/animal/mammal/wolf

To override any files inherited from a branch parent, simply check in a file to the branch with the same name. To get thumbnails in the web UI, check in an appropriate png file called “thumb.png”.

Adding files

Using grit, checkin a file to a remote repo

$ grit ci http://locahost/animal/mammal/wolf thumb.png

... or to a local repo

$ grit ci /tmp/projects/animal/mammal/wolf thumb.png

Using Python

>>> from grit import Repo
>>> r = Repo('/tmp/projects/animal/mammal/wolf')
>>> r.addFile('/path/to/thumb.png', 'Publishing thumbnail')

Adding multiple items to the same version

>>> from grit import Repo, Item
>>> v = r.addVersion()
>>> v.addFile(path='/path/to/fileA')
>>> v.addFile(path='/path/to/fileB')
>>>'Publishing files')

Using git

$ git clone http://localhost/animal/mammal/wolf
$ cd wolf
$ git add thumb.png
$ git commit thumb.png "adding thumb"
$ git push

Checking out repos

You can use grit to checkout the latest version of a repo (with revision depth=0), including all of the automatically inherited files from its branch parents.

$ grit co http://localhost/animal/mammal/wolf

Checking out files

Also with grit, you can check out a single file if you wish.

$ grit co http://localhost/animal/mammal/wolf/thumb.png

API Reference

The following API docs cover the major classes.


class grit.Repo(url)

Creates a new Repo instance. Most method and attribute calls are passed to the underlying repo object, which is either an instance of repo.Local or repo.Proxy, which is a proxy representation of a Local object served by the wsgi server.

Parameters:url – HTTP URL or file path.
Returns:New repo.Repo instance.

For example:

>>> r = Repo('http://localhost/projects/myrepo')


>>> r = Repo('/tmp/myrepo')

Either way, you can make the same method and attribute calls:

>>> r.setDescription(desc='my project repository')
>>> r.versions()
>>> r.items()
>>> f = r.items(path='relative/path/to/file')
classmethod new(url, clone_from=None, bare=True)

Creates a new Repo instance.

  • url – Path or remote URL of new repo.
  • clone_from – Path or URL of repo to clone from.
  • bare – Create as bare repo.

grit.Repo instance.

For example:

>>> r ='/tmp/projects')
>>> r
<grit.Repo "/tmp/projects">
clone(path=None, bare=False)

Clone the repository to path (requires git).

  • path – Destination filesystem path.
  • bare – Make this a bare repo.

grit.Repo instance.

For example:

>>> r = Repo("http://localhost/projects/a/b/c")
>>> c = r.clone('/tmp')
>>> c
<grit.Repo "/tmp/c">


class grit.Local(path=None)

Local repository class.

addFile(path, msg=None)

add a new file(s)

addItem(item, message=None)

add a new Item class object


Creates a new Version, to which Items can be added and removed, and committed.

Returns:New Version instance.
branch(name, desc=None)

Create a branch of this repo at ‘name’.

  • name – Name of new branch
  • desc – Repo description.

New Local instance.

Returns:datetime object
Returns:repository description

git command object

items(path=None, version=None)

Returns a list of items.

  • path – Regex filter on item path.
  • version – Repo versions number/index.

List of Item class objects.

classmethod new(path, desc=None, bare=True)

Create a new bare repo.Local instance.

  • path – Path to new repo.
  • desc – Repo description.
  • bare – Create as bare repo.

New repo.Local instance.

Returns:Remote origin as Proxy instance
setDescription(desc='No description')

sets repository description


Checkout a version of the repo.

Parameters:version – Version number.

List of Versions of this repository.

  • version – Version index.
  • rev – Commit sha or ref.

List of Version objects matching params.


class grit.Proxy(url)

Remote object proxy class.

request(cmd, *args, **kwargs)

Request data fromo the server.

Parameters:cmd – repo handler command.


class grit.Item(parent, sha, path, mode=33188)

read blob on access only because get_object is slow


Check out file data to path.

Parameters:path – Filesystem path to check out item to.
Returns:True if successful.
Returns:blob data
Returns:File-like StringIO object
classmethod from_path(repo, path, name=None)

Create a new Item from a file path.

  • repo – Repo object.
  • path – File path.
  • name – Name of item (to override original file name).

New Item class instance.

classmethod from_string(repo, name, string)

Create a new Item from a data stream.

  • repo – Repo object.
  • name – Name of item.
  • data – Data stream.

New Item class instance.


Modify item data and commit to repo. Git objects are immutable, to save means adding a new item

Parameters:msg – Commit message.
versions(rev=None, index=None)
Returns:List of Versions for this Item


class grit.Version(repo, commit, tree=None)
classmethod new(repo)

Create a new version of a repo.Local object.

Parameters:repo – Instance of repo.Local.
Returns:New Version instance.

Add version to repo object store, set repo head to version sha.

Parameters:message – Message string.
Returns:Version number / index in list of versions


class grit.Server(base_dir='.', port=8080, uri_marker='')

Assembles basic WSGI-compatible application providing functionality of git-http-backend.

Indices and tables