twada / extract-git-treeish

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

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

extract-git-treeish

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

Build Status NPM version Code Style License

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

LICENSE

Licensed under the MIT license.

About

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


Languages

Language:JavaScript 79.7%Language:TypeScript 20.3%