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

INSTALL

$ npm install extract-git-treeish

AUTHOR

• Takuto Wada

LICENSE

Licensed under the MIT license.