gittar

: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:

1{HOSTNAME}/{USER}/{REPO}/{BRANCH-TAG}.tar.gz
2#=> github/lukeed/mri/v1.1.0.tar.gz
3#=> gitlab/Rich-Harris/buble/v0.15.2.tar.gz
4#=> 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!

Install

$ npm install --save gittar

Usage

1const gittar = require('gittar');
2
3gittar.fetch('lukeed/gittar').then(console.log);
4//=> ~/.gittar/github/lukeed/gittar/master.tar.gz
5
6gittar.fetch('lukeed/tinydate#v1.0.0').then(console.log);
7//=> ~/.gittar/github/lukeed/tinydate/v1.0.0.tar.gz
8
9gittar.fetch('https://github.com/lukeed/mri').then(console.log);
10//=> ~/.gittar/github/lukeed/mri/master.tar.gz
11
12gittar.fetch('gitlab:Rich-Harris/buble#v0.15.2').then(console.log);
13//=> ~/.gittar/gitlab/Rich-Harris/buble/v0.15.2.tar.gz
14
15gittar.fetch('Rich-Harris/buble', { host:'gitlab' }).then(console.log);
16//=> ~/.gittar/gitlab/Rich-Harris/buble/master.tar.gz
17
18const src = '...local file or repo pattern...';
19const dest = '/path/to/foobar';
20
21gittar.extract(src, dest, {
22  filter(path, entry) {
23    if (path.includes('package.json')) {
24      let pkg = '';
25      entry.on('data', x => pkg += x).on('end', _ => {
26        const devDeps = JSON.parse(pkg).devDependencies || {};
27        console.log('~> new devDependencies:', Object.keys(devDeps));
28      });
29    }
30
31    if (path.includes('.babelrc')) {
32      return false; // ignore this file!
33    }
34
35    return true; // keep all other files
36  }
37});

API

gittar.fetch(repo, options)

Type: Promise
Returns: String

Behavior

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.

Exceptions

• 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.

repo

Type: String

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

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

1parse('user/repo');
2//=> ~/.gittar/github/user/repo/master.tar.gz
3//=> https://github.com/user/repo/archive/master.tar.gz
4
5parse('user/repo#v1.0.0');
6//=> ~/.gittar/github/user/repo/v1.0.0.tar.gz
7//=> https://github.com/user/repo/archive/v1.0.0.tar.gz
8
9parse('user/repo#production');
10//=> ~/.gittar/github/user/repo/production.tar.gz
11//=> https://github.com/user/repo/archive/production.tar.gz
12
13parse('bitbucket:user/repo');
14//=> ~/.gittar/bitbucket/user/repo/master.tar.gz
15//=> https://bitbucket.org/user/repo/get/master.tar.gz
16
17parse('https://gitlab.com/user/repo');
18//=> ~/.gittar/gitlab/user/repo/master.tar.gz
19//=> https://gitlab.com/user/repo/repository/archive.tar.gz?ref=master

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

options.host

Type: String
Default: github

The hostname for the repository.

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

1fetch('gitlab:user/repo', { host:'bitbucket' });
2//=> ~/.gittar/gitlab/user/repo/master.tar.gz
3//=> https://gitlab.com/user/repo/repository/archive.tar.gz?ref=master

options.force

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!

options.useCache

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)

file

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.

target

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.

options

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!

options.strip

Type: Integer
Default: 1

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

1const file = 'lukeed/mri#master';
2
3// strip:1 (default)
4gittar.extract(file, 'foo');
5//=> contents: foo/**
6
7// strip:0 (retain tarball name)
8gittar.extract(file, 'foo', { strip:0 });
9//=> contents: foo/mri-master/**

License

MIT © Luke Edwards