npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ri7nz/gittar

v0.1.1-patch.3

Published

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

Downloads

5

Readme

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:

{HOSTNAME}/{USER}/{REPO}/{BRANCH-TAG}.tar.gz
#=> 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!

Install

$ npm install --save gittar

Usage

const gittar = require('gittar');

gittar.fetch('lukeed/gittar').then(console.log);
//=> ~/.gittar/github/lukeed/gittar/master.tar.gz

gittar.fetch('lukeed/tinydate#v1.0.0').then(console.log);
//=> ~/.gittar/github/lukeed/tinydate/v1.0.0.tar.gz

gittar.fetch('https://github.com/lukeed/mri').then(console.log);
//=> ~/.gittar/github/lukeed/mri/master.tar.gz

gittar.fetch('gitlab:Rich-Harris/buble#v0.15.2').then(console.log);
//=> ~/.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
  }
});

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.

parse('user/repo');
//=> ~/.gittar/github/user/repo/master.tar.gz
//=> https://github.com/user/repo/archive/master.tar.gz

parse('user/repo#v1.0.0');
//=> ~/.gittar/github/user/repo/v1.0.0.tar.gz
//=> https://github.com/user/repo/archive/v1.0.0.tar.gz

parse('user/repo#production');
//=> ~/.gittar/github/user/repo/production.tar.gz
//=> https://github.com/user/repo/archive/production.tar.gz

parse('bitbucket:user/repo');
//=> ~/.gittar/bitbucket/user/repo/master.tar.gz
//=> https://bitbucket.org/user/repo/get/master.tar.gz

parse('https://gitlab.com/user/repo');
//=> ~/.gittar/gitlab/user/repo/master.tar.gz
//=> 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.

fetch('gitlab:user/repo', { host:'bitbucket' });
//=> ~/.gittar/gitlab/user/repo/master.tar.gz
//=> 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.

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/**

License

MIT © Luke Edwards