targit

A library for figuring out the download links for hosted Git services (Bitbucket, GitHub, GitLab).

Installation

npm install --save targit

Usage overview

The simplest usage for this module is to call downloadAndExtract. It will handle everything for your, from parsing the URI, downloading the archive, and then extracting it to the requested location.

const { downloadAndExtract } = require('targit');
 
await downloadAndExtract('ewanharris/targit', '/a/location')
 
// or configure targit by passing a third option see TarGitOptions for full options
 
await downloadAndExtract('ewanharris/targit', '/a/location', {
    defaultHost: 'gitlab' // download from gitlab
})

If you want to do some custom behaviour the different pieces of that function are available as the following exports:

• parseURI
  • A re-export of targit-parser)
• download
  • The download logic
• extract
  • The extraction logic

Full API details below.

• defaultCache
• TarGitOptions
  • Properties
• download
  • Parameters
• extract
  • Parameters
• downloadAndExtract
  • Parameters

defaultCache

The default cache location for targit.

Type: string

TarGitOptions

Options that can be used to configure targit.

Type: Object

Properties

• archiveType string? Archive format to download, zip or tar.gz.
• cacheDir string? Top level directory to cache downloads in.
• defaultHost string? Default host to be used when parsing the uri, bitbucket, github, or gitlab.
• force Boolean? If true, always ignore local cache and download from hosting service.
• onData Function? Function to invoke when data is recieved during download, useful for showing progress bars. Called with the chunk and content-length header.

download

Parameters

• uri string The uri for the git repo.
• options TarGitOptions? Various options to configure targit. (optional, default {})
  • options.archiveType (optional, default 'tar.gz')
  • options.cacheDir (optional, default defaultCache)
  • options.defaultHost (optional, default 'github')
  • options.force (optional, default false)
  • options.onData

extract

Parameters

• from string Item to extract.
• to string Location to extract to.

downloadAndExtract

Parameters

• uri string URI of the git repo to download.
• to string Location to extract the git repo to.
• options TarGitOptions? Various options to configure targit. (optional, default see TarGitOptions for defaults)

Returns string Location that the repo was extracted to.

Exceptions

The following exceptions are thrown by targit (and are instances of TarGitError)

• E_ARCHIVE_NO_EXIST - Provided archive location to extract does not exist
• E_EXTRACT_DIR_NOT_EMPTY - Directory to extract to has contents.
• E_NO_REF - Could not find the commit sha for the provided URI.
• E_PARSE_FAIL - Failed to parse the provided URI.
• E_REPO_LOOKUP_FAILED - Failed to lookup the repository represented by the provided URI.
• E_UNSUPPORTED_ARCHIVE_TYPE - Unsupported archive type was provided.
• E_UNSUPPORTED_HOST - Unsupported host was provided.

Acknowledgements

This library is built thanks to the following projects:

• degit by Rich Harris
• gittar by Luke Edwards