diff options
Diffstat (limited to 'node_modules/@npmcli/git/README.md')
-rw-r--r-- | node_modules/@npmcli/git/README.md | 157 |
1 files changed, 0 insertions, 157 deletions
diff --git a/node_modules/@npmcli/git/README.md b/node_modules/@npmcli/git/README.md deleted file mode 100644 index ca8afcbce..000000000 --- a/node_modules/@npmcli/git/README.md +++ /dev/null @@ -1,157 +0,0 @@ -# @npmcli/git - -A utility for spawning git from npm CLI contexts. - -This is _not_ an implementation of git itself, it's just a thing that -spawns child processes to tell the system git CLI implementation to do -stuff. - -## USAGE - -```js -const git = require('@npmcli/git') -git.clone('git://foo/bar.git', 'some-branch', 'some-path', opts) // clone a repo - .then(() => git.spawn(['checkout', 'some-branch'], {cwd: 'bar'})) - .then(() => git.spawn(['you get the idea'])) -``` - -## API - -Most methods take an options object. Options are described below. - -### `git.spawn(args, opts = {})` - -Launch a `git` subprocess with the arguments specified. - -All the other functions call this one at some point. - -Processes are launched using -[`@npmcli/promise-spawn`](http://npm.im/@npmcli/promise-spawn), with the -`stdioString: true` option enabled by default, since git output is -generally in readable string format. - -Return value is a `Promise` that resolves to a result object with `{cmd, -args, code, signal, stdout, stderr}` members, or rejects with an error with -the same fields, passed back from -[`@npmcli/promise-spawn`](http://npm.im/@npmcli/promise-spawn). - -### `git.clone(repo, ref = 'HEAD', target = null, opts = {})` -> `Promise<sha String>` - -Clone the repository into `target` path (or the default path for the name -of the repository), checking out `ref`. - -Return value is the sha of the current HEAD in the locally cloned -repository. - -In lieu of a specific `ref`, you may also pass in a `spec` option, which is -a [`npm-package-arg`](http://npm.im/npm-package-arg) object for a `git` -package dependency reference. In this way, you can select SemVer tags -within a range, or any git committish value. For example: - -```js -const npa = require('npm-package-arg') -git.clone('git@github.com:npm/git.git', '', null, { - spec: npa('github:npm/git#semver:1.x'), -}) - -// only gitRange and gitCommittish are relevant, so this works, too -git.clone('git@github.com:npm/git.git', null, null, { - spec: { gitRange: '1.x' } -}) -``` - -This will automatically do a shallow `--depth=1` clone on any hosts that -are known to support it. To force a shallow or deep clone, you can set the -`gitShallow` option to `true` or `false` respectively. - -### `git.revs(repo, opts = {})` -> `Promise<rev doc Object>` - -Fetch a representation of all of the named references in a given -repository. The resulting doc is intentionally somewhat -[packument](https://www.npmjs.com/package/pacote#packuments)-like, so that -git semver ranges can be applied using the same -[`npm-pick-manifest`](http://npm.im/npm-pick-manifest) logic. - -The resulting object looks like: - -```js -revs = { - versions: { - // all semver-looking tags go in here... - // version: { sha, ref, rawRef, type } - '1.0.0': { - sha: '1bc5fba3353f8e1b56493b266bc459276ab23139', - ref: 'v1.0.0', - rawRef: 'refs/tags/v1.0.0', - type: 'tag', - }, - }, - 'dist-tags': { - HEAD: '1.0.0', - latest: '1.0.0', - }, - refs: { - // all the advertised refs that can be cloned down remotely - HEAD: { sha, ref, rawRef, type: 'head' }, - master: { ... }, - 'v1.0.0': { ... }, - 'refs/tags/v1.0.0': { ... }, - }, - shas: { - // all named shas referenced above - // sha: [list, of, refs] - '6b2501f9183a1753027a9bf89a184b7d3d4602c7': [ - 'HEAD', - 'master', - 'refs/heads/master', - ], - '1bc5fba3353f8e1b56493b266bc459276ab23139': [ 'v1.0.0', 'refs/tags/v1.0.0' ], - }, -} -``` - -### `git.is(opts)` -> `Promise<Boolean>` - -Resolve to `true` if the path argument refers to the root of a git -repository. - -It does this by looking for a file in `${path}/.git/index`, which is not an -airtight indicator, but at least avoids being fooled by an empty directory -or a file named `.git`. - -### `git.find(opts)` -> `Promise<String | null>` - -Given a path, walk up the file system tree until a git repo working -directory is found. Since this calls `stat` a bunch of times, it's -probably best to only call it if you're reasonably sure you're likely to be -in a git project somewhere. - -Resolves to `null` if not in a git project. - -### `git.isClean(opts = {})` -> `Promise<Boolean>` - -Return true if in a git dir, and that git dir is free of changes. This -will resolve `true` if the git working dir is clean, or `false` if not, and -reject if the path is not within a git directory or some other error -occurs. - -## OPTIONS - -- `retry` An object to configure retry behavior for transient network - errors with exponential backoff. - - `retries`: Defaults to `opts.fetchRetries` or 2 - - `factor`: Defaults to `opts.fetchRetryFactor` or 10 - - `maxTimeout`: Defaults to `opts.fetchRetryMaxtimeout` or 60000 - - `minTimeout`: Defaults to `opts.fetchRetryMintimeout` or 1000 -- `git` Path to the `git` binary to use. Will look up the first `git` in - the `PATH` if not specified. -- `spec` The [`npm-package-arg`](http://npm.im/npm-package-arg) specifier - object for the thing being fetched (if relevant). -- `fakePlatform` set to a fake value of `process.platform` to use. (Just - for testing `win32` behavior on Unix, and vice versa.) -- `cwd` The current working dir for the git command. Particularly for - `find` and `is` and `isClean`, it's good to know that this defaults to - `process.cwd()`, as one might expect. -- Any other options that can be passed to - [`@npmcli/promise-spawn`](http://npm.im/@npmcli/promise-spawn), or - `child_process.spawn()`. |