History

Update Git documentation (2.30.0)

Simon Legner committed 5 years ago

Commit 3600a9f1 parent 8f17cfa41 files · +4398 −1Browse files

Showing the changes to node_modules/simple-git/promise.d.ts (1 of 41 files). Show all

Unified · Split

node_modules/simple-git/promise.d.ts+576−0
@@ -0,0 +1,576 @@
1import * as resp from "./typings/response";
2
3declare function simplegit(basePath?: string): simplegit.SimpleGit;
4
5declare namespace simplegit {
6
7 interface SimpleGit {
8 /**
9 * Adds one or more files to source control
10 *
11 * @param {string|string[]} files
12 * @returns {Promise<void>}
13 */
14 add(files: string | string[]): Promise<void>;
15
16 /**
17 * Add an annotated tag to the head of the current branch
18 *
19 * @param {string} tagName
20 * @param {string} tagMessage
21 * @returns {Promise<void>}
22 */
23 addAnnotatedTag(tagName: string, tagMessage: string): Promise<void>;
24
25 /**
26 * Add config to local git instance
27 *
28 * @param {string} key configuration key (e.g user.name)
29 * @param {string} value for the given key (e.g your name)
30 * @returns {Promise<string>}
31 */
32 addConfig(key: string, value: string): Promise<string>;
33
34 /**
35 * Adds a remote to the list of remotes.
36 *
37 * @param {string} remoteName Name of the repository - eg "upstream"
38 * @param {string} remoteRepo Fully qualified SSH or HTTP(S) path to the remote repo
39 * @returns {Promise<void>}
40 */
41 addRemote(remoteName: string, remoteRepo: string): Promise<void>;
42
43 /**
44 * Add a lightweight tag to the head of the current branch
45 *
46 * @param {string} name
47 * @returns {Promise<string>}
48 */
49 addTag(name: string): Promise<string>;
50
51 /**
52 * Equivalent to `catFile` but will return the native `Buffer` of content from the git command's stdout.
53 *
54 * @param {string[]} options
55 */
56 binaryCatFile(options: string[]): Promise<any>;
57
58 /**
59 * List all branches
60 */
61 branch(): Promise<BranchSummary>;
62 branch(options: Options | string[]): Promise<BranchSummary>;
63
64 /**
65 * List of local branches
66 *
67 * @returns {Promise<BranchSummary>}
68 */
69 branchLocal(): Promise<BranchSummary>;
70
71 /**
72 * Returns a list of objects in a tree based on commit hash.
73 * Passing in an object hash returns the object's content, size, and type.
74 *
75 * Passing "-p" will instruct cat-file to determine the object type, and display its formatted contents.
76 *
77 * @param {string[]} [options]
78 * @returns {Promise<string>}
79 *
80 * @see https://git-scm.com/docs/git-cat-file
81 */
82 catFile(options: string[]): Promise<string>;
83
84 /**
85 * Check if a pathname or pathnames are excluded by .gitignore
86 *
87 * @param {string|string[]} pathnames
88 */
89 checkIgnore(pathnames: string[]): Promise<string[]>;
90
91 checkIgnore(path: string): Promise<string[]>;
92
93 /**
94 * Validates that the current repo is a Git repo.
95 *
96 * @returns {Promise<boolean>}
97 */
98 checkIsRepo(): Promise<boolean>;
99
100 /**
101 * Checkout a tag or revision, any number of additional arguments can be passed to the `git* checkout` command
102 by supplying either a string or array of strings as the `what` parameter.
103 *
104 * @param {(string | string[])} what one or more commands to pass to `git checkout`.
105 * @returns {Promise<void>}
106 */
107 checkout(what: string | string[]): Promise<void>;
108
109 /**
110 * Checkout a remote branch.
111 *
112 * @param {string} branchName name of branch.
113 * @param {string} startPoint (e.g origin/development).
114 * @returns {Promise<void>}
115 */
116 checkoutBranch(branchName: string, startPoint: string): Promise<void>;
117
118 /**
119 * Internally uses pull and tags to get the list of tags then checks out the latest tag.
120 */
121 checkoutLatestTag(branchName: string, startPoint: string): Promise<void>;
122
123 /**
124 * Checkout a local branch
125 *
126 * @param {string} branchName name of branch.
127 * @returns {Promise<void>}
128 */
129 checkoutLocalBranch(branchName: string): Promise<void>;
130
131 /**
132 * @param {string} mode Required parameter "n" or "f"
133 * @param {string[]} options
134 */
135 clean(
136 mode: 'd' | 'f' | 'i' | 'n' | 'q' | 'x' | 'X',
137 options?: string[]
138 ): Promise<string>;
139
140 /**
141 * Clears the queue of pending commands and returns the wrapper instance for chaining.
142 */
143 clearQueue(): this;
144
145 /**
146 * Clone a repository into a new directory.
147 *
148 * @param {string} repoPath repository url to clone e.g. https://github.com/steveukx/git-js.git
149 * @param {string} localPath local folder path to clone to.
150 * @param {string[]} [options] options supported by [git](https://git-scm.com/docs/git-clone).
151 * @returns {Promise<void>}
152 */
153 clone(repoPath: string, localPath: string, options?: Options | string[]): Promise<string>;
154 clone(repoPath: string, options?: Options | string[]): Promise<string>;
155
156 /**
157 * Commits changes in the current working directory - when specific file paths are supplied, only changes on those
158 * files will be committed.
159 *
160 * @param {string|string[]} message
161 * @param {string|string[]} [files]
162 * @param {Object} [options]
163 */
164 commit(
165 message: string | string[],
166 files?: string | string[],
167 options?: Options
168 ): Promise<resp.CommitSummary>;
169
170 /**
171 * Sets the path to a custom git binary, should either be `git` when there is an installation of git available on
172 * the system path, or a fully qualified path to the executable.
173 *
174 * @param {string} command
175 */
176 customBinary(command: string): this;
177
178 /**
179 * Sets the working directory of the subsequent commands.
180 *
181 * @param {string} workingDirectory
182 */
183 cwd<path extends string>(workingDirectory: path): Promise<path>;
184
185 /**
186 * Delete a local branch
187 *
188 * @param {string} branchName name of branch
189 */
190 deleteLocalBranch(branchName: string):
191 Promise<resp.BranchDeletionSummary>;
192
193 /**
194 * Get the diff of the current repo compared to the last commit with a set of options supplied as a string.
195 *
196 * @param {string[]} [options] options supported by [git](https://git-scm.com/docs/git-diff).
197 * @returns {Promise<string>} raw string result.
198 */
199 diff(options?: string[]): Promise<string>;
200
201 /**
202 * Gets a summary of the diff for files in the repo, uses the `git diff --stat` format to calculate changes.
203 *
204 * in order to get staged (only): `--cached` or `--staged`.
205 *
206 * @param {string[]} [options] options supported by [git](https://git-scm.com/docs/git-diff).
207 * @returns {Promise<DiffResult>} Parsed diff summary result.
208 */
209 diffSummary(options?: string[]): Promise<DiffResult>;
210
211 /**
212 * Sets an environment variable for the spawned child process, either supply both a name and value as strings or
213 * a single object to entirely replace the current environment variables.
214 *
215 * @param {string|Object} name
216 * @param {string} [value]
217 */
218 env(name: string, value: string): this;
219
220 env(env: object): this;
221
222 /**
223 * Updates the local working copy database with changes from the default remote repo and branch.
224 *
225 * @param {string | string[]} [remote] remote to fetch from.
226 * @param {string} [branch] branch to fetch from.
227 * @param {string[]} [options] options supported by [git](https://git-scm.com/docs/git-fetch).
228 * @returns {Promise<FetchResult>} Parsed fetch result.
229 */
230 fetch(remote?: string | string[], branch?: string, options?: Options): Promise<FetchResult>;
231
232 /**
233 * Gets the currently available remotes, setting the optional verbose argument to true includes additional
234 * detail on the remotes themselves.
235 *
236 * @param {boolean} [verbose=false]
237 */
238 getRemotes(verbose: false | undefined): Promise<resp.RemoteWithoutRefs[]>;
239
240 getRemotes(verbose: true): Promise<resp.RemoteWithRefs[]>;
241
242 /**
243 * Initialize a git repo
244 *
245 * @param {Boolean} [bare=false]
246 */
247 init(bare?: boolean): Promise<void>;
248
249 /**
250 * List remote
251 *
252 * @param {string[]} [args]
253 */
254 listRemote(args: string[]): Promise<string>;
255
256 /**
257 * Show commit logs from `HEAD` to the first commit.
258 * If provided between `options.from` and `options.to` tags or branch.
259 *
260 * You can provide `options.file`, which is the path to a file in your repository. Then only this file will be considered.
261 *
262 * To use a custom splitter in the log format, set `options.splitter` to be the string the log should be split on.
263 *
264 * By default the following fields will be part of the result:
265 * `hash`: full commit hash
266 * `date`: author date, ISO 8601-like format
267 * `message`: subject + ref names, like the --decorate option of git-log
268 * `author_name`: author name
269 * `author_email`: author mail
270 * You can specify `options.format` to be an mapping from key to a format option like `%H` (for commit hash).
271 * The fields specified in `options.format` will be the fields in the result.
272 *
273 * Options can also be supplied as a standard options object for adding custom properties supported by the git log command.
274 * For any other set of options, supply options as an array of strings to be appended to the git log command.
275 *
276 * @param {LogOptions} [options]
277 *
278 * @returns Promise<ListLogSummary>
279 *
280 * @see https://git-scm.com/docs/git-log
281 */
282 log<T = resp.DefaultLogFields>(options?: LogOptions<T>): Promise<resp.ListLogSummary<T>>;
283
284 /**
285 * Runs a merge, `options` can be either an array of arguments
286 * supported by the [`git merge`](https://git-scm.com/docs/git-merge)
287 * or an options object.
288 *
289 * Conflicts during the merge result in an error response,
290 * the response type whether it was an error or success will be a MergeSummary instance.
291 * When successful, the MergeSummary has all detail from a the PullSummary
292 *
293 * @param {Options | string[]} [options] options supported by [git](https://git-scm.com/docs/git-merge).
294 * @returns {Promise<any>}
295 *
296 * @see https://github.com/steveukx/git-js/blob/master/src/responses/MergeSummary.js
297 * @see https://github.com/steveukx/git-js/blob/master/src/responses/PullSummary.js
298 */
299 merge(options: Options | string[]): Promise<MergeSummary>;
300
301 /**
302 * Merges from one branch to another, equivalent to running `git merge ${from} $[to}`, the `options` argument can
303 * either be an array of additional parameters to pass to the command or null / omitted to be ignored.
304 *
305 * @param {string} from branch to merge from.
306 * @param {string} to branch to merge to.
307 * @param {string[]} [options] options supported by [git](https://git-scm.com/docs/git-merge).
308 * @returns {Promise<string>}
309 */
310 mergeFromTo(from: string, to: string, options?: string[]): Promise<string>;
311
312 /**
313 * Mirror a git repo
314 *
315 * @param {string} repoPath
316 * @param {string} localPath
317 */
318 mirror(repoPath: string, localPath: string): Promise<string>;
319
320 /**
321 * Moves one or more files to a new destination.
322 *
323 * @see https://git-scm.com/docs/git-mv
324 *
325 * @param {string|string[]} from
326 * @param {string} to
327 */
328 mv(from: string | string[], to: string): Promise<resp.MoveSummary>;
329
330 /**
331 * Sets a handler function to be called whenever a new child process is created, the handler function will be called
332 * with the name of the command being run and the stdout & stderr streams used by the ChildProcess.
333 *
334 * @example
335 * require('simple-git')
336 * .outputHandler(function (command, stdout, stderr) {
337 * stdout.pipe(process.stdout);
338 * })
339 * .checkout('https://github.com/user/repo.git');
340 *
341 * @see https://nodejs.org/api/child_process.html#child_process_class_childprocess
342 * @see https://nodejs.org/api/stream.html#stream_class_stream_readable
343 * @param {Function} outputHandler
344 */
345 outputHandler(handler: outputHandler | void): this;
346
347 /**
348 * Fetch from and integrate with another repository or a local branch.
349 *
350 * @param {string} [remote] remote to pull from.
351 * @param {string} [branch] branch to pull from.
352 * @param {Options} [options] options supported by [git](https://git-scm.com/docs/git-pull).
353 * @returns {Promise<PullResult>} Parsed pull result.
354 */
355 pull(remote?: string, branch?: string, options?: Options): Promise<PullResult>;
356
357 /**
358 * Update remote refs along with associated objects.
359 *
360 * @param {string} [remote] remote to push to.
361 * @param {string} [branch] branch to push to.
362 * @param {Options} [options] options supported by [git](https://git-scm.com/docs/git-push).
363 * @returns {Promise<void>}
364 */
365 push(remote?: string, branch?: string, options?: Options): Promise<void>;
366
367 /**
368 * Pushes the current tag changes to a remote which can be either a URL or named remote. When not specified uses the
369 * default configured remote spec.
370 *
371 * @param {string} [remote]
372 */
373 pushTags(remote?: string): Promise<string>;
374
375 /**
376 * Executes any command against the git binary.
377 *
378 * @param {string[]|Object} commands
379 */
380 raw(commands: string | string[]): Promise<string>;
381
382 /**
383 * Rebases the current working copy. Options can be supplied either as an array of string parameters
384 * to be sent to the `git rebase` command, or a standard options object.
385 *
386 * @param {Object|String[]} [options]
387 */
388 rebase(options?: Options | string[]): Promise<string>;
389
390 /**
391 * Call any `git remote` function with arguments passed as an array of strings.
392 *
393 * @param {string[]} options
394 */
395 remote(options: string[]): Promise<void | string>;
396
397 /**
398 * Removes an entry from the list of remotes.
399 *
400 * @param {string} remoteName Name of the repository - eg "upstream"
401 * @returns {*}
402 */
403 removeRemote(remote: string): Promise<void>;
404
405 /**
406 * Reset a repo
407 *
408 * @param {string|string[]} [mode=soft] Either an array of arguments supported by the 'git reset' command, or the string value 'soft' or 'hard' to set the reset mode.
409 */
410 reset(mode?: 'soft' | 'mixed' | 'hard' | 'merge' | 'keep'): Promise<null>;
411
412 reset(commands?: string[]): Promise<void>;
413
414 /**
415 * Revert one or more commits in the local working copy
416 *
417 * @param {string} commit The commit to revert. Can be any hash, offset (eg: `HEAD~2`) or range (eg: `master~5..master~2`)
418 * @param {Object} [options] Optional options object
419 */
420 revert(commit: String, options?: Options): Promise<void>;
421
422 /**
423 * Wraps `git rev-parse`. Primarily used to convert friendly commit references (ie branch names) to SHA1 hashes.
424 *
425 * Options should be an array of string options compatible with the `git rev-parse`
426 *
427 * @param {string[]} [options]
428 *
429 * @returns Promise<string>
430 *
431 * @see https://git-scm.com/docs/git-rev-parse
432 */
433 revparse(options?: string[]): Promise<string>;
434
435 /**
436 * Removes the named files from source control.
437 *
438 * @param {string|string[]} files
439 */
440 rm(paths: string | string[]): Promise<void>;
441
442 /**
443 * Removes the named files from source control but keeps them on disk rather than deleting them entirely. To
444 * completely remove the files, use `rm`.
445 *
446 * @param {string|string[]} files
447 */
448 rmKeepLocal(paths: string | string[]): Promise<void>;
449
450 /**
451 * Show various types of objects, for example the file at a certain commit
452 *
453 * @param {string[]} [options]
454 */
455 show(options?: string[]): Promise<string>;
456
457 /**
458 * Disables/enables the use of the console for printing warnings and errors, by default messages are not shown in
459 * a production environment.
460 *
461 * @param {boolean} silence
462 * @returns {simplegit.SimpleGit}
463 */
464 silent(silence?: boolean): simplegit.SimpleGit;
465
466 /**
467 * Stash the local repo
468 *
469 * @param {Object|Array} [options]
470 */
471 stash(options?: Options | any[]): Promise<string>;
472
473 /**
474 * List the stash(s) of the local repo
475 *
476 * @param {Object|Array} [options]
477 */
478 stashList(options?: Options | string[]): Promise<resp.ListLogSummary>;
479
480 /**
481 * Show the working tree status.
482 *
483 * @returns {Promise<StatusResult>} Parsed status result.
484 */
485 status(): Promise<StatusResult>;
486
487 /**
488 * Call any `git submodule` function with arguments passed as an array of strings.
489 *
490 * @param {string[]} options
491 */
492 subModule(options: string[]): Promise<string>;
493
494 /**
495 * Add a submodule
496 *
497 * @param {string} repo
498 * @param {string} path
499 */
500 submoduleAdd(repo: string, path: string): Promise<void>;
501
502 /**
503 * Initialize submodules
504 *
505 * @param {string[]} [args]
506 */
507 submoduleInit(options?: string[]): Promise<string>;
508
509 /**
510 * Update submodules
511 *
512 * @param {string[]} [args]
513 */
514 submoduleUpdate(options?: string[]): Promise<string>;
515
516 /**
517 * List all tags. When using git 2.7.0 or above, include an options object with `"--sort": "property-name"` to
518 * sort the tags by that property instead of using the default semantic versioning sort.
519 *
520 * Note, supplying this option when it is not supported by your Git version will cause the operation to fail.
521 *
522 * @param {Object} [options]
523 */
524 tag(options?: Options | string[]): Promise<string>;
525
526 /**
527 * Gets a list of tagged versions.
528 *
529 * @param {Options} options
530 * @returns {Promise<TagResult>} Parsed tag list.
531 */
532 tags(options?: Options): Promise<TagResult>;
533
534 /**
535 * Updates repository server info
536 */
537 updateServerInfo(): Promise<string>;
538 }
539
540 type Options = { [key: string]: null | string | any };
541
542 type LogOptions<T = resp.DefaultLogFields> = Options & {
543 format?: T;
544 file?: string;
545 from?: string;
546 multiLine?: boolean;
547 symmetric?: boolean;
548 to?: string;
549 };
550
551 // responses
552 // ---------------------
553 interface BranchSummary extends resp.BranchSummary {}
554
555 interface CommitSummary extends resp.CommitSummary {}
556
557 interface MergeSummary extends resp.MergeSummary {}
558
559 interface PullResult extends resp.PullResult {}
560
561 interface FetchResult extends resp.FetchResult {}
562
563 interface StatusResult extends resp.StatusResult {}
564
565 interface DiffResult extends resp.DiffResult {}
566
567 interface TagResult extends resp.TagResult {}
568
569 type outputHandler = (
570 command: string,
571 stdout: NodeJS.ReadableStream,
572 stderr: NodeJS.ReadableStream
573 ) => void
574}
575
576export = simplegit;

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t