# gitly

> An API to download and/or extract git repositories

Latest version **3.2.4** (published 2026-04-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install gitly
pnpm add gitly
yarn add gitly
bun add gitly
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.2.4 |
| Published | 2026-04-17 |
| First published | 2019-11-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.x |
| Dependencies | 4 |
| Unpacked size | 85.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 28 |
| Author | Takeshi Iwana |
| Maintainers | iwatakeshi |
| Keywords | archive, bitbucket, download, extract, fetch, git, github, gitlab, offline-first, offline, project, repo, repository, scaffold, tarbarll, zip |

## Links

- npm: https://www.npmjs.com/package/gitly
- Repository: https://github.com/iwatakeshi/gitly
- Homepage: https://github.com/iwatakeshi/gitly#readme
- Issues: https://github.com/iwatakeshi/gitly/issues
- npm.io page: https://npm.io/package/gitly

## Dependencies (4)

- [tar](https://npm.io/package/tar.md) ^7.5.13
- [axios](https://npm.io/package/axios.md) ^1.15.0
- [shelljs](https://npm.io/package/shelljs.md) ^0.10.0
- [cross-spawn](https://npm.io/package/cross-spawn.md) ^7.0.6

## Alternatives

- [lodash.startswith](https://npm.io/package/lodash.startswith.md) — 769.7K weekly downloads
- [@tarojs/service](https://npm.io/package/@tarojs/service.md) — 33.9K weekly downloads
- [io.extendreality.tilia.indicators.spatialtargets.unity](https://npm.io/package/io.extendreality.tilia.indicators.spatialtargets.unity.md) — 131 weekly downloads
- [@rtarojs/taro](https://npm.io/package/@rtarojs/taro.md) — 90 weekly downloads
- [node-branch-io](https://npm.io/package/node-branch-io.md) — 50 weekly downloads

## Recent versions

- 3.2.4 (latest) — 2026-04-17
- 1.1.0-0 (next) — 2019-11-17
- 3.2.3 — 2026-03-02
- 3.2.2 — 2026-01-17
- 3.2.1 — 2025-11-30
- 3.2.0 — 2025-11-18
- 3.1.1 — 2025-09-26
- 3.1.0 — 2025-03-12
- 3.0.3 — 2025-01-01
- 3.0.2 — 2024-09-23
- 3.0.1 — 2024-07-31
- 3.0.0 — 2024-05-12
- 2.5.3 — 2024-04-10
- 2.5.2 — 2024-02-18
- 2.5.1 — 2024-02-18
- … 42 more at https://npm.io/package/gitly/versions

## README

# gitly

An API to download and/or extract git repositories.

[![Node CI](https://github.com/iwatakeshi/gitly/workflows/Node%20CI/badge.svg)](https://github.com/iwatakeshi/gitly/actions?query=workflow%3A%22Node+CI%22)
[![Version](https://img.shields.io/npm/v/gitly.svg)](https://www.npmjs.com/package/gitly)
[![codecov](https://codecov.io/gh/iwatakeshi/gitly/branch/master/graph/badge.svg)](https://codecov.io/gh/iwatakeshi/gitly)
[![Downloads/week](https://img.shields.io/npm/dw/gitly.svg)](https://www.npmjs.com/package/gitly)
[![License](https://img.shields.io/github/license/iwatakeshi/gitly)](https://github.com/iwatakeshi/gitly/blob/master/LICENSE.md)

This project is the spiritual successor of [gittar](https://github.com/lukeed/gittar) written in TypeScript.

## Usage

Since v1.0+

```typescript
import { download, extract } from 'gitly'

console.log(await download('iwatakeshi/gitly'))
// -> ~/.gitly/github/iwatakeshi/gitly/master.tar.gz

console.log(await download('iwatakeshi/gitly#v1.0.0'))
// -> ~/.gitly/github/iwatakeshi/gitly/v1.0.0.tar.gz

console.log(await download('https://github.com/iwatakeshi/gitly'))
// -> ~/.gitly/github/iwatakeshi/gitly/master.tar.gz

console.log(await download('gitlab:Rich-Harris/buble#v0.15.2'))
// -> ~/.gitly/gitlab/Rich-Harris/buble/v0.15.2.tar.gz

console.log(await download('Rich-Harris/buble', { host: 'gitlab' }))
// -> ~/.gitly/gitlab/Rich-Harris/buble/master.tar.gz

const source = 'path to downloaded zip file (can be obtained by download())'
const destination = '/path/to/foobar'

await extract(source, destination)
// -> /path/to/foobar
```

Since v2.0+

```typescript
import gitly from 'gitly'

console.log(await gitly('iwatakeshi/gitly', '/path/to/extracted/folder/'))
// -> ['~/.gitly/github/iwatakeshi/gitly/master.tar.gz', '/path/to/extracted/folder/']
```

## Options

````typescript
interface GitlyOptions {
  /**
   * Use cache only (default: undefined)
   */
  cache?: boolean
  /**
   * Use both cache and local (default: undefined)
   */
  force?: boolean
  /**
   * Throw an error when downloading (default: undefined)
   */
  throw?: boolean
  /**
   * Set cache directory (default: '~/.gitly')
   */
  temp?: string
  /**
   * Set the host name (default: undefined)
   */
  host?: string
  url?: {
    /**
     * Extend the url filtering method
     * @param info The URLInfo object
     */
    filter?(info: URLInfo): string
  }
  extract?: {
    /**
     * Extend the extract filtering method for the 'tar' library
     */
    filter?(path: string, stat: FileStat): boolean
  }
  /**
   * Set the request headers (default: undefined)
   */
  headers?: RawAxiosRequestHeaders | AxiosHeaders
  /**
   * Sets the hostname, port, and protocol of the proxy server (default: undefined)
   * Falls back to the https_proxy or http_proxy environment variables if not specified
   */
  proxy?: AxiosProxyConfig
  /**
   * Set the backend (default: undefined)
   *
   * @example
   * ```markdown
   * 'axios' - default behavior
   * 'git' - use local git installation to clone the repository (allows for cloning private
   * repositories as long as the local git installation has access)
   * ```
   */
  backend?: 'axios' | 'git'
  /**
   * Set the git options (default: undefined)
   */
  git?: {
    /**
     * Set the depth of the clone (default: 1)
     */
    depth?: number
  }
}
````

## Interfaces

```typescript
interface URLInfo {
  protocol: string
  host: string
  hostname: string
  hash: string
  href: string
  path: string
  repository: string
  owner: string
  type: string
}
```

---
_Source: https://npm.io/package/gitly · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._