source: trip-planner-front/node_modules/@npmcli/git/README.md@ bdd6491

Last change on this file since bdd6491 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 5.3 KB
Line 
1# @npmcli/git
2
3A utility for spawning git from npm CLI contexts.
4
5This is _not_ an implementation of git itself, it's just a thing that
6spawns child processes to tell the system git CLI implementation to do
7stuff.
8
9## USAGE
10
11```js
12const git = require('@npmcli/git')
13git.clone('git://foo/bar.git', 'some-branch', 'some-path', opts) // clone a repo
14 .then(() => git.spawn(['checkout', 'some-branch'], {cwd: 'bar'}))
15 .then(() => git.spawn(['you get the idea']))
16```
17
18## API
19
20Most methods take an options object. Options are described below.
21
22### `git.spawn(args, opts = {})`
23
24Launch a `git` subprocess with the arguments specified.
25
26All the other functions call this one at some point.
27
28Processes are launched using
29[`@npmcli/promise-spawn`](http://npm.im/@npmcli/promise-spawn), with the
30`stdioString: true` option enabled by default, since git output is
31generally in readable string format.
32
33Return value is a `Promise` that resolves to a result object with `{cmd,
34args, code, signal, stdout, stderr}` members, or rejects with an error with
35the same fields, passed back from
36[`@npmcli/promise-spawn`](http://npm.im/@npmcli/promise-spawn).
37
38### `git.clone(repo, ref = 'HEAD', target = null, opts = {})` -> `Promise<sha String>`
39
40Clone the repository into `target` path (or the default path for the name
41of the repository), checking out `ref`.
42
43Return value is the sha of the current HEAD in the locally cloned
44repository.
45
46In lieu of a specific `ref`, you may also pass in a `spec` option, which is
47a [`npm-package-arg`](http://npm.im/npm-package-arg) object for a `git`
48package dependency reference. In this way, you can select SemVer tags
49within a range, or any git committish value. For example:
50
51```js
52const npa = require('npm-package-arg')
53git.clone('git@github.com:npm/git.git', '', null, {
54 spec: npa('github:npm/git#semver:1.x'),
55})
56
57// only gitRange and gitCommittish are relevant, so this works, too
58git.clone('git@github.com:npm/git.git', null, null, {
59 spec: { gitRange: '1.x' }
60})
61```
62
63This will automatically do a shallow `--depth=1` clone on any hosts that
64are known to support it. To force a shallow or deep clone, you can set the
65`gitShallow` option to `true` or `false` respectively.
66
67### `git.revs(repo, opts = {})` -> `Promise<rev doc Object>`
68
69Fetch a representation of all of the named references in a given
70repository. The resulting doc is intentionally somewhat
71[packument](https://www.npmjs.com/package/pacote#packuments)-like, so that
72git semver ranges can be applied using the same
73[`npm-pick-manifest`](http://npm.im/npm-pick-manifest) logic.
74
75The resulting object looks like:
76
77```js
78revs = {
79 versions: {
80 // all semver-looking tags go in here...
81 // version: { sha, ref, rawRef, type }
82 '1.0.0': {
83 sha: '1bc5fba3353f8e1b56493b266bc459276ab23139',
84 ref: 'v1.0.0',
85 rawRef: 'refs/tags/v1.0.0',
86 type: 'tag',
87 },
88 },
89 'dist-tags': {
90 HEAD: '1.0.0',
91 latest: '1.0.0',
92 },
93 refs: {
94 // all the advertised refs that can be cloned down remotely
95 HEAD: { sha, ref, rawRef, type: 'head' },
96 master: { ... },
97 'v1.0.0': { ... },
98 'refs/tags/v1.0.0': { ... },
99 },
100 shas: {
101 // all named shas referenced above
102 // sha: [list, of, refs]
103 '6b2501f9183a1753027a9bf89a184b7d3d4602c7': [
104 'HEAD',
105 'master',
106 'refs/heads/master',
107 ],
108 '1bc5fba3353f8e1b56493b266bc459276ab23139': [ 'v1.0.0', 'refs/tags/v1.0.0' ],
109 },
110}
111```
112
113### `git.is(opts)` -> `Promise<Boolean>`
114
115Resolve to `true` if the path argument refers to the root of a git
116repository.
117
118It does this by looking for a file in `${path}/.git/index`, which is not an
119airtight indicator, but at least avoids being fooled by an empty directory
120or a file named `.git`.
121
122### `git.find(opts)` -> `Promise<String | null>`
123
124Given a path, walk up the file system tree until a git repo working
125directory is found. Since this calls `stat` a bunch of times, it's
126probably best to only call it if you're reasonably sure you're likely to be
127in a git project somewhere.
128
129Resolves to `null` if not in a git project.
130
131### `git.isClean(opts = {})` -> `Promise<Boolean>`
132
133Return true if in a git dir, and that git dir is free of changes. This
134will resolve `true` if the git working dir is clean, or `false` if not, and
135reject if the path is not within a git directory or some other error
136occurs.
137
138## OPTIONS
139
140- `retry` An object to configure retry behavior for transient network
141 errors with exponential backoff.
142 - `retries`: Defaults to `opts.fetchRetries` or 2
143 - `factor`: Defaults to `opts.fetchRetryFactor` or 10
144 - `maxTimeout`: Defaults to `opts.fetchRetryMaxtimeout` or 60000
145 - `minTimeout`: Defaults to `opts.fetchRetryMintimeout` or 1000
146- `git` Path to the `git` binary to use. Will look up the first `git` in
147 the `PATH` if not specified.
148- `spec` The [`npm-package-arg`](http://npm.im/npm-package-arg) specifier
149 object for the thing being fetched (if relevant).
150- `fakePlatform` set to a fake value of `process.platform` to use. (Just
151 for testing `win32` behavior on Unix, and vice versa.)
152- `cwd` The current working dir for the git command. Particularly for
153 `find` and `is` and `isClean`, it's good to know that this defaults to
154 `process.cwd()`, as one might expect.
155- Any other options that can be passed to
156 [`@npmcli/promise-spawn`](http://npm.im/@npmcli/promise-spawn), or
157 `child_process.spawn()`.
Note: See TracBrowser for help on using the repository browser.