:guitar: Download and/or Extract git repositories (GitHub, GitLab, BitBucket). Cross-platform and Offline-first!

Usage no npm install needed!

<script type="module">
  import gittar from '';


gittar TravisCI Status AppVeyor Status

:guitar: Download and/or Extract git repositories (GitHub, GitLab, BitBucket). Cross-platform and Offline-first!

Gittar is a Promise-based API that downloads *.tar.gz files from GitHub, GitLab, and BitBucket.

All archives are saved to the $HOME/.gittar directory with the following structure:

#=> github/lukeed/mri/v1.1.0.tar.gz
#=> gitlab/Rich-Harris/buble/v0.15.2.tar.gz
#=> github/vuejs-templates/pwa/master.tar.gz

By default, new gittar.fetch requests will check the local filesystem for a matching tarball before intiating a new remote download!

Important: Please see gittar.fetch for exceptions & behaviors!


$ npm install --save gittar


const gittar = require('gittar');

//=> ~/.gittar/github/lukeed/gittar/master.tar.gz

//=> ~/.gittar/github/lukeed/tinydate/v1.0.0.tar.gz

//=> ~/.gittar/github/lukeed/mri/master.tar.gz

//=> ~/.gittar/gitlab/Rich-Harris/buble/v0.15.2.tar.gz

gittar.fetch('Rich-Harris/buble', { host:'gitlab' }).then(console.log);
//=> ~/.gittar/gitlab/Rich-Harris/buble/master.tar.gz

const src = '...local file or repo pattern...';
const dest = '/path/to/foobar';

gittar.extract(src, dest, {
  filter(path, entry) {
    if (path.includes('package.json')) {
      let pkg = '';
      entry.on('data', x => pkg += x).on('end', _ => {
        const devDeps = JSON.parse(pkg).devDependencies || {};
        console.log('~> new devDependencies:', Object.keys(devDeps));

    if (path.includes('.babelrc')) {
      return false; // ignore this file!

    return true; // keep all other files


gittar.fetch(repo, options)

Type: Promise
Returns: String


Parses the repo name, then looks for matching tarball on filesystem. Otherwise, a HTTPS request is dispatched and then, if successful, the archive is saved to ~/.gittar at the appropriate path.


  • If Gittar detects that your machine is not connected to the internet, or if useCache is true, then it will only attempt a local fetch.
  • If repo is (or is assumed to be) a master branch, or if force is true, then the archive will be downloaded over HTTPS before checking local cache.


Type: String

The name, link, or pattern for a git repository.

Optionally provide a tag or branch name, otherwise master is assumed.

//=> ~/.gittar/github/user/repo/master.tar.gz

//=> ~/.gittar/github/user/repo/v1.0.0.tar.gz

//=> ~/.gittar/github/user/repo/production.tar.gz

//=> ~/.gittar/bitbucket/user/repo/master.tar.gz

//=> ~/.gittar/gitlab/user/repo/master.tar.gz

Note: The parse function does not exist -- it's only demonstrating the parsed values of the varying patterns.

Type: String
Default: github

The hostname for the repository.

Specifying a "hint" in the repo will take precedence over this value.

fetch('gitlab:user/repo', { host:'bitbucket' });
//=> ~/.gittar/gitlab/user/repo/master.tar.gz


Type: Boolean
Default: false

Force a HTTPS download. If there is an error with the network request, a local/cache lookup will follow.

Note: A network request is also forced if the repo is (or is assumed to be) a master branch!


Type: Boolean
Default: false

Only attempt to use an existing, cached file. No network requests will be dispatched.

Note: Gittar enacts this option if it detects that there is no internet connectivity.

gittar.extract(file, target, options)


Type: String

A filepath to extract. Also accepts a repo pattern!

Important: A repo pattern will be parsed (internally) as a filepath. No network requests will be dispatched.


Type: String
Default: process.cwd()

The target directory to place the archive's contents.

Note: Value will be resolved (see path.resolve) if not already an absolute path.


Type: Object
Default: { strip:1 }

All options are passed directly to tar.extract.

Note: The cwd and file options are set for you and cannot be changed!


Type: Integer
Default: 1

By default, gittar will strip the name of tarball from the extracted filepath.

const file = 'lukeed/mri#master';

// strip:1 (default)
gittar.extract(file, 'foo');
//=> contents: foo/**

// strip:0 (retain tarball name)
gittar.extract(file, 'foo', { strip:0 });
//=> contents: foo/mri-master/**


MIT © Luke Edwards