Extract-git-treeish NPM

extract-git-treeish

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

USAGE

`exists`

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

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

`extract`

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'
});

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

`exists({ treeIsh, [gitProjectRoot], [spawnOptions] })`: Inquires for existence of `treeIsh`

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

`extract({ treeIsh, dest, [gitProjectRoot], [spawnOptions] })`: Extracts contents of `treeIsh` into `dest` directory

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