girror

girror - Efficient mirroring of git remotes

girror maintains mirrors of git repositories on the local system using a bare repository cache. This makes it especially useful to handle post-commit triggers and automatically pull changes from a remote.

$ sudo npm install -g girror
$ girror [e-mail]/eladb/node-girror /tmp/node-girror-master
$ girror [e-mail]/eladb/node-girror#branch1 /tmp/node-girror-branch1

Now, every time the remote changes, calling girror again will update the worktree.

girror uses a bare repository with a --mirror=fetch origin to maintain a cached mirror of the remote.

It essentially performs the following steps:

1. Initializes a bare repo under /tmp/girror-cache (or $TEMP/girror-cache in Windows) based on the origin URL.
2. Sets up a remote with --mirror=fetch.
3. git fetch origin
4. export GIT_WORK_TREE=<worktree> && git checkout -f <branch>

girror can be used as a command line tool or as a node.js in-process module.

Command line

$ girror --help

  Usage: girror [options] remote-url[#branch] work-tree

  Options:

    -h, --help             output usage information
    -v, --verbose          verbose output

If #branch is not provided in the URL, #master is the default.

API

girror(remote, worktree, options, callback)

• remote - the URL of the git remote (postfix with '#branch' to checkout a specific branch)
• worktree - path to local working directory (where you want files to be checked out into)
• options.cachedir - where to store the bare repo cache that makes girror so awesome (default is $GIRROR_CACHE || ($TMP || $TEMP || /tmp)/girror-cache)
• options.logger - optional alternative to console.
• options.remote_type - A mapper for the remote URL (function(remote_url) => remote_url). You can either provide your own function, or use one of the built in ones:
  • girror.remote_types.no_auth() - passthru (the default)
  • girror.remote_types.auth(user, password) - add user:password@ to URL.
  • girror.remote_types.github_ssh() - convert a github (e.g. https://github.com/account/repo) URL to an SSH URL (e.g. [e-mail]/account/repo.git)

girror.git(args, options, callback)

Invokes git. Returns a ChildProcess object that can be used to grab stdio or whatever.

• args array of arguments to pass to git.
• options.env environment hash (default is process.env)
• options.logger optional logger (default is console)
• options.tolerate never fail (default false)
• options.verbose verbose output (default true)
• callback is function(err)

Using girror for continuous deployment

girror was built to enable automatic deployment from source control:

1. Set up a post-commit HTTP trigger on your favorite source control that will POST into some endpoint on your servers.
2. Invoke girror to sync from the remote repository into the local filesystem. girror will do it as efficiently and painlessly as possible (no merges, no cleanups, only clean diffs).
3. You can also use it to sync multiple branches into your production servers and use them as staging environments (yeah!).

I will create a "girror-middleware" for express so you can just plug it in and have all this automated.

Credits

• @mojodna

License

MIT