extract-git-treeish

extract-git-treeish
================================

Extracts git tree-ish (commits, branches, or tags) into target directory.

[![Build Status][ci-image]][ci-url]
[![NPM version][npm-image]][npm-url]
[![Code Style][style-image]][style-url]
[![License][license-image]][license-url]
!Supported Node Version

USAGE
---------------------------------------

$3

``js
const { exists } = require('extract-git-treeish');
const assert = require('assert').strict;
assert(await exists({ treeIsh: 'master' }) === true);
assert(await exists({ treeIsh: 'doesnotexist' }) === false);
`

`js
import { exists } from 'extract-git-treeish';
import assert from 'node:assert/strict';
assert(await exists({ treeIsh: 'master' }) === true);
assert(await exists({ treeIsh: 'doesnotexist' }) === false);
`

$3

`js
const { extract } = require('extract-git-treeish');
const assert = require('assert').strict;
const path = require('path');
const destDir = path.join(process.cwd(), 'demo', 'v1');
const extracted = await extract({ treeIsh: 'v1.0.0', dest: destDir })
assert.deepEqual(extracted, {
treeIsh: 'v1.0.0',
dir: '/path/to/cwd/demo/v1'
});
`

`js
import { extract } from 'extract-git-treeish';
import assert from 'node:assert/strict';
import { join } from 'node:path';
const destDir = join(process.cwd(), 'demo', 'v1');
const extracted = await extract({ treeIsh: 'v1.0.0', dest: destDir });
assert.deepEqual(extracted, {
treeIsh: 'v1.0.0',
dir: '/path/to/cwd/demo/v1'
});
`

API
---------------------------------------

$3


- returns Promise which will:
- resolve with true when tree-ish exists
- resolve with false when tree-ish does not exist
- treeIsh(string) is a name of a git tree-ish (commit, branch, or tag) to be inquired
- when treeIsh argument is omitted:
- throw TypeError
- when treeIsh argument is not a string:
- throw TypeError
- gitProjectRoot(string) is an optional directory path pointing to top level directory of git project
- when gitProjectRoot option is omitted:
- and when process.cwd() is inside the git project:
- resolves as usual
- and when process.cwd() is outside the git project:
- returns Promise which will reject with Error
- when specified gitProjectRoot is pointing to git project root:
- resolves as usual
- when specified gitProjectRoot is not a git repository (or any of the parent directories):
- returns Promise which will resolve with false
- when specified gitProjectRoot is pointing to directory that does not exist:
- returns Promise which will reject with Error
- when gitProjectRoot argument is not a string:
- throw TypeError when number
- throw TypeError when boolean

$3

- returns Promise which will:
- resolve with object containing {treeIsh, dir} when succeeded
- extract tree-ish content into dest on resolve
- treeIsh(string) is a name of a git tree-ish (commit, branch, or tag) to be extracted into dest
- when tree-ish specified by treeIsh does not exist:
- reject with Error
- when treeIsh argument is omitted:
- throw TypeError
- when treeIsh argument is not a string:
- throw TypeError
- dest(string) is a directory path which extract going to extract tree-ish content
- when directory specified by dest does not exist:
- creates dest recursively then resolves as usual
- when directory specified by dest already exists:
- resolves as usual when dest directory is empty
- rejects with Error when dest directory is not empty
- rejects with Error when dest directory is not writable or dest is not a directory
- when dest argument is omitted:
- throw TypeError
- when dest argument is not a string:
- throw TypeError
- gitProjectRoot(string) is an optional directory path pointing to top level directory of git project
- when gitProjectRoot option is omitted:
- when process.cwd() is inside the git project:
- resolves as usual
- when process.cwd() is outside the git project:
- returns Promise which will reject with Error
- when specified gitProjectRoot is pointing to git project root and treeIsh exists too:
- resolves as usual when dest is empty
- when specified gitProjectRoot is not a git repository (or any of the parent directories):
- returns Promise which will reject with Error
- when specified gitProjectRoot is pointing to directory that does not exist:
- returns Promise which will reject with Error
- when gitProjectRoot argument is not a string:
- throw TypeError when number
- throw TypeError when boolean

INSTALL
---------------------------------------

`sh
$ npm install extract-git-treeish
``

AUTHOR
---------------------------------------
* Takuto Wada

LICENSE
---------------------------------------
Licensed under the MIT license.

[ci-image]: https://github.com/twada/extract-git-treeish/workflows/Node.js%20CI/badge.svg
[ci-url]: https://github.com/twada/extract-git-treeish/actions?query=workflow%3A%22Node.js+CI%22

[npm-url]: https://npmjs.org/package/extract-git-treeish
[npm-image]: https://badge.fury.io/js/extract-git-treeish.svg

[style-url]: https://github.com/neostandard/neostandard
[style-image]: https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat

[license-url]: https://twada.mit-license.org
[license-image]: https://img.shields.io/badge/license-MIT-brightgreen.svg