1 | export default index;
|
2 | export type TreeEntry = {
|
3 | /**
|
4 | * - the 6 digit hexadecimal mode
|
5 | */
|
6 | mode: string;
|
7 | /**
|
8 | * - the name of the file or directory
|
9 | */
|
10 | path: string;
|
11 | /**
|
12 | * - the SHA-1 object id of the blob or tree
|
13 | */
|
14 | oid: string;
|
15 | /**
|
16 | * - the type of object
|
17 | */
|
18 | type: "blob" | "tree" | "commit";
|
19 | };
|
20 | /**
|
21 | * - The object returned has the following schema:
|
22 | */
|
23 | export type ReadTreeResult = {
|
24 | /**
|
25 | * - SHA-1 object id of this tree
|
26 | */
|
27 | oid: string;
|
28 | /**
|
29 | * - the parsed tree object
|
30 | */
|
31 | tree: TreeEntry[];
|
32 | };
|
33 | /**
|
34 | * - The object returned has the following schema:
|
35 | */
|
36 | export type FetchResult = {
|
37 | /**
|
38 | * - The branch that is cloned if no branch is specified
|
39 | */
|
40 | defaultBranch: string | null;
|
41 | /**
|
42 | * - The SHA-1 object id of the fetched head commit
|
43 | */
|
44 | fetchHead: string | null;
|
45 | /**
|
46 | * - a textual description of the branch that was fetched
|
47 | */
|
48 | fetchHeadDescription: string | null;
|
49 | /**
|
50 | * - The HTTP response headers returned by the git server
|
51 | */
|
52 | headers?: {
|
53 | [x: string]: string;
|
54 | };
|
55 | /**
|
56 | * - A list of branches that were pruned, if you provided the `prune` parameter
|
57 | */
|
58 | pruned?: string[];
|
59 | };
|
60 | /**
|
61 | * - Returns an object with a schema like this:
|
62 | */
|
63 | export type MergeResult = {
|
64 | /**
|
65 | * - The SHA-1 object id that is now at the head of the branch. Absent only if `dryRun` was specified and `mergeCommit` is true.
|
66 | */
|
67 | oid?: string;
|
68 | /**
|
69 | * - True if the branch was already merged so no changes were made
|
70 | */
|
71 | alreadyMerged?: boolean;
|
72 | /**
|
73 | * - True if it was a fast-forward merge
|
74 | */
|
75 | fastForward?: boolean;
|
76 | /**
|
77 | * - True if merge resulted in a merge commit
|
78 | */
|
79 | mergeCommit?: boolean;
|
80 | /**
|
81 | * - The SHA-1 object id of the tree resulting from a merge commit
|
82 | */
|
83 | tree?: string;
|
84 | };
|
85 | /**
|
86 | * - The object returned has the following schema:
|
87 | */
|
88 | export type GetRemoteInfoResult = {
|
89 | /**
|
90 | * - The list of capabilities returned by the server (part of the Git protocol)
|
91 | */
|
92 | capabilities: string[];
|
93 | refs?: any;
|
94 | /**
|
95 | * - The default branch of the remote
|
96 | */
|
97 | HEAD?: string;
|
98 | /**
|
99 | * - The branches on the remote
|
100 | */
|
101 | heads?: {
|
102 | [x: string]: string;
|
103 | };
|
104 | /**
|
105 | * - The special branches representing pull requests (non-standard)
|
106 | */
|
107 | pull?: {
|
108 | [x: string]: string;
|
109 | };
|
110 | /**
|
111 | * - The tags on the remote
|
112 | */
|
113 | tags?: {
|
114 | [x: string]: string;
|
115 | };
|
116 | };
|
117 | /**
|
118 | * - This object has the following schema:
|
119 | */
|
120 | export type GetRemoteInfo2Result = {
|
121 | /**
|
122 | * - Git protocol version the server supports
|
123 | */
|
124 | protocolVersion: 1 | 2;
|
125 | /**
|
126 | * - An object of capabilities represented as keys and values
|
127 | */
|
128 | capabilities: {
|
129 | [x: string]: string | true;
|
130 | };
|
131 | /**
|
132 | * - Server refs (they get returned by protocol version 1 whether you want them or not)
|
133 | */
|
134 | refs?: ServerRef[];
|
135 | };
|
136 | /**
|
137 | * - The object returned has the following schema:
|
138 | */
|
139 | export type HashBlobResult = {
|
140 | /**
|
141 | * - The SHA-1 object id
|
142 | */
|
143 | oid: string;
|
144 | /**
|
145 | * - The type of the object
|
146 | */
|
147 | type: "blob";
|
148 | /**
|
149 | * - The wrapped git object (the thing that is hashed)
|
150 | */
|
151 | object: Uint8Array;
|
152 | /**
|
153 | * - The format of the object
|
154 | */
|
155 | format: "wrapped";
|
156 | };
|
157 | /**
|
158 | * - This object has the following schema:
|
159 | */
|
160 | export type ServerRef = {
|
161 | /**
|
162 | * - The name of the ref
|
163 | */
|
164 | ref: string;
|
165 | /**
|
166 | * - The SHA-1 object id the ref points to
|
167 | */
|
168 | oid: string;
|
169 | /**
|
170 | * - The target ref pointed to by a symbolic ref
|
171 | */
|
172 | target?: string;
|
173 | /**
|
174 | * - If the oid is the SHA-1 object id of an annotated tag, this is the SHA-1 object id that the annotated tag points to
|
175 | */
|
176 | peeled?: string;
|
177 | };
|
178 | /**
|
179 | * The packObjects command returns an object with two properties:
|
180 | */
|
181 | export type PackObjectsResult = {
|
182 | /**
|
183 | * - The suggested filename for the packfile if you want to save it to disk somewhere. It includes the packfile SHA.
|
184 | */
|
185 | filename: string;
|
186 | /**
|
187 | * - The packfile contents. Not present if `write` parameter was true, in which case the packfile was written straight to disk.
|
188 | */
|
189 | packfile?: Uint8Array;
|
190 | };
|
191 | /**
|
192 | * - The object returned has the following schema:
|
193 | */
|
194 | export type ReadBlobResult = {
|
195 | oid: string;
|
196 | blob: Uint8Array;
|
197 | };
|
198 | export type DeflatedObject = {
|
199 | oid: string;
|
200 | type: "deflated";
|
201 | format: "deflated";
|
202 | object: Uint8Array;
|
203 | source?: string;
|
204 | };
|
205 | export type WrappedObject = {
|
206 | oid: string;
|
207 | type: "wrapped";
|
208 | format: "wrapped";
|
209 | object: Uint8Array;
|
210 | source?: string;
|
211 | };
|
212 | export type RawObject = {
|
213 | oid: string;
|
214 | type: "blob" | "tree" | "commit" | "tag";
|
215 | format: "content";
|
216 | object: Uint8Array;
|
217 | source?: string;
|
218 | };
|
219 | export type ParsedBlobObject = {
|
220 | oid: string;
|
221 | type: "blob";
|
222 | format: "parsed";
|
223 | object: string;
|
224 | source?: string;
|
225 | };
|
226 | export type ParsedCommitObject = {
|
227 | oid: string;
|
228 | type: "commit";
|
229 | format: "parsed";
|
230 | object: CommitObject;
|
231 | source?: string;
|
232 | };
|
233 | export type ParsedTreeObject = {
|
234 | oid: string;
|
235 | type: "tree";
|
236 | format: "parsed";
|
237 | object: TreeEntry[];
|
238 | source?: string;
|
239 | };
|
240 | export type ParsedTagObject = {
|
241 | oid: string;
|
242 | type: "tag";
|
243 | format: "parsed";
|
244 | object: TagObject;
|
245 | source?: string;
|
246 | };
|
247 | export type ParsedObject = ParsedBlobObject | ParsedCommitObject | ParsedTreeObject | ParsedTagObject;
|
248 | export type ReadObjectResult = ParsedBlobObject | ParsedCommitObject | ParsedTreeObject | ParsedTagObject | DeflatedObject | WrappedObject | RawObject;
|
249 | /**
|
250 | * - The object returned has the following schema:
|
251 | */
|
252 | export type ReadTagResult = {
|
253 | /**
|
254 | * - SHA-1 object id of this tag
|
255 | */
|
256 | oid: string;
|
257 | /**
|
258 | * - the parsed tag object
|
259 | */
|
260 | tag: TagObject;
|
261 | /**
|
262 | * - PGP signing payload
|
263 | */
|
264 | payload: string;
|
265 | };
|
266 | export type WalkerMap = (filename: string, entries: (WalkerEntry | null)[]) => Promise<any>;
|
267 | export type WalkerReduce = (parent: any, children: any[]) => Promise<any>;
|
268 | export type WalkerIterateCallback = (entries: WalkerEntry[]) => Promise<any[]>;
|
269 | export type WalkerIterate = (walk: WalkerIterateCallback, children: any) => Promise<any[]>;
|
270 | export type GitProgressEvent = {
|
271 | phase: string;
|
272 | loaded: number;
|
273 | total: number;
|
274 | };
|
275 | export type ProgressCallback = (progress: GitProgressEvent) => void | Promise<void>;
|
276 | export type GitHttpRequest = {
|
277 | /**
|
278 | * - The URL to request
|
279 | */
|
280 | url: string;
|
281 | /**
|
282 | * - The HTTP method to use
|
283 | */
|
284 | method?: string;
|
285 | /**
|
286 | * - Headers to include in the HTTP request
|
287 | */
|
288 | headers?: {
|
289 | [x: string]: string;
|
290 | };
|
291 | /**
|
292 | * - An async iterator of Uint8Arrays that make up the body of POST requests
|
293 | */
|
294 | body?: any;
|
295 | /**
|
296 | * - Reserved for future use (emitting `GitProgressEvent`s)
|
297 | */
|
298 | onProgress?: ProgressCallback;
|
299 | /**
|
300 | * - Reserved for future use (canceling a request)
|
301 | */
|
302 | signal?: any;
|
303 | };
|
304 | export type GitHttpResponse = {
|
305 | /**
|
306 | * - The final URL that was fetched after any redirects
|
307 | */
|
308 | url: string;
|
309 | /**
|
310 | * - The HTTP method that was used
|
311 | */
|
312 | method?: string;
|
313 | /**
|
314 | * - HTTP response headers
|
315 | */
|
316 | headers?: {
|
317 | [x: string]: string;
|
318 | };
|
319 | /**
|
320 | * - An async iterator of Uint8Arrays that make up the body of the response
|
321 | */
|
322 | body?: any;
|
323 | /**
|
324 | * - The HTTP status code
|
325 | */
|
326 | statusCode: number;
|
327 | /**
|
328 | * - The HTTP status message
|
329 | */
|
330 | statusMessage: string;
|
331 | };
|
332 | export type HttpFetch = (request: GitHttpRequest) => Promise<GitHttpResponse>;
|
333 | export type HttpClient = {
|
334 | request: HttpFetch;
|
335 | };
|
336 | /**
|
337 | * A git commit object.
|
338 | */
|
339 | export type CommitObject = {
|
340 | /**
|
341 | * Commit message
|
342 | */
|
343 | message: string;
|
344 | /**
|
345 | * SHA-1 object id of corresponding file tree
|
346 | */
|
347 | tree: string;
|
348 | /**
|
349 | * an array of zero or more SHA-1 object ids
|
350 | */
|
351 | parent: string[];
|
352 | author: {
|
353 | /**
|
354 | * The author's name
|
355 | */
|
356 | name: string;
|
357 | /**
|
358 | * The author's email
|
359 | */
|
360 | email: string;
|
361 | /**
|
362 | * UTC Unix timestamp in seconds
|
363 | */
|
364 | timestamp: number;
|
365 | /**
|
366 | * Timezone difference from UTC in minutes
|
367 | */
|
368 | timezoneOffset: number;
|
369 | };
|
370 | committer: {
|
371 | /**
|
372 | * The committer's name
|
373 | */
|
374 | name: string;
|
375 | /**
|
376 | * The committer's email
|
377 | */
|
378 | email: string;
|
379 | /**
|
380 | * UTC Unix timestamp in seconds
|
381 | */
|
382 | timestamp: number;
|
383 | /**
|
384 | * Timezone difference from UTC in minutes
|
385 | */
|
386 | timezoneOffset: number;
|
387 | };
|
388 | /**
|
389 | * PGP signature (if present)
|
390 | */
|
391 | gpgsig?: string;
|
392 | };
|
393 | /**
|
394 | * A git tree object. Trees represent a directory snapshot.
|
395 | */
|
396 | export type TreeObject = TreeEntry[];
|
397 | /**
|
398 | * A git annotated tag object.
|
399 | */
|
400 | export type TagObject = {
|
401 | /**
|
402 | * SHA-1 object id of object being tagged
|
403 | */
|
404 | object: string;
|
405 | /**
|
406 | * the type of the object being tagged
|
407 | */
|
408 | type: "blob" | "tree" | "commit" | "tag";
|
409 | /**
|
410 | * the tag name
|
411 | */
|
412 | tag: string;
|
413 | tagger: {
|
414 | /**
|
415 | * the tagger's name
|
416 | */
|
417 | name: string;
|
418 | /**
|
419 | * the tagger's email
|
420 | */
|
421 | email: string;
|
422 | /**
|
423 | * UTC Unix timestamp in seconds
|
424 | */
|
425 | timestamp: number;
|
426 | /**
|
427 | * timezone difference from UTC in minutes
|
428 | */
|
429 | timezoneOffset: number;
|
430 | };
|
431 | /**
|
432 | * tag message
|
433 | */
|
434 | message: string;
|
435 | /**
|
436 | * PGP signature (if present)
|
437 | */
|
438 | gpgsig?: string;
|
439 | };
|
440 | export type ReadCommitResult = {
|
441 | /**
|
442 | * - SHA-1 object id of this commit
|
443 | */
|
444 | oid: string;
|
445 | /**
|
446 | * - the parsed commit object
|
447 | */
|
448 | commit: CommitObject;
|
449 | /**
|
450 | * - PGP signing payload
|
451 | */
|
452 | payload: string;
|
453 | };
|
454 | export type Walker = {
|
455 | /**
|
456 | * ('GitWalkerSymbol')
|
457 | */
|
458 | Symbol: Symbol;
|
459 | };
|
460 | /**
|
461 | * Normalized subset of filesystem `stat` data:
|
462 | */
|
463 | export type Stat = {
|
464 | ctimeSeconds: number;
|
465 | ctimeNanoseconds: number;
|
466 | mtimeSeconds: number;
|
467 | mtimeNanoseconds: number;
|
468 | dev: number;
|
469 | ino: number;
|
470 | mode: number;
|
471 | uid: number;
|
472 | gid: number;
|
473 | size: number;
|
474 | };
|
475 | /**
|
476 | * The `WalkerEntry` is an interface that abstracts computing many common tree / blob stats.
|
477 | */
|
478 | export type WalkerEntry = {
|
479 | type: () => Promise<"blob" | "tree" | "commit" | "special">;
|
480 | mode: () => Promise<number>;
|
481 | oid: () => Promise<string>;
|
482 | content: () => Promise<void | Uint8Array>;
|
483 | stat: () => Promise<Stat>;
|
484 | };
|
485 | export type CallbackFsClient = {
|
486 | /**
|
487 | * - https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback
|
488 | */
|
489 | readFile: Function;
|
490 | /**
|
491 | * - https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback
|
492 | */
|
493 | writeFile: Function;
|
494 | /**
|
495 | * - https://nodejs.org/api/fs.html#fs_fs_unlink_path_callback
|
496 | */
|
497 | unlink: Function;
|
498 | /**
|
499 | * - https://nodejs.org/api/fs.html#fs_fs_readdir_path_options_callback
|
500 | */
|
501 | readdir: Function;
|
502 | /**
|
503 | * - https://nodejs.org/api/fs.html#fs_fs_mkdir_path_mode_callback
|
504 | */
|
505 | mkdir: Function;
|
506 | /**
|
507 | * - https://nodejs.org/api/fs.html#fs_fs_rmdir_path_callback
|
508 | */
|
509 | rmdir: Function;
|
510 | /**
|
511 | * - https://nodejs.org/api/fs.html#fs_fs_stat_path_options_callback
|
512 | */
|
513 | stat: Function;
|
514 | /**
|
515 | * - https://nodejs.org/api/fs.html#fs_fs_lstat_path_options_callback
|
516 | */
|
517 | lstat: Function;
|
518 | /**
|
519 | * - https://nodejs.org/api/fs.html#fs_fs_readlink_path_options_callback
|
520 | */
|
521 | readlink?: Function;
|
522 | /**
|
523 | * - https://nodejs.org/api/fs.html#fs_fs_symlink_target_path_type_callback
|
524 | */
|
525 | symlink?: Function;
|
526 | /**
|
527 | * - https://nodejs.org/api/fs.html#fs_fs_chmod_path_mode_callback
|
528 | */
|
529 | chmod?: Function;
|
530 | };
|
531 | export type PromiseFsClient = {
|
532 | promises: {
|
533 | /**
|
534 | * - https://nodejs.org/api/fs.html#fs_fspromises_readfile_path_options
|
535 | */
|
536 | readFile: Function;
|
537 | /**
|
538 | * - https://nodejs.org/api/fs.html#fs_fspromises_writefile_file_data_options
|
539 | */
|
540 | writeFile: Function;
|
541 | /**
|
542 | * - https://nodejs.org/api/fs.html#fs_fspromises_unlink_path
|
543 | */
|
544 | unlink: Function;
|
545 | /**
|
546 | * - https://nodejs.org/api/fs.html#fs_fspromises_readdir_path_options
|
547 | */
|
548 | readdir: Function;
|
549 | /**
|
550 | * - https://nodejs.org/api/fs.html#fs_fspromises_mkdir_path_options
|
551 | */
|
552 | mkdir: Function;
|
553 | /**
|
554 | * - https://nodejs.org/api/fs.html#fs_fspromises_rmdir_path
|
555 | */
|
556 | rmdir: Function;
|
557 | /**
|
558 | * - https://nodejs.org/api/fs.html#fs_fspromises_stat_path_options
|
559 | */
|
560 | stat: Function;
|
561 | /**
|
562 | * - https://nodejs.org/api/fs.html#fs_fspromises_lstat_path_options
|
563 | */
|
564 | lstat: Function;
|
565 | /**
|
566 | * - https://nodejs.org/api/fs.html#fs_fspromises_readlink_path_options
|
567 | */
|
568 | readlink?: Function;
|
569 | /**
|
570 | * - https://nodejs.org/api/fs.html#fs_fspromises_symlink_target_path_type
|
571 | */
|
572 | symlink?: Function;
|
573 | /**
|
574 | * - https://nodejs.org/api/fs.html#fs_fspromises_chmod_path_mode
|
575 | */
|
576 | chmod?: Function;
|
577 | };
|
578 | };
|
579 | export type FsClient = CallbackFsClient | PromiseFsClient;
|
580 | export type MessageCallback = (message: string) => void | Promise<void>;
|
581 | export type GitAuth = {
|
582 | username?: string;
|
583 | password?: string;
|
584 | headers?: {
|
585 | [x: string]: string;
|
586 | };
|
587 | /**
|
588 | * Tells git to throw a `UserCanceledError` (instead of an `HttpError`).
|
589 | */
|
590 | cancel?: boolean;
|
591 | };
|
592 | export type AuthCallback = (url: string, auth: GitAuth) => void | GitAuth | Promise<void | GitAuth>;
|
593 | export type AuthFailureCallback = (url: string, auth: GitAuth) => void | GitAuth | Promise<void | GitAuth>;
|
594 | export type AuthSuccessCallback = (url: string, auth: GitAuth) => void | Promise<void>;
|
595 | export type SignParams = {
|
596 | /**
|
597 | * - a plaintext message
|
598 | */
|
599 | payload: string;
|
600 | /**
|
601 | * - an 'ASCII armor' encoded PGP key (technically can actually contain _multiple_ keys)
|
602 | */
|
603 | secretKey: string;
|
604 | };
|
605 | export type SignCallback = (args: SignParams) => {
|
606 | signature: string;
|
607 | } | Promise<{
|
608 | signature: string;
|
609 | }>;
|
610 | export type RefUpdateStatus = {
|
611 | ok: boolean;
|
612 | error: string;
|
613 | };
|
614 | export type PushResult = {
|
615 | ok: boolean;
|
616 | error: string | null;
|
617 | refs: {
|
618 | [x: string]: RefUpdateStatus;
|
619 | };
|
620 | headers?: {
|
621 | [x: string]: string;
|
622 | };
|
623 | };
|
624 | export type HeadStatus = 0 | 1;
|
625 | export type WorkdirStatus = 0 | 1 | 2;
|
626 | export type StageStatus = 0 | 1 | 2 | 3;
|
627 | export type StatusRow = [string, 0 | 1, 0 | 1 | 2, 0 | 1 | 2 | 3];
|
628 | export type types = number;
|
629 | declare namespace index {
|
630 | export { Errors };
|
631 | export { STAGE };
|
632 | export { TREE };
|
633 | export { WORKDIR };
|
634 | export { add };
|
635 | export { addNote };
|
636 | export { addRemote };
|
637 | export { annotatedTag };
|
638 | export { branch };
|
639 | export { checkout };
|
640 | export { clone };
|
641 | export { commit };
|
642 | export { getConfig };
|
643 | export { getConfigAll };
|
644 | export { setConfig };
|
645 | export { currentBranch };
|
646 | export { deleteBranch };
|
647 | export { deleteRef };
|
648 | export { deleteRemote };
|
649 | export { deleteTag };
|
650 | export { expandOid };
|
651 | export { expandRef };
|
652 | export { fastForward };
|
653 | export { fetch };
|
654 | export { findMergeBase };
|
655 | export { findRoot };
|
656 | export { getRemoteInfo };
|
657 | export { getRemoteInfo2 };
|
658 | export { hashBlob };
|
659 | export { indexPack };
|
660 | export { init };
|
661 | export { isDescendent };
|
662 | export { listBranches };
|
663 | export { listFiles };
|
664 | export { listNotes };
|
665 | export { listRemotes };
|
666 | export { listServerRefs };
|
667 | export { listTags };
|
668 | export { log };
|
669 | export { merge };
|
670 | export { packObjects };
|
671 | export { pull };
|
672 | export { push };
|
673 | export { readBlob };
|
674 | export { readCommit };
|
675 | export { readNote };
|
676 | export { readObject };
|
677 | export { readTag };
|
678 | export { readTree };
|
679 | export { remove };
|
680 | export { removeNote };
|
681 | export { renameBranch };
|
682 | export { resetIndex };
|
683 | export { resolveRef };
|
684 | export { status };
|
685 | export { statusMatrix };
|
686 | export { tag };
|
687 | export { version };
|
688 | export { walk };
|
689 | export { writeBlob };
|
690 | export { writeCommit };
|
691 | export { writeObject };
|
692 | export { writeRef };
|
693 | export { writeTag };
|
694 | export { writeTree };
|
695 | }
|
696 | export var Errors: Readonly<{
|
697 | __proto__: null;
|
698 | AlreadyExistsError: typeof AlreadyExistsError;
|
699 | AmbiguousError: typeof AmbiguousError;
|
700 | CheckoutConflictError: typeof CheckoutConflictError;
|
701 | CommitNotFetchedError: typeof CommitNotFetchedError;
|
702 | EmptyServerResponseError: typeof EmptyServerResponseError;
|
703 | FastForwardError: typeof FastForwardError;
|
704 | GitPushError: typeof GitPushError;
|
705 | HttpError: typeof HttpError;
|
706 | InternalError: typeof InternalError;
|
707 | InvalidFilepathError: typeof InvalidFilepathError;
|
708 | InvalidOidError: typeof InvalidOidError;
|
709 | InvalidRefNameError: typeof InvalidRefNameError;
|
710 | MaxDepthError: typeof MaxDepthError;
|
711 | MergeNotSupportedError: typeof MergeNotSupportedError;
|
712 | MissingNameError: typeof MissingNameError;
|
713 | MissingParameterError: typeof MissingParameterError;
|
714 | NoRefspecError: typeof NoRefspecError;
|
715 | NotFoundError: typeof NotFoundError;
|
716 | ObjectTypeError: typeof ObjectTypeError;
|
717 | ParseError: typeof ParseError;
|
718 | PushRejectedError: typeof PushRejectedError;
|
719 | RemoteCapabilityError: typeof RemoteCapabilityError;
|
720 | SmartHttpError: typeof SmartHttpError;
|
721 | UnknownTransportError: typeof UnknownTransportError;
|
722 | UnsafeFilepathError: typeof UnsafeFilepathError;
|
723 | UrlParseError: typeof UrlParseError;
|
724 | UserCanceledError: typeof UserCanceledError;
|
725 | }>;
|
726 | /**
|
727 | * @returns {Walker}
|
728 | */
|
729 | export function STAGE(): Walker;
|
730 | /**
|
731 | * @param {object} args
|
732 | * @param {string} [args.ref='HEAD']
|
733 | * @returns {Walker}
|
734 | */
|
735 | export function TREE({ ref }: {
|
736 | ref?: string;
|
737 | }): Walker;
|
738 | /**
|
739 | * @returns {Walker}
|
740 | */
|
741 | export function WORKDIR(): Walker;
|
742 | /**
|
743 | * Add a file to the git index (aka staging area)
|
744 | *
|
745 | * @param {object} args
|
746 | * @param {FsClient} args.fs - a file system implementation
|
747 | * @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
|
748 | * @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
749 | * @param {string} args.filepath - The path to the file to add to the index
|
750 | * @param {object} [args.cache] - a [cache](cache.md) object
|
751 | *
|
752 | * @returns {Promise<void>} Resolves successfully once the git index has been updated
|
753 | *
|
754 | * @example
|
755 | * await fs.promises.writeFile('/tutorial/README.md', `# TEST`)
|
756 | * await git.add({ fs, dir: '/tutorial', filepath: 'README.md' })
|
757 | * console.log('done')
|
758 | *
|
759 | */
|
760 | export function add({ fs: _fs, dir, gitdir, filepath, cache, }: {
|
761 | fs: CallbackFsClient | PromiseFsClient;
|
762 | dir: string;
|
763 | gitdir?: string;
|
764 | filepath: string;
|
765 | cache?: any;
|
766 | }): Promise<void>;
|
767 | /**
|
768 | * Add or update an object note
|
769 | *
|
770 | * @param {object} args
|
771 | * @param {FsClient} args.fs - a file system implementation
|
772 | * @param {SignCallback} [args.onSign] - a PGP signing implementation
|
773 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
774 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
775 | * @param {string} [args.ref] - The notes ref to look under
|
776 | * @param {string} args.oid - The SHA-1 object id of the object to add the note to.
|
777 | * @param {string|Uint8Array} args.note - The note to add
|
778 | * @param {boolean} [args.force] - Over-write note if it already exists.
|
779 | * @param {Object} [args.author] - The details about the author.
|
780 | * @param {string} [args.author.name] - Default is `user.name` config.
|
781 | * @param {string} [args.author.email] - Default is `user.email` config.
|
782 | * @param {number} [args.author.timestamp=Math.floor(Date.now()/1000)] - Set the author timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
783 | * @param {number} [args.author.timezoneOffset] - Set the author timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
784 | * @param {Object} [args.committer = author] - The details about the note committer, in the same format as the author parameter. If not specified, the author details are used.
|
785 | * @param {string} [args.committer.name] - Default is `user.name` config.
|
786 | * @param {string} [args.committer.email] - Default is `user.email` config.
|
787 | * @param {number} [args.committer.timestamp=Math.floor(Date.now()/1000)] - Set the committer timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
788 | * @param {number} [args.committer.timezoneOffset] - Set the committer timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
789 | * @param {string} [args.signingKey] - Sign the note commit using this private PGP key.
|
790 | * @param {object} [args.cache] - a [cache](cache.md) object
|
791 | *
|
792 | * @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the commit object for the added note.
|
793 | */
|
794 | export function addNote({ fs: _fs, onSign, dir, gitdir, ref, oid, note, force, author: _author, committer: _committer, signingKey, cache, }: {
|
795 | fs: CallbackFsClient | PromiseFsClient;
|
796 | onSign?: SignCallback;
|
797 | dir?: string;
|
798 | gitdir?: string;
|
799 | ref?: string;
|
800 | oid: string;
|
801 | note: string | Uint8Array;
|
802 | force?: boolean;
|
803 | author?: {
|
804 | name?: string;
|
805 | email?: string;
|
806 | timestamp?: number;
|
807 | timezoneOffset?: number;
|
808 | };
|
809 | committer?: {
|
810 | name?: string;
|
811 | email?: string;
|
812 | timestamp?: number;
|
813 | timezoneOffset?: number;
|
814 | };
|
815 | signingKey?: string;
|
816 | cache?: any;
|
817 | }): Promise<string>;
|
818 | /**
|
819 | * Add or update a remote
|
820 | *
|
821 | * @param {object} args
|
822 | * @param {FsClient} args.fs - a file system implementation
|
823 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
824 | * @param {string} [args.gitdir] - [required] The [git directory](dir-vs-gitdir.md) path
|
825 | * @param {string} args.remote - The name of the remote
|
826 | * @param {string} args.url - The URL of the remote
|
827 | * @param {boolean} [args.force = false] - Instead of throwing an error if a remote named `remote` already exists, overwrite the existing remote.
|
828 | *
|
829 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
830 | *
|
831 | * @example
|
832 | * await git.addRemote({
|
833 | * fs,
|
834 | * dir: '/tutorial',
|
835 | * remote: 'upstream',
|
836 | * url: 'https://github.com/isomorphic-git/isomorphic-git'
|
837 | * })
|
838 | * console.log('done')
|
839 | *
|
840 | */
|
841 | export function addRemote({ fs, dir, gitdir, remote, url, force, }: {
|
842 | fs: CallbackFsClient | PromiseFsClient;
|
843 | dir?: string;
|
844 | gitdir?: string;
|
845 | remote: string;
|
846 | url: string;
|
847 | force?: boolean;
|
848 | }): Promise<void>;
|
849 | /**
|
850 | * Create an annotated tag.
|
851 | *
|
852 | * @param {object} args
|
853 | * @param {FsClient} args.fs - a file system implementation
|
854 | * @param {SignCallback} [args.onSign] - a PGP signing implementation
|
855 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
856 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
857 | * @param {string} args.ref - What to name the tag
|
858 | * @param {string} [args.message = ref] - The tag message to use.
|
859 | * @param {string} [args.object = 'HEAD'] - The SHA-1 object id the tag points to. (Will resolve to a SHA-1 object id if value is a ref.) By default, the commit object which is referred by the current `HEAD` is used.
|
860 | * @param {object} [args.tagger] - The details about the tagger.
|
861 | * @param {string} [args.tagger.name] - Default is `user.name` config.
|
862 | * @param {string} [args.tagger.email] - Default is `user.email` config.
|
863 | * @param {number} [args.tagger.timestamp=Math.floor(Date.now()/1000)] - Set the tagger timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
864 | * @param {number} [args.tagger.timezoneOffset] - Set the tagger timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
865 | * @param {string} [args.gpgsig] - The gpgsig attatched to the tag object. (Mutually exclusive with the `signingKey` option.)
|
866 | * @param {string} [args.signingKey] - Sign the tag object using this private PGP key. (Mutually exclusive with the `gpgsig` option.)
|
867 | * @param {boolean} [args.force = false] - Instead of throwing an error if a tag named `ref` already exists, overwrite the existing tag. Note that this option does not modify the original tag object itself.
|
868 | * @param {object} [args.cache] - a [cache](cache.md) object
|
869 | *
|
870 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
871 | *
|
872 | * @example
|
873 | * await git.annotatedTag({
|
874 | * fs,
|
875 | * dir: '/tutorial',
|
876 | * ref: 'test-tag',
|
877 | * message: 'This commit is awesome',
|
878 | * tagger: {
|
879 | * name: 'Mr. Test',
|
880 | * email: 'mrtest@example.com'
|
881 | * }
|
882 | * })
|
883 | * console.log('done')
|
884 | *
|
885 | */
|
886 | export function annotatedTag({ fs: _fs, onSign, dir, gitdir, ref, tagger: _tagger, message, gpgsig, object, signingKey, force, cache, }: {
|
887 | fs: CallbackFsClient | PromiseFsClient;
|
888 | onSign?: SignCallback;
|
889 | dir?: string;
|
890 | gitdir?: string;
|
891 | ref: string;
|
892 | message?: string;
|
893 | object?: string;
|
894 | tagger?: {
|
895 | name?: string;
|
896 | email?: string;
|
897 | timestamp?: number;
|
898 | timezoneOffset?: number;
|
899 | };
|
900 | gpgsig?: string;
|
901 | signingKey?: string;
|
902 | force?: boolean;
|
903 | cache?: any;
|
904 | }): Promise<void>;
|
905 | /**
|
906 | * Create a branch
|
907 | *
|
908 | * @param {object} args
|
909 | * @param {FsClient} args.fs - a file system implementation
|
910 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
911 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
912 | * @param {string} args.ref - What to name the branch
|
913 | * @param {boolean} [args.checkout = false] - Update `HEAD` to point at the newly created branch
|
914 | *
|
915 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
916 | *
|
917 | * @example
|
918 | * await git.branch({ fs, dir: '/tutorial', ref: 'develop' })
|
919 | * console.log('done')
|
920 | *
|
921 | */
|
922 | export function branch({ fs, dir, gitdir, ref, checkout, }: {
|
923 | fs: CallbackFsClient | PromiseFsClient;
|
924 | dir?: string;
|
925 | gitdir?: string;
|
926 | ref: string;
|
927 | checkout?: boolean;
|
928 | }): Promise<void>;
|
929 | /**
|
930 | * Checkout a branch
|
931 | *
|
932 | * If the branch already exists it will check out that branch. Otherwise, it will create a new remote tracking branch set to track the remote branch of that name.
|
933 | *
|
934 | * @param {object} args
|
935 | * @param {FsClient} args.fs - a file system implementation
|
936 | * @param {ProgressCallback} [args.onProgress] - optional progress event callback
|
937 | * @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
|
938 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
939 | * @param {string} [args.ref = 'HEAD'] - Source to checkout files from
|
940 | * @param {string[]} [args.filepaths] - Limit the checkout to the given files and directories
|
941 | * @param {string} [args.remote = 'origin'] - Which remote repository to use
|
942 | * @param {boolean} [args.noCheckout = false] - If true, will update HEAD but won't update the working directory
|
943 | * @param {boolean} [args.noUpdateHead] - If true, will update the working directory but won't update HEAD. Defaults to `false` when `ref` is provided, and `true` if `ref` is not provided.
|
944 | * @param {boolean} [args.dryRun = false] - If true, simulates a checkout so you can test whether it would succeed.
|
945 | * @param {boolean} [args.force = false] - If true, conflicts will be ignored and files will be overwritten regardless of local changes.
|
946 | * @param {object} [args.cache] - a [cache](cache.md) object
|
947 | *
|
948 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
949 | *
|
950 | * @example
|
951 | * // switch to the main branch
|
952 | * await git.checkout({
|
953 | * fs,
|
954 | * dir: '/tutorial',
|
955 | * ref: 'main'
|
956 | * })
|
957 | * console.log('done')
|
958 | *
|
959 | * @example
|
960 | * // restore the 'docs' and 'src/docs' folders to the way they were, overwriting any changes
|
961 | * await git.checkout({
|
962 | * fs,
|
963 | * dir: '/tutorial',
|
964 | * force: true,
|
965 | * filepaths: ['docs', 'src/docs']
|
966 | * })
|
967 | * console.log('done')
|
968 | *
|
969 | * @example
|
970 | * // restore the 'docs' and 'src/docs' folders to the way they are in the 'develop' branch, overwriting any changes
|
971 | * await git.checkout({
|
972 | * fs,
|
973 | * dir: '/tutorial',
|
974 | * ref: 'develop',
|
975 | * noUpdateHead: true,
|
976 | * force: true,
|
977 | * filepaths: ['docs', 'src/docs']
|
978 | * })
|
979 | * console.log('done')
|
980 | */
|
981 | export function checkout({ fs, onProgress, dir, gitdir, remote, ref: _ref, filepaths, noCheckout, noUpdateHead, dryRun, force, cache, }: {
|
982 | fs: CallbackFsClient | PromiseFsClient;
|
983 | onProgress?: ProgressCallback;
|
984 | dir: string;
|
985 | gitdir?: string;
|
986 | ref?: string;
|
987 | filepaths?: string[];
|
988 | remote?: string;
|
989 | noCheckout?: boolean;
|
990 | noUpdateHead?: boolean;
|
991 | dryRun?: boolean;
|
992 | force?: boolean;
|
993 | cache?: any;
|
994 | }): Promise<void>;
|
995 | /**
|
996 | * Clone a repository
|
997 | *
|
998 | * @param {object} args
|
999 | * @param {FsClient} args.fs - a file system implementation
|
1000 | * @param {HttpClient} args.http - an HTTP client
|
1001 | * @param {ProgressCallback} [args.onProgress] - optional progress event callback
|
1002 | * @param {MessageCallback} [args.onMessage] - optional message event callback
|
1003 | * @param {AuthCallback} [args.onAuth] - optional auth fill callback
|
1004 | * @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
|
1005 | * @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
|
1006 | * @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
|
1007 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1008 | * @param {string} args.url - The URL of the remote repository
|
1009 | * @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Value is stored in the git config file for that repo.
|
1010 | * @param {string} [args.ref] - Which branch to checkout. By default this is the designated "main branch" of the repository.
|
1011 | * @param {boolean} [args.singleBranch = false] - Instead of the default behavior of fetching all the branches, only fetch a single branch.
|
1012 | * @param {boolean} [args.noCheckout = false] - If true, clone will only fetch the repo, not check out a branch. Skipping checkout can save a lot of time normally spent writing files to disk.
|
1013 | * @param {boolean} [args.noTags = false] - By default clone will fetch all tags. `noTags` disables that behavior.
|
1014 | * @param {string} [args.remote = 'origin'] - What to name the remote that is created.
|
1015 | * @param {number} [args.depth] - Integer. Determines how much of the git repository's history to retrieve
|
1016 | * @param {Date} [args.since] - Only fetch commits created after the given date. Mutually exclusive with `depth`.
|
1017 | * @param {string[]} [args.exclude = []] - A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs.
|
1018 | * @param {boolean} [args.relative = false] - Changes the meaning of `depth` to be measured from the current shallow depth rather than from the branch tip.
|
1019 | * @param {Object<string, string>} [args.headers = {}] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
|
1020 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1021 | *
|
1022 | * @returns {Promise<void>} Resolves successfully when clone completes
|
1023 | *
|
1024 | * @example
|
1025 | * await git.clone({
|
1026 | * fs,
|
1027 | * http,
|
1028 | * dir: '/tutorial',
|
1029 | * corsProxy: 'https://cors.isomorphic-git.org',
|
1030 | * url: 'https://github.com/isomorphic-git/isomorphic-git',
|
1031 | * singleBranch: true,
|
1032 | * depth: 1
|
1033 | * })
|
1034 | * console.log('done')
|
1035 | *
|
1036 | */
|
1037 | export function clone({ fs, http, onProgress, onMessage, onAuth, onAuthSuccess, onAuthFailure, dir, gitdir, url, corsProxy, ref, remote, depth, since, exclude, relative, singleBranch, noCheckout, noTags, headers, cache, }: {
|
1038 | fs: CallbackFsClient | PromiseFsClient;
|
1039 | http: HttpClient;
|
1040 | onProgress?: ProgressCallback;
|
1041 | onMessage?: MessageCallback;
|
1042 | onAuth?: AuthCallback;
|
1043 | onAuthFailure?: AuthFailureCallback;
|
1044 | onAuthSuccess?: AuthSuccessCallback;
|
1045 | dir: string;
|
1046 | gitdir?: string;
|
1047 | url: string;
|
1048 | corsProxy?: string;
|
1049 | ref?: string;
|
1050 | singleBranch?: boolean;
|
1051 | noCheckout?: boolean;
|
1052 | noTags?: boolean;
|
1053 | remote?: string;
|
1054 | depth?: number;
|
1055 | since?: Date;
|
1056 | exclude?: string[];
|
1057 | relative?: boolean;
|
1058 | headers?: {
|
1059 | [x: string]: string;
|
1060 | };
|
1061 | cache?: any;
|
1062 | }): Promise<void>;
|
1063 | /**
|
1064 | * Create a new commit
|
1065 | *
|
1066 | * @param {Object} args
|
1067 | * @param {FsClient} args.fs - a file system implementation
|
1068 | * @param {SignCallback} [args.onSign] - a PGP signing implementation
|
1069 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1070 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1071 | * @param {string} args.message - The commit message to use.
|
1072 | * @param {Object} [args.author] - The details about the author.
|
1073 | * @param {string} [args.author.name] - Default is `user.name` config.
|
1074 | * @param {string} [args.author.email] - Default is `user.email` config.
|
1075 | * @param {number} [args.author.timestamp=Math.floor(Date.now()/1000)] - Set the author timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
1076 | * @param {number} [args.author.timezoneOffset] - Set the author timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
1077 | * @param {Object} [args.committer = author] - The details about the commit committer, in the same format as the author parameter. If not specified, the author details are used.
|
1078 | * @param {string} [args.committer.name] - Default is `user.name` config.
|
1079 | * @param {string} [args.committer.email] - Default is `user.email` config.
|
1080 | * @param {number} [args.committer.timestamp=Math.floor(Date.now()/1000)] - Set the committer timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
1081 | * @param {number} [args.committer.timezoneOffset] - Set the committer timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
1082 | * @param {string} [args.signingKey] - Sign the tag object using this private PGP key.
|
1083 | * @param {boolean} [args.dryRun = false] - If true, simulates making a commit so you can test whether it would succeed. Implies `noUpdateBranch`.
|
1084 | * @param {boolean} [args.noUpdateBranch = false] - If true, does not update the branch pointer after creating the commit.
|
1085 | * @param {string} [args.ref] - The fully expanded name of the branch to commit to. Default is the current branch pointed to by HEAD. (TODO: fix it so it can expand branch names without throwing if the branch doesn't exist yet.)
|
1086 | * @param {string[]} [args.parent] - The SHA-1 object ids of the commits to use as parents. If not specified, the commit pointed to by `ref` is used.
|
1087 | * @param {string} [args.tree] - The SHA-1 object id of the tree to use. If not specified, a new tree object is created from the current git index.
|
1088 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1089 | *
|
1090 | * @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly created commit.
|
1091 | *
|
1092 | * @example
|
1093 | * let sha = await git.commit({
|
1094 | * fs,
|
1095 | * dir: '/tutorial',
|
1096 | * author: {
|
1097 | * name: 'Mr. Test',
|
1098 | * email: 'mrtest@example.com',
|
1099 | * },
|
1100 | * message: 'Added the a.txt file'
|
1101 | * })
|
1102 | * console.log(sha)
|
1103 | *
|
1104 | */
|
1105 | export function commit({ fs: _fs, onSign, dir, gitdir, message, author: _author, committer: _committer, signingKey, dryRun, noUpdateBranch, ref, parent, tree, cache, }: {
|
1106 | fs: CallbackFsClient | PromiseFsClient;
|
1107 | onSign?: SignCallback;
|
1108 | dir?: string;
|
1109 | gitdir?: string;
|
1110 | message: string;
|
1111 | author?: {
|
1112 | name?: string;
|
1113 | email?: string;
|
1114 | timestamp?: number;
|
1115 | timezoneOffset?: number;
|
1116 | };
|
1117 | committer?: {
|
1118 | name?: string;
|
1119 | email?: string;
|
1120 | timestamp?: number;
|
1121 | timezoneOffset?: number;
|
1122 | };
|
1123 | signingKey?: string;
|
1124 | dryRun?: boolean;
|
1125 | noUpdateBranch?: boolean;
|
1126 | ref?: string;
|
1127 | parent?: string[];
|
1128 | tree?: string;
|
1129 | cache?: any;
|
1130 | }): Promise<string>;
|
1131 | /**
|
1132 | * Get the name of the branch currently pointed to by .git/HEAD
|
1133 | *
|
1134 | * @param {Object} args
|
1135 | * @param {FsClient} args.fs - a file system implementation
|
1136 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1137 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1138 | * @param {boolean} [args.fullname = false] - Return the full path (e.g. "refs/heads/main") instead of the abbreviated form.
|
1139 | * @param {boolean} [args.test = false] - If the current branch doesn't actually exist (such as right after git init) then return `undefined`.
|
1140 | *
|
1141 | * @returns {Promise<string|void>} The name of the current branch or undefined if the HEAD is detached.
|
1142 | *
|
1143 | * @example
|
1144 | * // Get the current branch name
|
1145 | * let branch = await git.currentBranch({
|
1146 | * fs,
|
1147 | * dir: '/tutorial',
|
1148 | * fullname: false
|
1149 | * })
|
1150 | * console.log(branch)
|
1151 | *
|
1152 | */
|
1153 | export function currentBranch({ fs, dir, gitdir, fullname, test, }: {
|
1154 | fs: CallbackFsClient | PromiseFsClient;
|
1155 | dir?: string;
|
1156 | gitdir?: string;
|
1157 | fullname?: boolean;
|
1158 | test?: boolean;
|
1159 | }): Promise<string | void>;
|
1160 | /**
|
1161 | * Delete a local branch
|
1162 | *
|
1163 | * > Note: This only deletes loose branches - it should be fixed in the future to delete packed branches as well.
|
1164 | *
|
1165 | * @param {Object} args
|
1166 | * @param {FsClient} args.fs - a file system implementation
|
1167 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1168 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1169 | * @param {string} args.ref - The branch to delete
|
1170 | *
|
1171 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
1172 | *
|
1173 | * @example
|
1174 | * await git.deleteBranch({ fs, dir: '/tutorial', ref: 'local-branch' })
|
1175 | * console.log('done')
|
1176 | *
|
1177 | */
|
1178 | export function deleteBranch({ fs, dir, gitdir, ref, }: {
|
1179 | fs: CallbackFsClient | PromiseFsClient;
|
1180 | dir?: string;
|
1181 | gitdir?: string;
|
1182 | ref: string;
|
1183 | }): Promise<void>;
|
1184 | /**
|
1185 | * Delete a local ref
|
1186 | *
|
1187 | * @param {Object} args
|
1188 | * @param {FsClient} args.fs - a file system implementation
|
1189 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1190 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1191 | * @param {string} args.ref - The ref to delete
|
1192 | *
|
1193 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
1194 | *
|
1195 | * @example
|
1196 | * await git.deleteRef({ fs, dir: '/tutorial', ref: 'refs/tags/test-tag' })
|
1197 | * console.log('done')
|
1198 | *
|
1199 | */
|
1200 | export function deleteRef({ fs, dir, gitdir, ref }: {
|
1201 | fs: CallbackFsClient | PromiseFsClient;
|
1202 | dir?: string;
|
1203 | gitdir?: string;
|
1204 | ref: string;
|
1205 | }): Promise<void>;
|
1206 | /**
|
1207 | * Removes the local config entry for a given remote
|
1208 | *
|
1209 | * @param {Object} args
|
1210 | * @param {FsClient} args.fs - a file system implementation
|
1211 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1212 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1213 | * @param {string} args.remote - The name of the remote to delete
|
1214 | *
|
1215 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
1216 | *
|
1217 | * @example
|
1218 | * await git.deleteRemote({ fs, dir: '/tutorial', remote: 'upstream' })
|
1219 | * console.log('done')
|
1220 | *
|
1221 | */
|
1222 | export function deleteRemote({ fs, dir, gitdir, remote, }: {
|
1223 | fs: CallbackFsClient | PromiseFsClient;
|
1224 | dir?: string;
|
1225 | gitdir?: string;
|
1226 | remote: string;
|
1227 | }): Promise<void>;
|
1228 | /**
|
1229 | * Delete a local tag ref
|
1230 | *
|
1231 | * @param {Object} args
|
1232 | * @param {FsClient} args.fs - a file system implementation
|
1233 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1234 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1235 | * @param {string} args.ref - The tag to delete
|
1236 | *
|
1237 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
1238 | *
|
1239 | * @example
|
1240 | * await git.deleteTag({ fs, dir: '/tutorial', ref: 'test-tag' })
|
1241 | * console.log('done')
|
1242 | *
|
1243 | */
|
1244 | export function deleteTag({ fs, dir, gitdir, ref }: {
|
1245 | fs: CallbackFsClient | PromiseFsClient;
|
1246 | dir?: string;
|
1247 | gitdir?: string;
|
1248 | ref: string;
|
1249 | }): Promise<void>;
|
1250 | /**
|
1251 | * Expand and resolve a short oid into a full oid
|
1252 | *
|
1253 | * @param {Object} args
|
1254 | * @param {FsClient} args.fs - a file system implementation
|
1255 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1256 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1257 | * @param {string} args.oid - The shortened oid prefix to expand (like "0414d2a")
|
1258 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1259 | *
|
1260 | * @returns {Promise<string>} Resolves successfully with the full oid (like "0414d2a286d7bbc7a4a326a61c1f9f888a8ab87f")
|
1261 | *
|
1262 | * @example
|
1263 | * let oid = await git.expandOid({ fs, dir: '/tutorial', oid: '0414d2a'})
|
1264 | * console.log(oid)
|
1265 | *
|
1266 | */
|
1267 | export function expandOid({ fs, dir, gitdir, oid, cache, }: {
|
1268 | fs: CallbackFsClient | PromiseFsClient;
|
1269 | dir?: string;
|
1270 | gitdir?: string;
|
1271 | oid: string;
|
1272 | cache?: any;
|
1273 | }): Promise<string>;
|
1274 | /**
|
1275 | * Expand an abbreviated ref to its full name
|
1276 | *
|
1277 | * @param {Object} args
|
1278 | * @param {FsClient} args.fs - a file system implementation
|
1279 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1280 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1281 | * @param {string} args.ref - The ref to expand (like "v1.0.0")
|
1282 | *
|
1283 | * @returns {Promise<string>} Resolves successfully with a full ref name ("refs/tags/v1.0.0")
|
1284 | *
|
1285 | * @example
|
1286 | * let fullRef = await git.expandRef({ fs, dir: '/tutorial', ref: 'main'})
|
1287 | * console.log(fullRef)
|
1288 | *
|
1289 | */
|
1290 | export function expandRef({ fs, dir, gitdir, ref }: {
|
1291 | fs: CallbackFsClient | PromiseFsClient;
|
1292 | dir?: string;
|
1293 | gitdir?: string;
|
1294 | ref: string;
|
1295 | }): Promise<string>;
|
1296 | /**
|
1297 | * Like `pull`, but hard-coded with `fastForward: true` so there is no need for an `author` parameter.
|
1298 | *
|
1299 | * @param {object} args
|
1300 | * @param {FsClient} args.fs - a file system client
|
1301 | * @param {HttpClient} args.http - an HTTP client
|
1302 | * @param {ProgressCallback} [args.onProgress] - optional progress event callback
|
1303 | * @param {MessageCallback} [args.onMessage] - optional message event callback
|
1304 | * @param {AuthCallback} [args.onAuth] - optional auth fill callback
|
1305 | * @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
|
1306 | * @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
|
1307 | * @param {string} args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1308 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1309 | * @param {string} [args.ref] - Which branch to merge into. By default this is the currently checked out branch.
|
1310 | * @param {string} [args.url] - (Added in 1.1.0) The URL of the remote repository. The default is the value set in the git config for that remote.
|
1311 | * @param {string} [args.remote] - (Added in 1.1.0) If URL is not specified, determines which remote to use.
|
1312 | * @param {string} [args.remoteRef] - (Added in 1.1.0) The name of the branch on the remote to fetch. By default this is the configured remote tracking branch.
|
1313 | * @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
|
1314 | * @param {boolean} [args.singleBranch = false] - Instead of the default behavior of fetching all the branches, only fetch a single branch.
|
1315 | * @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
|
1316 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1317 | *
|
1318 | * @returns {Promise<void>} Resolves successfully when pull operation completes
|
1319 | *
|
1320 | * @example
|
1321 | * await git.fastForward({
|
1322 | * fs,
|
1323 | * http,
|
1324 | * dir: '/tutorial',
|
1325 | * ref: 'main',
|
1326 | * singleBranch: true
|
1327 | * })
|
1328 | * console.log('done')
|
1329 | *
|
1330 | */
|
1331 | export function fastForward({ fs, http, onProgress, onMessage, onAuth, onAuthSuccess, onAuthFailure, dir, gitdir, ref, url, remote, remoteRef, corsProxy, singleBranch, headers, cache, }: {
|
1332 | fs: CallbackFsClient | PromiseFsClient;
|
1333 | http: HttpClient;
|
1334 | onProgress?: ProgressCallback;
|
1335 | onMessage?: MessageCallback;
|
1336 | onAuth?: AuthCallback;
|
1337 | onAuthFailure?: AuthFailureCallback;
|
1338 | onAuthSuccess?: AuthSuccessCallback;
|
1339 | dir: string;
|
1340 | gitdir?: string;
|
1341 | ref?: string;
|
1342 | url?: string;
|
1343 | remote?: string;
|
1344 | remoteRef?: string;
|
1345 | corsProxy?: string;
|
1346 | singleBranch?: boolean;
|
1347 | headers?: {
|
1348 | [x: string]: string;
|
1349 | };
|
1350 | cache?: any;
|
1351 | }): Promise<void>;
|
1352 | /**
|
1353 | *
|
1354 | * @typedef {object} FetchResult - The object returned has the following schema:
|
1355 | * @property {string | null} defaultBranch - The branch that is cloned if no branch is specified
|
1356 | * @property {string | null} fetchHead - The SHA-1 object id of the fetched head commit
|
1357 | * @property {string | null} fetchHeadDescription - a textual description of the branch that was fetched
|
1358 | * @property {Object<string, string>} [headers] - The HTTP response headers returned by the git server
|
1359 | * @property {string[]} [pruned] - A list of branches that were pruned, if you provided the `prune` parameter
|
1360 | *
|
1361 | */
|
1362 | /**
|
1363 | * Fetch commits from a remote repository
|
1364 | *
|
1365 | * @param {object} args
|
1366 | * @param {FsClient} args.fs - a file system client
|
1367 | * @param {HttpClient} args.http - an HTTP client
|
1368 | * @param {ProgressCallback} [args.onProgress] - optional progress event callback
|
1369 | * @param {MessageCallback} [args.onMessage] - optional message event callback
|
1370 | * @param {AuthCallback} [args.onAuth] - optional auth fill callback
|
1371 | * @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
|
1372 | * @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
|
1373 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1374 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1375 | * @param {string} [args.url] - The URL of the remote repository. The default is the value set in the git config for that remote.
|
1376 | * @param {string} [args.remote] - If URL is not specified, determines which remote to use.
|
1377 | * @param {boolean} [args.singleBranch = false] - Instead of the default behavior of fetching all the branches, only fetch a single branch.
|
1378 | * @param {string} [args.ref] - Which branch to fetch if `singleBranch` is true. By default this is the current branch or the remote's default branch.
|
1379 | * @param {string} [args.remoteRef] - The name of the branch on the remote to fetch if `singleBranch` is true. By default this is the configured remote tracking branch.
|
1380 | * @param {boolean} [args.tags = false] - Also fetch tags
|
1381 | * @param {number} [args.depth] - Integer. Determines how much of the git repository's history to retrieve
|
1382 | * @param {boolean} [args.relative = false] - Changes the meaning of `depth` to be measured from the current shallow depth rather than from the branch tip.
|
1383 | * @param {Date} [args.since] - Only fetch commits created after the given date. Mutually exclusive with `depth`.
|
1384 | * @param {string[]} [args.exclude = []] - A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs.
|
1385 | * @param {boolean} [args.prune] - Delete local remote-tracking branches that are not present on the remote
|
1386 | * @param {boolean} [args.pruneTags] - Prune local tags that don’t exist on the remote, and force-update those tags that differ
|
1387 | * @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
|
1388 | * @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
|
1389 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1390 | *
|
1391 | * @returns {Promise<FetchResult>} Resolves successfully when fetch completes
|
1392 | * @see FetchResult
|
1393 | *
|
1394 | * @example
|
1395 | * let result = await git.fetch({
|
1396 | * fs,
|
1397 | * http,
|
1398 | * dir: '/tutorial',
|
1399 | * corsProxy: 'https://cors.isomorphic-git.org',
|
1400 | * url: 'https://github.com/isomorphic-git/isomorphic-git',
|
1401 | * ref: 'main',
|
1402 | * depth: 1,
|
1403 | * singleBranch: true,
|
1404 | * tags: false
|
1405 | * })
|
1406 | * console.log(result)
|
1407 | *
|
1408 | */
|
1409 | export function fetch({ fs, http, onProgress, onMessage, onAuth, onAuthSuccess, onAuthFailure, dir, gitdir, ref, remote, remoteRef, url, corsProxy, depth, since, exclude, relative, tags, singleBranch, headers, prune, pruneTags, cache, }: {
|
1410 | fs: CallbackFsClient | PromiseFsClient;
|
1411 | http: HttpClient;
|
1412 | onProgress?: ProgressCallback;
|
1413 | onMessage?: MessageCallback;
|
1414 | onAuth?: AuthCallback;
|
1415 | onAuthFailure?: AuthFailureCallback;
|
1416 | onAuthSuccess?: AuthSuccessCallback;
|
1417 | dir?: string;
|
1418 | gitdir?: string;
|
1419 | url?: string;
|
1420 | remote?: string;
|
1421 | singleBranch?: boolean;
|
1422 | ref?: string;
|
1423 | remoteRef?: string;
|
1424 | tags?: boolean;
|
1425 | depth?: number;
|
1426 | relative?: boolean;
|
1427 | since?: Date;
|
1428 | exclude?: string[];
|
1429 | prune?: boolean;
|
1430 | pruneTags?: boolean;
|
1431 | corsProxy?: string;
|
1432 | headers?: {
|
1433 | [x: string]: string;
|
1434 | };
|
1435 | cache?: any;
|
1436 | }): Promise<FetchResult>;
|
1437 | /**
|
1438 | * Find the merge base for a set of commits
|
1439 | *
|
1440 | * @param {object} args
|
1441 | * @param {FsClient} args.fs - a file system client
|
1442 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1443 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1444 | * @param {string[]} args.oids - Which commits
|
1445 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1446 | *
|
1447 | */
|
1448 | export function findMergeBase({ fs, dir, gitdir, oids, cache, }: {
|
1449 | fs: CallbackFsClient | PromiseFsClient;
|
1450 | dir?: string;
|
1451 | gitdir?: string;
|
1452 | oids: string[];
|
1453 | cache?: any;
|
1454 | }): Promise<any[]>;
|
1455 | /**
|
1456 | * Find the root git directory
|
1457 | *
|
1458 | * Starting at `filepath`, walks upward until it finds a directory that contains a subdirectory called '.git'.
|
1459 | *
|
1460 | * @param {Object} args
|
1461 | * @param {FsClient} args.fs - a file system client
|
1462 | * @param {string} args.filepath - The file directory to start searching in.
|
1463 | *
|
1464 | * @returns {Promise<string>} Resolves successfully with a root git directory path
|
1465 | * @throws {NotFoundError}
|
1466 | *
|
1467 | * @example
|
1468 | * let gitroot = await git.findRoot({
|
1469 | * fs,
|
1470 | * filepath: '/tutorial/src/utils'
|
1471 | * })
|
1472 | * console.log(gitroot)
|
1473 | *
|
1474 | */
|
1475 | export function findRoot({ fs, filepath }: {
|
1476 | fs: CallbackFsClient | PromiseFsClient;
|
1477 | filepath: string;
|
1478 | }): Promise<string>;
|
1479 | /**
|
1480 | * Read an entry from the git config files.
|
1481 | *
|
1482 | * *Caveats:*
|
1483 | * - Currently only the local `$GIT_DIR/config` file can be read or written. However support for the global `~/.gitconfig` and system `$(prefix)/etc/gitconfig` will be added in the future.
|
1484 | * - The current parser does not support the more exotic features of the git-config file format such as `[include]` and `[includeIf]`.
|
1485 | *
|
1486 | * @param {Object} args
|
1487 | * @param {FsClient} args.fs - a file system implementation
|
1488 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1489 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1490 | * @param {string} args.path - The key of the git config entry
|
1491 | *
|
1492 | * @returns {Promise<any>} Resolves with the config value
|
1493 | *
|
1494 | * @example
|
1495 | * // Read config value
|
1496 | * let value = await git.getConfig({
|
1497 | * fs,
|
1498 | * dir: '/tutorial',
|
1499 | * path: 'remote.origin.url'
|
1500 | * })
|
1501 | * console.log(value)
|
1502 | *
|
1503 | */
|
1504 | export function getConfig({ fs, dir, gitdir, path }: {
|
1505 | fs: CallbackFsClient | PromiseFsClient;
|
1506 | dir?: string;
|
1507 | gitdir?: string;
|
1508 | path: string;
|
1509 | }): Promise<any>;
|
1510 | /**
|
1511 | * Read a multi-valued entry from the git config files.
|
1512 | *
|
1513 | * *Caveats:*
|
1514 | * - Currently only the local `$GIT_DIR/config` file can be read or written. However support for the global `~/.gitconfig` and system `$(prefix)/etc/gitconfig` will be added in the future.
|
1515 | * - The current parser does not support the more exotic features of the git-config file format such as `[include]` and `[includeIf]`.
|
1516 | *
|
1517 | * @param {Object} args
|
1518 | * @param {FsClient} args.fs - a file system implementation
|
1519 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1520 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1521 | * @param {string} args.path - The key of the git config entry
|
1522 | *
|
1523 | * @returns {Promise<Array<any>>} Resolves with the config value
|
1524 | *
|
1525 | */
|
1526 | export function getConfigAll({ fs, dir, gitdir, path, }: {
|
1527 | fs: CallbackFsClient | PromiseFsClient;
|
1528 | dir?: string;
|
1529 | gitdir?: string;
|
1530 | path: string;
|
1531 | }): Promise<any[]>;
|
1532 | /**
|
1533 | *
|
1534 | * @typedef {Object} GetRemoteInfoResult - The object returned has the following schema:
|
1535 | * @property {string[]} capabilities - The list of capabilities returned by the server (part of the Git protocol)
|
1536 | * @property {Object} [refs]
|
1537 | * @property {string} [HEAD] - The default branch of the remote
|
1538 | * @property {Object<string, string>} [refs.heads] - The branches on the remote
|
1539 | * @property {Object<string, string>} [refs.pull] - The special branches representing pull requests (non-standard)
|
1540 | * @property {Object<string, string>} [refs.tags] - The tags on the remote
|
1541 | *
|
1542 | */
|
1543 | /**
|
1544 | * List a remote servers branches, tags, and capabilities.
|
1545 | *
|
1546 | * This is a rare command that doesn't require an `fs`, `dir`, or even `gitdir` argument.
|
1547 | * It just communicates to a remote git server, using the first step of the `git-upload-pack` handshake, but stopping short of fetching the packfile.
|
1548 | *
|
1549 | * @param {object} args
|
1550 | * @param {HttpClient} args.http - an HTTP client
|
1551 | * @param {AuthCallback} [args.onAuth] - optional auth fill callback
|
1552 | * @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
|
1553 | * @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
|
1554 | * @param {string} args.url - The URL of the remote repository. Will be gotten from gitconfig if absent.
|
1555 | * @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
|
1556 | * @param {boolean} [args.forPush = false] - By default, the command queries the 'fetch' capabilities. If true, it will ask for the 'push' capabilities.
|
1557 | * @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
|
1558 | *
|
1559 | * @returns {Promise<GetRemoteInfoResult>} Resolves successfully with an object listing the branches, tags, and capabilities of the remote.
|
1560 | * @see GetRemoteInfoResult
|
1561 | *
|
1562 | * @example
|
1563 | * let info = await git.getRemoteInfo({
|
1564 | * http,
|
1565 | * url:
|
1566 | * "https://cors.isomorphic-git.org/github.com/isomorphic-git/isomorphic-git.git"
|
1567 | * });
|
1568 | * console.log(info);
|
1569 | *
|
1570 | */
|
1571 | export function getRemoteInfo({ http, onAuth, onAuthSuccess, onAuthFailure, corsProxy, url, headers, forPush, }: {
|
1572 | http: HttpClient;
|
1573 | onAuth?: AuthCallback;
|
1574 | onAuthFailure?: AuthFailureCallback;
|
1575 | onAuthSuccess?: AuthSuccessCallback;
|
1576 | url: string;
|
1577 | corsProxy?: string;
|
1578 | forPush?: boolean;
|
1579 | headers?: {
|
1580 | [x: string]: string;
|
1581 | };
|
1582 | }): Promise<GetRemoteInfoResult>;
|
1583 | /**
|
1584 | * @typedef {Object} GetRemoteInfo2Result - This object has the following schema:
|
1585 | * @property {1 | 2} protocolVersion - Git protocol version the server supports
|
1586 | * @property {Object<string, string | true>} capabilities - An object of capabilities represented as keys and values
|
1587 | * @property {ServerRef[]} [refs] - Server refs (they get returned by protocol version 1 whether you want them or not)
|
1588 | */
|
1589 | /**
|
1590 | * List a remote server's capabilities.
|
1591 | *
|
1592 | * This is a rare command that doesn't require an `fs`, `dir`, or even `gitdir` argument.
|
1593 | * It just communicates to a remote git server, determining what protocol version, commands, and features it supports.
|
1594 | *
|
1595 | * > The successor to [`getRemoteInfo`](./getRemoteInfo.md), this command supports Git Wire Protocol Version 2.
|
1596 | * > Therefore its return type is more complicated as either:
|
1597 | * >
|
1598 | * > - v1 capabilities (and refs) or
|
1599 | * > - v2 capabilities (and no refs)
|
1600 | * >
|
1601 | * > are returned.
|
1602 | * > If you just care about refs, use [`listServerRefs`](./listServerRefs.md)
|
1603 | *
|
1604 | * @param {object} args
|
1605 | * @param {HttpClient} args.http - an HTTP client
|
1606 | * @param {AuthCallback} [args.onAuth] - optional auth fill callback
|
1607 | * @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
|
1608 | * @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
|
1609 | * @param {string} args.url - The URL of the remote repository. Will be gotten from gitconfig if absent.
|
1610 | * @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
|
1611 | * @param {boolean} [args.forPush = false] - By default, the command queries the 'fetch' capabilities. If true, it will ask for the 'push' capabilities.
|
1612 | * @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
|
1613 | * @param {1 | 2} [args.protocolVersion = 2] - Which version of the Git Protocol to use.
|
1614 | *
|
1615 | * @returns {Promise<GetRemoteInfo2Result>} Resolves successfully with an object listing the capabilities of the remote.
|
1616 | * @see GetRemoteInfo2Result
|
1617 | * @see ServerRef
|
1618 | *
|
1619 | * @example
|
1620 | * let info = await git.getRemoteInfo2({
|
1621 | * http,
|
1622 | * corsProxy: "https://cors.isomorphic-git.org",
|
1623 | * url: "https://github.com/isomorphic-git/isomorphic-git.git"
|
1624 | * });
|
1625 | * console.log(info);
|
1626 | *
|
1627 | */
|
1628 | export function getRemoteInfo2({ http, onAuth, onAuthSuccess, onAuthFailure, corsProxy, url, headers, forPush, protocolVersion, }: {
|
1629 | http: HttpClient;
|
1630 | onAuth?: AuthCallback;
|
1631 | onAuthFailure?: AuthFailureCallback;
|
1632 | onAuthSuccess?: AuthSuccessCallback;
|
1633 | url: string;
|
1634 | corsProxy?: string;
|
1635 | forPush?: boolean;
|
1636 | headers?: {
|
1637 | [x: string]: string;
|
1638 | };
|
1639 | protocolVersion?: 1 | 2;
|
1640 | }): Promise<GetRemoteInfo2Result>;
|
1641 | /**
|
1642 | *
|
1643 | * @typedef {object} HashBlobResult - The object returned has the following schema:
|
1644 | * @property {string} oid - The SHA-1 object id
|
1645 | * @property {'blob'} type - The type of the object
|
1646 | * @property {Uint8Array} object - The wrapped git object (the thing that is hashed)
|
1647 | * @property {'wrapped'} format - The format of the object
|
1648 | *
|
1649 | */
|
1650 | /**
|
1651 | * Compute what the SHA-1 object id of a file would be
|
1652 | *
|
1653 | * @param {object} args
|
1654 | * @param {Uint8Array|string} args.object - The object to write. If `object` is a String then it will be converted to a Uint8Array using UTF-8 encoding.
|
1655 | *
|
1656 | * @returns {Promise<HashBlobResult>} Resolves successfully with the SHA-1 object id and the wrapped object Uint8Array.
|
1657 | * @see HashBlobResult
|
1658 | *
|
1659 | * @example
|
1660 | * let { oid, type, object, format } = await git.hashBlob({
|
1661 | * object: 'Hello world!',
|
1662 | * })
|
1663 | *
|
1664 | * console.log('oid', oid)
|
1665 | * console.log('type', type)
|
1666 | * console.log('object', object)
|
1667 | * console.log('format', format)
|
1668 | *
|
1669 | */
|
1670 | export function hashBlob({ object }: {
|
1671 | object: string | Uint8Array;
|
1672 | }): Promise<HashBlobResult>;
|
1673 | /**
|
1674 | * Create the .idx file for a given .pack file
|
1675 | *
|
1676 | * @param {object} args
|
1677 | * @param {FsClient} args.fs - a file system client
|
1678 | * @param {ProgressCallback} [args.onProgress] - optional progress event callback
|
1679 | * @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
|
1680 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1681 | * @param {string} args.filepath - The path to the .pack file to index
|
1682 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1683 | *
|
1684 | * @returns {Promise<{oids: string[]}>} Resolves with a list of the SHA-1 object ids contained in the packfile
|
1685 | *
|
1686 | * @example
|
1687 | * let packfiles = await fs.promises.readdir('/tutorial/.git/objects/pack')
|
1688 | * packfiles = packfiles.filter(name => name.endsWith('.pack'))
|
1689 | * console.log('packfiles', packfiles)
|
1690 | *
|
1691 | * const { oids } = await git.indexPack({
|
1692 | * fs,
|
1693 | * dir: '/tutorial',
|
1694 | * filepath: `.git/objects/pack/${packfiles[0]}`,
|
1695 | * async onProgress (evt) {
|
1696 | * console.log(`${evt.phase}: ${evt.loaded} / ${evt.total}`)
|
1697 | * }
|
1698 | * })
|
1699 | * console.log(oids)
|
1700 | *
|
1701 | */
|
1702 | export function indexPack({ fs, onProgress, dir, gitdir, filepath, cache, }: {
|
1703 | fs: CallbackFsClient | PromiseFsClient;
|
1704 | onProgress?: ProgressCallback;
|
1705 | dir: string;
|
1706 | gitdir?: string;
|
1707 | filepath: string;
|
1708 | cache?: any;
|
1709 | }): Promise<{
|
1710 | oids: string[];
|
1711 | }>;
|
1712 | /**
|
1713 | * Initialize a new repository
|
1714 | *
|
1715 | * @param {object} args
|
1716 | * @param {FsClient} args.fs - a file system client
|
1717 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1718 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1719 | * @param {boolean} [args.bare = false] - Initialize a bare repository
|
1720 | * @param {string} [args.defaultBranch = 'master'] - The name of the default branch (might be changed to a required argument in 2.0.0)
|
1721 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
1722 | *
|
1723 | * @example
|
1724 | * await git.init({ fs, dir: '/tutorial' })
|
1725 | * console.log('done')
|
1726 | *
|
1727 | */
|
1728 | export function init({ fs, bare, dir, gitdir, defaultBranch, }: {
|
1729 | fs: CallbackFsClient | PromiseFsClient;
|
1730 | dir?: string;
|
1731 | gitdir?: string;
|
1732 | bare?: boolean;
|
1733 | defaultBranch?: string;
|
1734 | }): Promise<void>;
|
1735 | /**
|
1736 | * Check whether a git commit is descended from another
|
1737 | *
|
1738 | * @param {object} args
|
1739 | * @param {FsClient} args.fs - a file system client
|
1740 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1741 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1742 | * @param {string} args.oid - The descendent commit
|
1743 | * @param {string} args.ancestor - The (proposed) ancestor commit
|
1744 | * @param {number} [args.depth = -1] - Maximum depth to search before giving up. -1 means no maximum depth.
|
1745 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1746 | *
|
1747 | * @returns {Promise<boolean>} Resolves to true if `oid` is a descendent of `ancestor`
|
1748 | *
|
1749 | * @example
|
1750 | * let oid = await git.resolveRef({ fs, dir: '/tutorial', ref: 'main' })
|
1751 | * let ancestor = await git.resolveRef({ fs, dir: '/tutorial', ref: 'v0.20.0' })
|
1752 | * console.log(oid, ancestor)
|
1753 | * await git.isDescendent({ fs, dir: '/tutorial', oid, ancestor, depth: -1 })
|
1754 | *
|
1755 | */
|
1756 | export function isDescendent({ fs, dir, gitdir, oid, ancestor, depth, cache, }: {
|
1757 | fs: CallbackFsClient | PromiseFsClient;
|
1758 | dir?: string;
|
1759 | gitdir?: string;
|
1760 | oid: string;
|
1761 | ancestor: string;
|
1762 | depth?: number;
|
1763 | cache?: any;
|
1764 | }): Promise<boolean>;
|
1765 | /**
|
1766 | * List branches
|
1767 | *
|
1768 | * By default it lists local branches. If a 'remote' is specified, it lists the remote's branches. When listing remote branches, the HEAD branch is not filtered out, so it may be included in the list of results.
|
1769 | *
|
1770 | * Note that specifying a remote does not actually contact the server and update the list of branches.
|
1771 | * If you want an up-to-date list, first do a `fetch` to that remote.
|
1772 | * (Which branch you fetch doesn't matter - the list of branches available on the remote is updated during the fetch handshake.)
|
1773 | *
|
1774 | * @param {object} args
|
1775 | * @param {FsClient} args.fs - a file system client
|
1776 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1777 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1778 | * @param {string} [args.remote] - Instead of the branches in `refs/heads`, list the branches in `refs/remotes/${remote}`.
|
1779 | *
|
1780 | * @returns {Promise<Array<string>>} Resolves successfully with an array of branch names
|
1781 | *
|
1782 | * @example
|
1783 | * let branches = await git.listBranches({ fs, dir: '/tutorial' })
|
1784 | * console.log(branches)
|
1785 | * let remoteBranches = await git.listBranches({ fs, dir: '/tutorial', remote: 'origin' })
|
1786 | * console.log(remoteBranches)
|
1787 | *
|
1788 | */
|
1789 | export function listBranches({ fs, dir, gitdir, remote, }: {
|
1790 | fs: CallbackFsClient | PromiseFsClient;
|
1791 | dir?: string;
|
1792 | gitdir?: string;
|
1793 | remote?: string;
|
1794 | }): Promise<string[]>;
|
1795 | /**
|
1796 | * List all the files in the git index or a commit
|
1797 | *
|
1798 | * > Note: This function is efficient for listing the files in the staging area, but listing all the files in a commit requires recursively walking through the git object store.
|
1799 | * > If you do not require a complete list of every file, better performance can be achieved by using [walk](./walk) and ignoring subdirectories you don't care about.
|
1800 | *
|
1801 | * @param {object} args
|
1802 | * @param {FsClient} args.fs - a file system client
|
1803 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1804 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1805 | * @param {string} [args.ref] - Return a list of all the files in the commit at `ref` instead of the files currently in the git index (aka staging area)
|
1806 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1807 | *
|
1808 | * @returns {Promise<Array<string>>} Resolves successfully with an array of filepaths
|
1809 | *
|
1810 | * @example
|
1811 | * // All the files in the previous commit
|
1812 | * let files = await git.listFiles({ fs, dir: '/tutorial', ref: 'HEAD' })
|
1813 | * console.log(files)
|
1814 | * // All the files in the current staging area
|
1815 | * files = await git.listFiles({ fs, dir: '/tutorial' })
|
1816 | * console.log(files)
|
1817 | *
|
1818 | */
|
1819 | export function listFiles({ fs, dir, gitdir, ref, cache, }: {
|
1820 | fs: CallbackFsClient | PromiseFsClient;
|
1821 | dir?: string;
|
1822 | gitdir?: string;
|
1823 | ref?: string;
|
1824 | cache?: any;
|
1825 | }): Promise<string[]>;
|
1826 | /**
|
1827 | * List all the object notes
|
1828 | *
|
1829 | * @param {object} args
|
1830 | * @param {FsClient} args.fs - a file system client
|
1831 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1832 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1833 | * @param {string} [args.ref] - The notes ref to look under
|
1834 | * @param {object} [args.cache] - a [cache](cache.md) object
|
1835 | *
|
1836 | * @returns {Promise<Array<{target: string, note: string}>>} Resolves successfully with an array of entries containing SHA-1 object ids of the note and the object the note targets
|
1837 | */
|
1838 | export function listNotes({ fs, dir, gitdir, ref, cache, }: {
|
1839 | fs: CallbackFsClient | PromiseFsClient;
|
1840 | dir?: string;
|
1841 | gitdir?: string;
|
1842 | ref?: string;
|
1843 | cache?: any;
|
1844 | }): Promise<{
|
1845 | target: string;
|
1846 | note: string;
|
1847 | }[]>;
|
1848 | /**
|
1849 | * List remotes
|
1850 | *
|
1851 | * @param {object} args
|
1852 | * @param {FsClient} args.fs - a file system client
|
1853 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1854 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1855 | *
|
1856 | * @returns {Promise<Array<{remote: string, url: string}>>} Resolves successfully with an array of `{remote, url}` objects
|
1857 | *
|
1858 | * @example
|
1859 | * let remotes = await git.listRemotes({ fs, dir: '/tutorial' })
|
1860 | * console.log(remotes)
|
1861 | *
|
1862 | */
|
1863 | export function listRemotes({ fs, dir, gitdir }: {
|
1864 | fs: CallbackFsClient | PromiseFsClient;
|
1865 | dir?: string;
|
1866 | gitdir?: string;
|
1867 | }): Promise<{
|
1868 | remote: string;
|
1869 | url: string;
|
1870 | }[]>;
|
1871 | /**
|
1872 | * Fetch a list of refs (branches, tags, etc) from a server.
|
1873 | *
|
1874 | * This is a rare command that doesn't require an `fs`, `dir`, or even `gitdir` argument.
|
1875 | * It just requires an `http` argument.
|
1876 | *
|
1877 | * ### About `protocolVersion`
|
1878 | *
|
1879 | * There's a rather fun trade-off between Git Protocol Version 1 and Git Protocol Version 2.
|
1880 | * Version 2 actually requires 2 HTTP requests instead of 1, making it similar to fetch or push in that regard.
|
1881 | * However, version 2 supports server-side filtering by prefix, whereas that filtering is done client-side in version 1.
|
1882 | * Which protocol is most efficient therefore depends on the number of refs on the remote, the latency of the server, and speed of the network connection.
|
1883 | * For an small repos (or fast Internet connections), the requirement to make two trips to the server makes protocol 2 slower.
|
1884 | * But for large repos (or slow Internet connections), the decreased payload size of the second request makes up for the additional request.
|
1885 | *
|
1886 | * Hard numbers vary by situation, but here's some numbers from my machine:
|
1887 | *
|
1888 | * Using isomorphic-git in a browser, with a CORS proxy, listing only the branches (refs/heads) of https://github.com/isomorphic-git/isomorphic-git
|
1889 | * - Protocol Version 1 took ~300ms and transfered 84 KB.
|
1890 | * - Protocol Version 2 took ~500ms and transfered 4.1 KB.
|
1891 | *
|
1892 | * Using isomorphic-git in a browser, with a CORS proxy, listing only the branches (refs/heads) of https://gitlab.com/gitlab-org/gitlab
|
1893 | * - Protocol Version 1 took ~4900ms and transfered 9.41 MB.
|
1894 | * - Protocol Version 2 took ~1280ms and transfered 433 KB.
|
1895 | *
|
1896 | * Finally, there is a fun quirk regarding the `symrefs` parameter.
|
1897 | * Protocol Version 1 will generally only return the `HEAD` symref and not others.
|
1898 | * Historically, this meant that servers don't use symbolic refs except for `HEAD`, which is used to point at the "default branch".
|
1899 | * However Protocol Version 2 can return *all* the symbolic refs on the server.
|
1900 | * So if you are running your own git server, you could take advantage of that I guess.
|
1901 | *
|
1902 | * #### TL;DR
|
1903 | * If you are _not_ taking advantage of `prefix` I would recommend `protocolVersion: 1`.
|
1904 | * Otherwise, I recommend to use the default which is `protocolVersion: 2`.
|
1905 | *
|
1906 | * @param {object} args
|
1907 | * @param {HttpClient} args.http - an HTTP client
|
1908 | * @param {AuthCallback} [args.onAuth] - optional auth fill callback
|
1909 | * @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
|
1910 | * @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
|
1911 | * @param {string} args.url - The URL of the remote repository. Will be gotten from gitconfig if absent.
|
1912 | * @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
|
1913 | * @param {boolean} [args.forPush = false] - By default, the command queries the 'fetch' capabilities. If true, it will ask for the 'push' capabilities.
|
1914 | * @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
|
1915 | * @param {1 | 2} [args.protocolVersion = 2] - Which version of the Git Protocol to use.
|
1916 | * @param {string} [args.prefix] - Only list refs that start with this prefix
|
1917 | * @param {boolean} [args.symrefs = false] - Include symbolic ref targets
|
1918 | * @param {boolean} [args.peelTags = false] - Include annotated tag peeled targets
|
1919 | *
|
1920 | * @returns {Promise<ServerRef[]>} Resolves successfully with an array of ServerRef objects
|
1921 | * @see ServerRef
|
1922 | *
|
1923 | * @example
|
1924 | * // List all the branches on a repo
|
1925 | * let refs = await git.listServerRefs({
|
1926 | * http,
|
1927 | * corsProxy: "https://cors.isomorphic-git.org",
|
1928 | * url: "https://github.com/isomorphic-git/isomorphic-git.git",
|
1929 | * prefix: "refs/heads/",
|
1930 | * });
|
1931 | * console.log(refs);
|
1932 | *
|
1933 | * @example
|
1934 | * // Get the default branch on a repo
|
1935 | * let refs = await git.listServerRefs({
|
1936 | * http,
|
1937 | * corsProxy: "https://cors.isomorphic-git.org",
|
1938 | * url: "https://github.com/isomorphic-git/isomorphic-git.git",
|
1939 | * prefix: "HEAD",
|
1940 | * symrefs: true,
|
1941 | * });
|
1942 | * console.log(refs);
|
1943 | *
|
1944 | * @example
|
1945 | * // List all the tags on a repo
|
1946 | * let refs = await git.listServerRefs({
|
1947 | * http,
|
1948 | * corsProxy: "https://cors.isomorphic-git.org",
|
1949 | * url: "https://github.com/isomorphic-git/isomorphic-git.git",
|
1950 | * prefix: "refs/tags/",
|
1951 | * peelTags: true,
|
1952 | * });
|
1953 | * console.log(refs);
|
1954 | *
|
1955 | * @example
|
1956 | * // List all the pull requests on a repo
|
1957 | * let refs = await git.listServerRefs({
|
1958 | * http,
|
1959 | * corsProxy: "https://cors.isomorphic-git.org",
|
1960 | * url: "https://github.com/isomorphic-git/isomorphic-git.git",
|
1961 | * prefix: "refs/pull/",
|
1962 | * });
|
1963 | * console.log(refs);
|
1964 | *
|
1965 | */
|
1966 | export function listServerRefs({ http, onAuth, onAuthSuccess, onAuthFailure, corsProxy, url, headers, forPush, protocolVersion, prefix, symrefs, peelTags, }: {
|
1967 | http: HttpClient;
|
1968 | onAuth?: AuthCallback;
|
1969 | onAuthFailure?: AuthFailureCallback;
|
1970 | onAuthSuccess?: AuthSuccessCallback;
|
1971 | url: string;
|
1972 | corsProxy?: string;
|
1973 | forPush?: boolean;
|
1974 | headers?: {
|
1975 | [x: string]: string;
|
1976 | };
|
1977 | protocolVersion?: 1 | 2;
|
1978 | prefix?: string;
|
1979 | symrefs?: boolean;
|
1980 | peelTags?: boolean;
|
1981 | }): Promise<ServerRef[]>;
|
1982 | /**
|
1983 | * List tags
|
1984 | *
|
1985 | * @param {object} args
|
1986 | * @param {FsClient} args.fs - a file system client
|
1987 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
1988 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
1989 | *
|
1990 | * @returns {Promise<Array<string>>} Resolves successfully with an array of tag names
|
1991 | *
|
1992 | * @example
|
1993 | * let tags = await git.listTags({ fs, dir: '/tutorial' })
|
1994 | * console.log(tags)
|
1995 | *
|
1996 | */
|
1997 | export function listTags({ fs, dir, gitdir }: {
|
1998 | fs: CallbackFsClient | PromiseFsClient;
|
1999 | dir?: string;
|
2000 | gitdir?: string;
|
2001 | }): Promise<string[]>;
|
2002 | /**
|
2003 | * Get commit descriptions from the git history
|
2004 | *
|
2005 | * @param {object} args
|
2006 | * @param {FsClient} args.fs - a file system client
|
2007 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2008 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2009 | * @param {string=} args.filepath optional get the commit for the filepath only
|
2010 | * @param {string} [args.ref = 'HEAD'] - The commit to begin walking backwards through the history from
|
2011 | * @param {number=} [args.depth] - Limit the number of commits returned. No limit by default.
|
2012 | * @param {Date} [args.since] - Return history newer than the given date. Can be combined with `depth` to get whichever is shorter.
|
2013 | * @param {boolean=} [args.force=false] do not throw error if filepath is not exist (works only for a single file). defaults to false
|
2014 | * @param {boolean=} [args.follow=false] Continue listing the history of a file beyond renames (works only for a single file). defaults to false
|
2015 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2016 | *
|
2017 | * @returns {Promise<Array<ReadCommitResult>>} Resolves to an array of ReadCommitResult objects
|
2018 | * @see ReadCommitResult
|
2019 | * @see CommitObject
|
2020 | *
|
2021 | * @example
|
2022 | * let commits = await git.log({
|
2023 | * fs,
|
2024 | * dir: '/tutorial',
|
2025 | * depth: 5,
|
2026 | * ref: 'main'
|
2027 | * })
|
2028 | * console.log(commits)
|
2029 | *
|
2030 | */
|
2031 | export function log({ fs, dir, gitdir, filepath, ref, depth, since, force, follow, cache, }: {
|
2032 | fs: CallbackFsClient | PromiseFsClient;
|
2033 | dir?: string;
|
2034 | gitdir?: string;
|
2035 | filepath?: string | undefined;
|
2036 | ref?: string;
|
2037 | depth?: number | undefined;
|
2038 | since?: Date;
|
2039 | force?: boolean | undefined;
|
2040 | follow?: boolean | undefined;
|
2041 | cache?: any;
|
2042 | }): Promise<ReadCommitResult[]>;
|
2043 | /**
|
2044 | *
|
2045 | * @typedef {Object} MergeResult - Returns an object with a schema like this:
|
2046 | * @property {string} [oid] - The SHA-1 object id that is now at the head of the branch. Absent only if `dryRun` was specified and `mergeCommit` is true.
|
2047 | * @property {boolean} [alreadyMerged] - True if the branch was already merged so no changes were made
|
2048 | * @property {boolean} [fastForward] - True if it was a fast-forward merge
|
2049 | * @property {boolean} [mergeCommit] - True if merge resulted in a merge commit
|
2050 | * @property {string} [tree] - The SHA-1 object id of the tree resulting from a merge commit
|
2051 | *
|
2052 | */
|
2053 | /**
|
2054 | * Merge two branches
|
2055 | *
|
2056 | * ## Limitations
|
2057 | *
|
2058 | * Currently it does not support incomplete merges. That is, if there are merge conflicts it cannot solve
|
2059 | * with the built in diff3 algorithm it will not modify the working dir, and will throw a [`MergeNotSupportedError`](./errors.md#mergenotsupportedError) error.
|
2060 | *
|
2061 | * Currently it will fail if multiple candidate merge bases are found. (It doesn't yet implement the recursive merge strategy.)
|
2062 | *
|
2063 | * Currently it does not support selecting alternative merge strategies.
|
2064 | *
|
2065 | * @param {object} args
|
2066 | * @param {FsClient} args.fs - a file system client
|
2067 | * @param {SignCallback} [args.onSign] - a PGP signing implementation
|
2068 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2069 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2070 | * @param {string} [args.ours] - The branch receiving the merge. If undefined, defaults to the current branch.
|
2071 | * @param {string} args.theirs - The branch to be merged
|
2072 | * @param {boolean} [args.fastForwardOnly = false] - If true, then non-fast-forward merges will throw an Error instead of performing a merge.
|
2073 | * @param {boolean} [args.dryRun = false] - If true, simulates a merge so you can test whether it would succeed.
|
2074 | * @param {boolean} [args.noUpdateBranch = false] - If true, does not update the branch pointer after creating the commit.
|
2075 | * @param {string} [args.message] - Overrides the default auto-generated merge commit message
|
2076 | * @param {Object} [args.author] - passed to [commit](commit.md) when creating a merge commit
|
2077 | * @param {string} [args.author.name] - Default is `user.name` config.
|
2078 | * @param {string} [args.author.email] - Default is `user.email` config.
|
2079 | * @param {number} [args.author.timestamp=Math.floor(Date.now()/1000)] - Set the author timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
2080 | * @param {number} [args.author.timezoneOffset] - Set the author timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
2081 | * @param {Object} [args.committer] - passed to [commit](commit.md) when creating a merge commit
|
2082 | * @param {string} [args.committer.name] - Default is `user.name` config.
|
2083 | * @param {string} [args.committer.email] - Default is `user.email` config.
|
2084 | * @param {number} [args.committer.timestamp=Math.floor(Date.now()/1000)] - Set the committer timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
2085 | * @param {number} [args.committer.timezoneOffset] - Set the committer timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
2086 | * @param {string} [args.signingKey] - passed to [commit](commit.md) when creating a merge commit
|
2087 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2088 | *
|
2089 | * @returns {Promise<MergeResult>} Resolves to a description of the merge operation
|
2090 | * @see MergeResult
|
2091 | *
|
2092 | * @example
|
2093 | * let m = await git.merge({
|
2094 | * fs,
|
2095 | * dir: '/tutorial',
|
2096 | * ours: 'main',
|
2097 | * theirs: 'remotes/origin/main'
|
2098 | * })
|
2099 | * console.log(m)
|
2100 | *
|
2101 | */
|
2102 | export function merge({ fs: _fs, onSign, dir, gitdir, ours, theirs, fastForwardOnly, dryRun, noUpdateBranch, message, author: _author, committer: _committer, signingKey, cache, }: {
|
2103 | fs: CallbackFsClient | PromiseFsClient;
|
2104 | onSign?: SignCallback;
|
2105 | dir?: string;
|
2106 | gitdir?: string;
|
2107 | ours?: string;
|
2108 | theirs: string;
|
2109 | fastForwardOnly?: boolean;
|
2110 | dryRun?: boolean;
|
2111 | noUpdateBranch?: boolean;
|
2112 | message?: string;
|
2113 | author?: {
|
2114 | name?: string;
|
2115 | email?: string;
|
2116 | timestamp?: number;
|
2117 | timezoneOffset?: number;
|
2118 | };
|
2119 | committer?: {
|
2120 | name?: string;
|
2121 | email?: string;
|
2122 | timestamp?: number;
|
2123 | timezoneOffset?: number;
|
2124 | };
|
2125 | signingKey?: string;
|
2126 | cache?: any;
|
2127 | }): Promise<MergeResult>;
|
2128 | /**
|
2129 | *
|
2130 | * @typedef {Object} PackObjectsResult The packObjects command returns an object with two properties:
|
2131 | * @property {string} filename - The suggested filename for the packfile if you want to save it to disk somewhere. It includes the packfile SHA.
|
2132 | * @property {Uint8Array} [packfile] - The packfile contents. Not present if `write` parameter was true, in which case the packfile was written straight to disk.
|
2133 | */
|
2134 | /**
|
2135 | * Create a packfile from an array of SHA-1 object ids
|
2136 | *
|
2137 | * @param {object} args
|
2138 | * @param {FsClient} args.fs - a file system client
|
2139 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2140 | * @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2141 | * @param {string[]} args.oids - An array of SHA-1 object ids to be included in the packfile
|
2142 | * @param {boolean} [args.write = false] - Whether to save the packfile to disk or not
|
2143 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2144 | *
|
2145 | * @returns {Promise<PackObjectsResult>} Resolves successfully when the packfile is ready with the filename and buffer
|
2146 | * @see PackObjectsResult
|
2147 | *
|
2148 | * @example
|
2149 | * // Create a packfile containing only an empty tree
|
2150 | * let { packfile } = await git.packObjects({
|
2151 | * fs,
|
2152 | * dir: '/tutorial',
|
2153 | * oids: ['4b825dc642cb6eb9a060e54bf8d69288fbee4904']
|
2154 | * })
|
2155 | * console.log(packfile)
|
2156 | *
|
2157 | */
|
2158 | export function packObjects({ fs, dir, gitdir, oids, write, cache, }: {
|
2159 | fs: CallbackFsClient | PromiseFsClient;
|
2160 | dir?: string;
|
2161 | gitdir?: string;
|
2162 | oids: string[];
|
2163 | write?: boolean;
|
2164 | cache?: any;
|
2165 | }): Promise<PackObjectsResult>;
|
2166 | /**
|
2167 | * Fetch and merge commits from a remote repository
|
2168 | *
|
2169 | * @param {object} args
|
2170 | * @param {FsClient} args.fs - a file system client
|
2171 | * @param {HttpClient} args.http - an HTTP client
|
2172 | * @param {ProgressCallback} [args.onProgress] - optional progress event callback
|
2173 | * @param {MessageCallback} [args.onMessage] - optional message event callback
|
2174 | * @param {AuthCallback} [args.onAuth] - optional auth fill callback
|
2175 | * @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
|
2176 | * @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
|
2177 | * @param {string} args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2178 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2179 | * @param {string} [args.ref] - Which branch to merge into. By default this is the currently checked out branch.
|
2180 | * @param {string} [args.url] - (Added in 1.1.0) The URL of the remote repository. The default is the value set in the git config for that remote.
|
2181 | * @param {string} [args.remote] - (Added in 1.1.0) If URL is not specified, determines which remote to use.
|
2182 | * @param {string} [args.remoteRef] - (Added in 1.1.0) The name of the branch on the remote to fetch. By default this is the configured remote tracking branch.
|
2183 | * @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
|
2184 | * @param {boolean} [args.singleBranch = false] - Instead of the default behavior of fetching all the branches, only fetch a single branch.
|
2185 | * @param {boolean} [args.fastForwardOnly = false] - Only perform simple fast-forward merges. (Don't create merge commits.)
|
2186 | * @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
|
2187 | * @param {Object} [args.author] - The details about the author.
|
2188 | * @param {string} [args.author.name] - Default is `user.name` config.
|
2189 | * @param {string} [args.author.email] - Default is `user.email` config.
|
2190 | * @param {number} [args.author.timestamp=Math.floor(Date.now()/1000)] - Set the author timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
2191 | * @param {number} [args.author.timezoneOffset] - Set the author timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
2192 | * @param {Object} [args.committer = author] - The details about the commit committer, in the same format as the author parameter. If not specified, the author details are used.
|
2193 | * @param {string} [args.committer.name] - Default is `user.name` config.
|
2194 | * @param {string} [args.committer.email] - Default is `user.email` config.
|
2195 | * @param {number} [args.committer.timestamp=Math.floor(Date.now()/1000)] - Set the committer timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
2196 | * @param {number} [args.committer.timezoneOffset] - Set the committer timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
2197 | * @param {string} [args.signingKey] - passed to [commit](commit.md) when creating a merge commit
|
2198 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2199 | *
|
2200 | * @returns {Promise<void>} Resolves successfully when pull operation completes
|
2201 | *
|
2202 | * @example
|
2203 | * await git.pull({
|
2204 | * fs,
|
2205 | * http,
|
2206 | * dir: '/tutorial',
|
2207 | * ref: 'main',
|
2208 | * singleBranch: true
|
2209 | * })
|
2210 | * console.log('done')
|
2211 | *
|
2212 | */
|
2213 | export function pull({ fs: _fs, http, onProgress, onMessage, onAuth, onAuthSuccess, onAuthFailure, dir, gitdir, ref, url, remote, remoteRef, fastForwardOnly, corsProxy, singleBranch, headers, author: _author, committer: _committer, signingKey, cache, }: {
|
2214 | fs: CallbackFsClient | PromiseFsClient;
|
2215 | http: HttpClient;
|
2216 | onProgress?: ProgressCallback;
|
2217 | onMessage?: MessageCallback;
|
2218 | onAuth?: AuthCallback;
|
2219 | onAuthFailure?: AuthFailureCallback;
|
2220 | onAuthSuccess?: AuthSuccessCallback;
|
2221 | dir: string;
|
2222 | gitdir?: string;
|
2223 | ref?: string;
|
2224 | url?: string;
|
2225 | remote?: string;
|
2226 | remoteRef?: string;
|
2227 | corsProxy?: string;
|
2228 | singleBranch?: boolean;
|
2229 | fastForwardOnly?: boolean;
|
2230 | headers?: {
|
2231 | [x: string]: string;
|
2232 | };
|
2233 | author?: {
|
2234 | name?: string;
|
2235 | email?: string;
|
2236 | timestamp?: number;
|
2237 | timezoneOffset?: number;
|
2238 | };
|
2239 | committer?: {
|
2240 | name?: string;
|
2241 | email?: string;
|
2242 | timestamp?: number;
|
2243 | timezoneOffset?: number;
|
2244 | };
|
2245 | signingKey?: string;
|
2246 | cache?: any;
|
2247 | }): Promise<void>;
|
2248 | /**
|
2249 | * Push a branch or tag
|
2250 | *
|
2251 | * The push command returns an object that describes the result of the attempted push operation.
|
2252 | * *Notes:* If there were no errors, then there will be no `errors` property. There can be a mix of `ok` messages and `errors` messages.
|
2253 | *
|
2254 | * | param | type [= default] | description |
|
2255 | * | ------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
2256 | * | ok | Array\<string\> | The first item is "unpack" if the overall operation was successful. The remaining items are the names of refs that were updated successfully. |
|
2257 | * | errors | Array\<string\> | If the overall operation threw and error, the first item will be "unpack {Overall error message}". The remaining items are individual refs that failed to be updated in the format "{ref name} {error message}". |
|
2258 | *
|
2259 | * @param {object} args
|
2260 | * @param {FsClient} args.fs - a file system client
|
2261 | * @param {HttpClient} args.http - an HTTP client
|
2262 | * @param {ProgressCallback} [args.onProgress] - optional progress event callback
|
2263 | * @param {MessageCallback} [args.onMessage] - optional message event callback
|
2264 | * @param {AuthCallback} [args.onAuth] - optional auth fill callback
|
2265 | * @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
|
2266 | * @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
|
2267 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2268 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2269 | * @param {string} [args.ref] - Which branch to push. By default this is the currently checked out branch.
|
2270 | * @param {string} [args.url] - The URL of the remote repository. The default is the value set in the git config for that remote.
|
2271 | * @param {string} [args.remote] - If URL is not specified, determines which remote to use.
|
2272 | * @param {string} [args.remoteRef] - The name of the receiving branch on the remote. By default this is the configured remote tracking branch.
|
2273 | * @param {boolean} [args.force = false] - If true, behaves the same as `git push --force`
|
2274 | * @param {boolean} [args.delete = false] - If true, delete the remote ref
|
2275 | * @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
|
2276 | * @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
|
2277 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2278 | *
|
2279 | * @returns {Promise<PushResult>} Resolves successfully when push completes with a detailed description of the operation from the server.
|
2280 | * @see PushResult
|
2281 | * @see RefUpdateStatus
|
2282 | *
|
2283 | * @example
|
2284 | * let pushResult = await git.push({
|
2285 | * fs,
|
2286 | * http,
|
2287 | * dir: '/tutorial',
|
2288 | * remote: 'origin',
|
2289 | * ref: 'main',
|
2290 | * onAuth: () => ({ username: process.env.GITHUB_TOKEN }),
|
2291 | * })
|
2292 | * console.log(pushResult)
|
2293 | *
|
2294 | */
|
2295 | export function push({ fs, http, onProgress, onMessage, onAuth, onAuthSuccess, onAuthFailure, dir, gitdir, ref, remoteRef, remote, url, force, delete: _delete, corsProxy, headers, cache, }: {
|
2296 | fs: CallbackFsClient | PromiseFsClient;
|
2297 | http: HttpClient;
|
2298 | onProgress?: ProgressCallback;
|
2299 | onMessage?: MessageCallback;
|
2300 | onAuth?: AuthCallback;
|
2301 | onAuthFailure?: AuthFailureCallback;
|
2302 | onAuthSuccess?: AuthSuccessCallback;
|
2303 | dir?: string;
|
2304 | gitdir?: string;
|
2305 | ref?: string;
|
2306 | url?: string;
|
2307 | remote?: string;
|
2308 | remoteRef?: string;
|
2309 | force?: boolean;
|
2310 | delete?: boolean;
|
2311 | corsProxy?: string;
|
2312 | headers?: {
|
2313 | [x: string]: string;
|
2314 | };
|
2315 | cache?: any;
|
2316 | }): Promise<PushResult>;
|
2317 | /**
|
2318 | *
|
2319 | * @typedef {Object} ReadBlobResult - The object returned has the following schema:
|
2320 | * @property {string} oid
|
2321 | * @property {Uint8Array} blob
|
2322 | *
|
2323 | */
|
2324 | /**
|
2325 | * Read a blob object directly
|
2326 | *
|
2327 | * @param {object} args
|
2328 | * @param {FsClient} args.fs - a file system client
|
2329 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2330 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2331 | * @param {string} args.oid - The SHA-1 object id to get. Annotated tags, commits, and trees are peeled.
|
2332 | * @param {string} [args.filepath] - Don't return the object with `oid` itself, but resolve `oid` to a tree and then return the blob object at that filepath.
|
2333 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2334 | *
|
2335 | * @returns {Promise<ReadBlobResult>} Resolves successfully with a blob object description
|
2336 | * @see ReadBlobResult
|
2337 | *
|
2338 | * @example
|
2339 | * // Get the contents of 'README.md' in the main branch.
|
2340 | * let commitOid = await git.resolveRef({ fs, dir: '/tutorial', ref: 'main' })
|
2341 | * console.log(commitOid)
|
2342 | * let { blob } = await git.readBlob({
|
2343 | * fs,
|
2344 | * dir: '/tutorial',
|
2345 | * oid: commitOid,
|
2346 | * filepath: 'README.md'
|
2347 | * })
|
2348 | * console.log(Buffer.from(blob).toString('utf8'))
|
2349 | *
|
2350 | */
|
2351 | export function readBlob({ fs, dir, gitdir, oid, filepath, cache, }: {
|
2352 | fs: CallbackFsClient | PromiseFsClient;
|
2353 | dir?: string;
|
2354 | gitdir?: string;
|
2355 | oid: string;
|
2356 | filepath?: string;
|
2357 | cache?: any;
|
2358 | }): Promise<ReadBlobResult>;
|
2359 | /**
|
2360 | * Read a commit object directly
|
2361 | *
|
2362 | * @param {object} args
|
2363 | * @param {FsClient} args.fs - a file system client
|
2364 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2365 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2366 | * @param {string} args.oid - The SHA-1 object id to get. Annotated tags are peeled.
|
2367 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2368 | *
|
2369 | * @returns {Promise<ReadCommitResult>} Resolves successfully with a git commit object
|
2370 | * @see ReadCommitResult
|
2371 | * @see CommitObject
|
2372 | *
|
2373 | * @example
|
2374 | * // Read a commit object
|
2375 | * let sha = await git.resolveRef({ fs, dir: '/tutorial', ref: 'main' })
|
2376 | * console.log(sha)
|
2377 | * let commit = await git.readCommit({ fs, dir: '/tutorial', oid: sha })
|
2378 | * console.log(commit)
|
2379 | *
|
2380 | */
|
2381 | export function readCommit({ fs, dir, gitdir, oid, cache, }: {
|
2382 | fs: CallbackFsClient | PromiseFsClient;
|
2383 | dir?: string;
|
2384 | gitdir?: string;
|
2385 | oid: string;
|
2386 | cache?: any;
|
2387 | }): Promise<ReadCommitResult>;
|
2388 | /**
|
2389 | * Read the contents of a note
|
2390 | *
|
2391 | * @param {object} args
|
2392 | * @param {FsClient} args.fs - a file system client
|
2393 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2394 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2395 | * @param {string} [args.ref] - The notes ref to look under
|
2396 | * @param {string} args.oid - The SHA-1 object id of the object to get the note for.
|
2397 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2398 | *
|
2399 | * @returns {Promise<Uint8Array>} Resolves successfully with note contents as a Buffer.
|
2400 | */
|
2401 | export function readNote({ fs, dir, gitdir, ref, oid, cache, }: {
|
2402 | fs: CallbackFsClient | PromiseFsClient;
|
2403 | dir?: string;
|
2404 | gitdir?: string;
|
2405 | ref?: string;
|
2406 | oid: string;
|
2407 | cache?: any;
|
2408 | }): Promise<Uint8Array>;
|
2409 | /**
|
2410 | *
|
2411 | * @typedef {Object} DeflatedObject
|
2412 | * @property {string} oid
|
2413 | * @property {'deflated'} type
|
2414 | * @property {'deflated'} format
|
2415 | * @property {Uint8Array} object
|
2416 | * @property {string} [source]
|
2417 | *
|
2418 | */
|
2419 | /**
|
2420 | *
|
2421 | * @typedef {Object} WrappedObject
|
2422 | * @property {string} oid
|
2423 | * @property {'wrapped'} type
|
2424 | * @property {'wrapped'} format
|
2425 | * @property {Uint8Array} object
|
2426 | * @property {string} [source]
|
2427 | *
|
2428 | */
|
2429 | /**
|
2430 | *
|
2431 | * @typedef {Object} RawObject
|
2432 | * @property {string} oid
|
2433 | * @property {'blob'|'commit'|'tree'|'tag'} type
|
2434 | * @property {'content'} format
|
2435 | * @property {Uint8Array} object
|
2436 | * @property {string} [source]
|
2437 | *
|
2438 | */
|
2439 | /**
|
2440 | *
|
2441 | * @typedef {Object} ParsedBlobObject
|
2442 | * @property {string} oid
|
2443 | * @property {'blob'} type
|
2444 | * @property {'parsed'} format
|
2445 | * @property {string} object
|
2446 | * @property {string} [source]
|
2447 | *
|
2448 | */
|
2449 | /**
|
2450 | *
|
2451 | * @typedef {Object} ParsedCommitObject
|
2452 | * @property {string} oid
|
2453 | * @property {'commit'} type
|
2454 | * @property {'parsed'} format
|
2455 | * @property {CommitObject} object
|
2456 | * @property {string} [source]
|
2457 | *
|
2458 | */
|
2459 | /**
|
2460 | *
|
2461 | * @typedef {Object} ParsedTreeObject
|
2462 | * @property {string} oid
|
2463 | * @property {'tree'} type
|
2464 | * @property {'parsed'} format
|
2465 | * @property {TreeObject} object
|
2466 | * @property {string} [source]
|
2467 | *
|
2468 | */
|
2469 | /**
|
2470 | *
|
2471 | * @typedef {Object} ParsedTagObject
|
2472 | * @property {string} oid
|
2473 | * @property {'tag'} type
|
2474 | * @property {'parsed'} format
|
2475 | * @property {TagObject} object
|
2476 | * @property {string} [source]
|
2477 | *
|
2478 | */
|
2479 | /**
|
2480 | *
|
2481 | * @typedef {ParsedBlobObject | ParsedCommitObject | ParsedTreeObject | ParsedTagObject} ParsedObject
|
2482 | */
|
2483 | /**
|
2484 | *
|
2485 | * @typedef {DeflatedObject | WrappedObject | RawObject | ParsedObject } ReadObjectResult
|
2486 | */
|
2487 | /**
|
2488 | * Read a git object directly by its SHA-1 object id
|
2489 | *
|
2490 | * Regarding `ReadObjectResult`:
|
2491 | *
|
2492 | * - `oid` will be the same as the `oid` argument unless the `filepath` argument is provided, in which case it will be the oid of the tree or blob being returned.
|
2493 | * - `type` of deflated objects is `'deflated'`, and `type` of wrapped objects is `'wrapped'`
|
2494 | * - `format` is usually, but not always, the format you requested. Packfiles do not store each object individually compressed so if you end up reading the object from a packfile it will be returned in format 'content' even if you requested 'deflated' or 'wrapped'.
|
2495 | * - `object` will be an actual Object if format is 'parsed' and the object is a commit, tree, or annotated tag. Blobs are still formatted as Buffers unless an encoding is provided in which case they'll be strings. If format is anything other than 'parsed', object will be a Buffer.
|
2496 | * - `source` is the name of the packfile or loose object file where the object was found.
|
2497 | *
|
2498 | * The `format` parameter can have the following values:
|
2499 | *
|
2500 | * | param | description |
|
2501 | * | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
2502 | * | 'deflated' | Return the raw deflate-compressed buffer for an object if possible. Useful for efficiently shuffling around loose objects when you don't care about the contents and can save time by not inflating them. |
|
2503 | * | 'wrapped' | Return the inflated object buffer wrapped in the git object header if possible. This is the raw data used when calculating the SHA-1 object id of a git object. |
|
2504 | * | 'content' | Return the object buffer without the git header. |
|
2505 | * | 'parsed' | Returns a parsed representation of the object. |
|
2506 | *
|
2507 | * The result will be in one of the following schemas:
|
2508 | *
|
2509 | * ## `'deflated'` format
|
2510 | *
|
2511 | * {@link DeflatedObject typedef}
|
2512 | *
|
2513 | * ## `'wrapped'` format
|
2514 | *
|
2515 | * {@link WrappedObject typedef}
|
2516 | *
|
2517 | * ## `'content'` format
|
2518 | *
|
2519 | * {@link RawObject typedef}
|
2520 | *
|
2521 | * ## `'parsed'` format
|
2522 | *
|
2523 | * ### parsed `'blob'` type
|
2524 | *
|
2525 | * {@link ParsedBlobObject typedef}
|
2526 | *
|
2527 | * ### parsed `'commit'` type
|
2528 | *
|
2529 | * {@link ParsedCommitObject typedef}
|
2530 | * {@link CommitObject typedef}
|
2531 | *
|
2532 | * ### parsed `'tree'` type
|
2533 | *
|
2534 | * {@link ParsedTreeObject typedef}
|
2535 | * {@link TreeObject typedef}
|
2536 | * {@link TreeEntry typedef}
|
2537 | *
|
2538 | * ### parsed `'tag'` type
|
2539 | *
|
2540 | * {@link ParsedTagObject typedef}
|
2541 | * {@link TagObject typedef}
|
2542 | *
|
2543 | * @deprecated
|
2544 | * > This command is overly complicated.
|
2545 | * >
|
2546 | * > If you know the type of object you are reading, use [`readBlob`](./readBlob.md), [`readCommit`](./readCommit.md), [`readTag`](./readTag.md), or [`readTree`](./readTree.md).
|
2547 | *
|
2548 | * @param {object} args
|
2549 | * @param {FsClient} args.fs - a file system client
|
2550 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2551 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2552 | * @param {string} args.oid - The SHA-1 object id to get
|
2553 | * @param {'deflated' | 'wrapped' | 'content' | 'parsed'} [args.format = 'parsed'] - What format to return the object in. The choices are described in more detail below.
|
2554 | * @param {string} [args.filepath] - Don't return the object with `oid` itself, but resolve `oid` to a tree and then return the object at that filepath. To return the root directory of a tree set filepath to `''`
|
2555 | * @param {string} [args.encoding] - A convenience argument that only affects blobs. Instead of returning `object` as a buffer, it returns a string parsed using the given encoding.
|
2556 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2557 | *
|
2558 | * @returns {Promise<ReadObjectResult>} Resolves successfully with a git object description
|
2559 | * @see ReadObjectResult
|
2560 | *
|
2561 | * @example
|
2562 | * // Given a ransom SHA-1 object id, figure out what it is
|
2563 | * let { type, object } = await git.readObject({
|
2564 | * fs,
|
2565 | * dir: '/tutorial',
|
2566 | * oid: '0698a781a02264a6f37ba3ff41d78067eaf0f075'
|
2567 | * })
|
2568 | * switch (type) {
|
2569 | * case 'commit': {
|
2570 | * console.log(object)
|
2571 | * break
|
2572 | * }
|
2573 | * case 'tree': {
|
2574 | * console.log(object)
|
2575 | * break
|
2576 | * }
|
2577 | * case 'blob': {
|
2578 | * console.log(object)
|
2579 | * break
|
2580 | * }
|
2581 | * case 'tag': {
|
2582 | * console.log(object)
|
2583 | * break
|
2584 | * }
|
2585 | * }
|
2586 | *
|
2587 | */
|
2588 | export function readObject({ fs: _fs, dir, gitdir, oid, format, filepath, encoding, cache, }: {
|
2589 | fs: CallbackFsClient | PromiseFsClient;
|
2590 | dir?: string;
|
2591 | gitdir?: string;
|
2592 | oid: string;
|
2593 | format?: "parsed" | "deflated" | "content" | "wrapped";
|
2594 | filepath?: string;
|
2595 | encoding?: string;
|
2596 | cache?: any;
|
2597 | }): Promise<ParsedBlobObject | ParsedCommitObject | ParsedTreeObject | ParsedTagObject | DeflatedObject | WrappedObject | RawObject>;
|
2598 | /**
|
2599 | *
|
2600 | * @typedef {Object} ReadTagResult - The object returned has the following schema:
|
2601 | * @property {string} oid - SHA-1 object id of this tag
|
2602 | * @property {TagObject} tag - the parsed tag object
|
2603 | * @property {string} payload - PGP signing payload
|
2604 | */
|
2605 | /**
|
2606 | * Read an annotated tag object directly
|
2607 | *
|
2608 | * @param {object} args
|
2609 | * @param {FsClient} args.fs - a file system client
|
2610 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2611 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2612 | * @param {string} args.oid - The SHA-1 object id to get
|
2613 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2614 | *
|
2615 | * @returns {Promise<ReadTagResult>} Resolves successfully with a git object description
|
2616 | * @see ReadTagResult
|
2617 | * @see TagObject
|
2618 | *
|
2619 | */
|
2620 | export function readTag({ fs, dir, gitdir, oid, cache, }: {
|
2621 | fs: CallbackFsClient | PromiseFsClient;
|
2622 | dir?: string;
|
2623 | gitdir?: string;
|
2624 | oid: string;
|
2625 | cache?: any;
|
2626 | }): Promise<ReadTagResult>;
|
2627 | /**
|
2628 | *
|
2629 | * @typedef {Object} ReadTreeResult - The object returned has the following schema:
|
2630 | * @property {string} oid - SHA-1 object id of this tree
|
2631 | * @property {TreeObject} tree - the parsed tree object
|
2632 | */
|
2633 | /**
|
2634 | * Read a tree object directly
|
2635 | *
|
2636 | * @param {object} args
|
2637 | * @param {FsClient} args.fs - a file system client
|
2638 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2639 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2640 | * @param {string} args.oid - The SHA-1 object id to get. Annotated tags and commits are peeled.
|
2641 | * @param {string} [args.filepath] - Don't return the object with `oid` itself, but resolve `oid` to a tree and then return the tree object at that filepath.
|
2642 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2643 | *
|
2644 | * @returns {Promise<ReadTreeResult>} Resolves successfully with a git tree object
|
2645 | * @see ReadTreeResult
|
2646 | * @see TreeObject
|
2647 | * @see TreeEntry
|
2648 | *
|
2649 | */
|
2650 | export function readTree({ fs, dir, gitdir, oid, filepath, cache, }: {
|
2651 | fs: CallbackFsClient | PromiseFsClient;
|
2652 | dir?: string;
|
2653 | gitdir?: string;
|
2654 | oid: string;
|
2655 | filepath?: string;
|
2656 | cache?: any;
|
2657 | }): Promise<ReadTreeResult>;
|
2658 | /**
|
2659 | * Remove a file from the git index (aka staging area)
|
2660 | *
|
2661 | * Note that this does NOT delete the file in the working directory.
|
2662 | *
|
2663 | * @param {object} args
|
2664 | * @param {FsClient} args.fs - a file system client
|
2665 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2666 | * @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2667 | * @param {string} args.filepath - The path to the file to remove from the index
|
2668 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2669 | *
|
2670 | * @returns {Promise<void>} Resolves successfully once the git index has been updated
|
2671 | *
|
2672 | * @example
|
2673 | * await git.remove({ fs, dir: '/tutorial', filepath: 'README.md' })
|
2674 | * console.log('done')
|
2675 | *
|
2676 | */
|
2677 | export function remove({ fs: _fs, dir, gitdir, filepath, cache, }: {
|
2678 | fs: CallbackFsClient | PromiseFsClient;
|
2679 | dir?: string;
|
2680 | gitdir?: string;
|
2681 | filepath: string;
|
2682 | cache?: any;
|
2683 | }): Promise<void>;
|
2684 | /**
|
2685 | * Remove an object note
|
2686 | *
|
2687 | * @param {object} args
|
2688 | * @param {FsClient} args.fs - a file system client
|
2689 | * @param {SignCallback} [args.onSign] - a PGP signing implementation
|
2690 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2691 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2692 | * @param {string} [args.ref] - The notes ref to look under
|
2693 | * @param {string} args.oid - The SHA-1 object id of the object to remove the note from.
|
2694 | * @param {Object} [args.author] - The details about the author.
|
2695 | * @param {string} [args.author.name] - Default is `user.name` config.
|
2696 | * @param {string} [args.author.email] - Default is `user.email` config.
|
2697 | * @param {number} [args.author.timestamp=Math.floor(Date.now()/1000)] - Set the author timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
2698 | * @param {number} [args.author.timezoneOffset] - Set the author timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
2699 | * @param {Object} [args.committer = author] - The details about the note committer, in the same format as the author parameter. If not specified, the author details are used.
|
2700 | * @param {string} [args.committer.name] - Default is `user.name` config.
|
2701 | * @param {string} [args.committer.email] - Default is `user.email` config.
|
2702 | * @param {number} [args.committer.timestamp=Math.floor(Date.now()/1000)] - Set the committer timestamp field. This is the integer number of seconds since the Unix epoch (1970-01-01 00:00:00).
|
2703 | * @param {number} [args.committer.timezoneOffset] - Set the committer timezone offset field. This is the difference, in minutes, from the current timezone to UTC. Default is `(new Date()).getTimezoneOffset()`.
|
2704 | * @param {string} [args.signingKey] - Sign the tag object using this private PGP key.
|
2705 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2706 | *
|
2707 | * @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the commit object for the note removal.
|
2708 | */
|
2709 | export function removeNote({ fs: _fs, onSign, dir, gitdir, ref, oid, author: _author, committer: _committer, signingKey, cache, }: {
|
2710 | fs: CallbackFsClient | PromiseFsClient;
|
2711 | onSign?: SignCallback;
|
2712 | dir?: string;
|
2713 | gitdir?: string;
|
2714 | ref?: string;
|
2715 | oid: string;
|
2716 | author?: {
|
2717 | name?: string;
|
2718 | email?: string;
|
2719 | timestamp?: number;
|
2720 | timezoneOffset?: number;
|
2721 | };
|
2722 | committer?: {
|
2723 | name?: string;
|
2724 | email?: string;
|
2725 | timestamp?: number;
|
2726 | timezoneOffset?: number;
|
2727 | };
|
2728 | signingKey?: string;
|
2729 | cache?: any;
|
2730 | }): Promise<string>;
|
2731 | /**
|
2732 | * Rename a branch
|
2733 | *
|
2734 | * @param {object} args
|
2735 | * @param {FsClient} args.fs - a file system implementation
|
2736 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2737 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2738 | * @param {string} args.ref - What to name the branch
|
2739 | * @param {string} args.oldref - What the name of the branch was
|
2740 | * @param {boolean} [args.checkout = false] - Update `HEAD` to point at the newly created branch
|
2741 | *
|
2742 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
2743 | *
|
2744 | * @example
|
2745 | * await git.renameBranch({ fs, dir: '/tutorial', ref: 'main', oldref: 'master' })
|
2746 | * console.log('done')
|
2747 | *
|
2748 | */
|
2749 | export function renameBranch({ fs, dir, gitdir, ref, oldref, checkout, }: {
|
2750 | fs: CallbackFsClient | PromiseFsClient;
|
2751 | dir?: string;
|
2752 | gitdir?: string;
|
2753 | ref: string;
|
2754 | oldref: string;
|
2755 | checkout?: boolean;
|
2756 | }): Promise<void>;
|
2757 | /**
|
2758 | * Reset a file in the git index (aka staging area)
|
2759 | *
|
2760 | * Note that this does NOT modify the file in the working directory.
|
2761 | *
|
2762 | * @param {object} args
|
2763 | * @param {FsClient} args.fs - a file system client
|
2764 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2765 | * @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2766 | * @param {string} args.filepath - The path to the file to reset in the index
|
2767 | * @param {string} [args.ref = 'HEAD'] - A ref to the commit to use
|
2768 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2769 | *
|
2770 | * @returns {Promise<void>} Resolves successfully once the git index has been updated
|
2771 | *
|
2772 | * @example
|
2773 | * await git.resetIndex({ fs, dir: '/tutorial', filepath: 'README.md' })
|
2774 | * console.log('done')
|
2775 | *
|
2776 | */
|
2777 | export function resetIndex({ fs: _fs, dir, gitdir, filepath, ref, cache, }: {
|
2778 | fs: CallbackFsClient | PromiseFsClient;
|
2779 | dir?: string;
|
2780 | gitdir?: string;
|
2781 | filepath: string;
|
2782 | ref?: string;
|
2783 | cache?: any;
|
2784 | }): Promise<void>;
|
2785 | /**
|
2786 | * Get the value of a symbolic ref or resolve a ref to its SHA-1 object id
|
2787 | *
|
2788 | * @param {object} args
|
2789 | * @param {FsClient} args.fs - a file system client
|
2790 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2791 | * @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2792 | * @param {string} args.ref - The ref to resolve
|
2793 | * @param {number} [args.depth = undefined] - How many symbolic references to follow before returning
|
2794 | *
|
2795 | * @returns {Promise<string>} Resolves successfully with a SHA-1 object id or the value of a symbolic ref
|
2796 | *
|
2797 | * @example
|
2798 | * let currentCommit = await git.resolveRef({ fs, dir: '/tutorial', ref: 'HEAD' })
|
2799 | * console.log(currentCommit)
|
2800 | * let currentBranch = await git.resolveRef({ fs, dir: '/tutorial', ref: 'HEAD', depth: 2 })
|
2801 | * console.log(currentBranch)
|
2802 | *
|
2803 | */
|
2804 | export function resolveRef({ fs, dir, gitdir, ref, depth, }: {
|
2805 | fs: CallbackFsClient | PromiseFsClient;
|
2806 | dir?: string;
|
2807 | gitdir?: string;
|
2808 | ref: string;
|
2809 | depth?: number;
|
2810 | }): Promise<string>;
|
2811 | /**
|
2812 | * Write an entry to the git config files.
|
2813 | *
|
2814 | * *Caveats:*
|
2815 | * - Currently only the local `$GIT_DIR/config` file can be read or written. However support for the global `~/.gitconfig` and system `$(prefix)/etc/gitconfig` will be added in the future.
|
2816 | * - The current parser does not support the more exotic features of the git-config file format such as `[include]` and `[includeIf]`.
|
2817 | *
|
2818 | * @param {Object} args
|
2819 | * @param {FsClient} args.fs - a file system implementation
|
2820 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
2821 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2822 | * @param {string} args.path - The key of the git config entry
|
2823 | * @param {string | boolean | number | void} args.value - A value to store at that path. (Use `undefined` as the value to delete a config entry.)
|
2824 | * @param {boolean} [args.append = false] - If true, will append rather than replace when setting (use with multi-valued config options).
|
2825 | *
|
2826 | * @returns {Promise<void>} Resolves successfully when operation completed
|
2827 | *
|
2828 | * @example
|
2829 | * // Write config value
|
2830 | * await git.setConfig({
|
2831 | * fs,
|
2832 | * dir: '/tutorial',
|
2833 | * path: 'user.name',
|
2834 | * value: 'Mr. Test'
|
2835 | * })
|
2836 | *
|
2837 | * // Print out config file
|
2838 | * let file = await fs.promises.readFile('/tutorial/.git/config', 'utf8')
|
2839 | * console.log(file)
|
2840 | *
|
2841 | * // Delete a config entry
|
2842 | * await git.setConfig({
|
2843 | * fs,
|
2844 | * dir: '/tutorial',
|
2845 | * path: 'user.name',
|
2846 | * value: undefined
|
2847 | * })
|
2848 | *
|
2849 | * // Print out config file
|
2850 | * file = await fs.promises.readFile('/tutorial/.git/config', 'utf8')
|
2851 | * console.log(file)
|
2852 | */
|
2853 | export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
|
2854 | fs: CallbackFsClient | PromiseFsClient;
|
2855 | dir?: string;
|
2856 | gitdir?: string;
|
2857 | path: string;
|
2858 | value: string | number | boolean | void;
|
2859 | append?: boolean;
|
2860 | }): Promise<void>;
|
2861 | /**
|
2862 | * Tell whether a file has been changed
|
2863 | *
|
2864 | * The possible resolve values are:
|
2865 | *
|
2866 | * | status | description |
|
2867 | * | --------------------- | ------------------------------------------------------------------------------------- |
|
2868 | * | `"ignored"` | file ignored by a .gitignore rule |
|
2869 | * | `"unmodified"` | file unchanged from HEAD commit |
|
2870 | * | `"*modified"` | file has modifications, not yet staged |
|
2871 | * | `"*deleted"` | file has been removed, but the removal is not yet staged |
|
2872 | * | `"*added"` | file is untracked, not yet staged |
|
2873 | * | `"absent"` | file not present in HEAD commit, staging area, or working dir |
|
2874 | * | `"modified"` | file has modifications, staged |
|
2875 | * | `"deleted"` | file has been removed, staged |
|
2876 | * | `"added"` | previously untracked file, staged |
|
2877 | * | `"*unmodified"` | working dir and HEAD commit match, but index differs |
|
2878 | * | `"*absent"` | file not present in working dir or HEAD commit, but present in the index |
|
2879 | * | `"*undeleted"` | file was deleted from the index, but is still in the working dir |
|
2880 | * | `"*undeletemodified"` | file was deleted from the index, but is present with modifications in the working dir |
|
2881 | *
|
2882 | * @param {object} args
|
2883 | * @param {FsClient} args.fs - a file system client
|
2884 | * @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
|
2885 | * @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
2886 | * @param {string} args.filepath - The path to the file to query
|
2887 | * @param {object} [args.cache] - a [cache](cache.md) object
|
2888 | *
|
2889 | * @returns {Promise<'ignored'|'unmodified'|'*modified'|'*deleted'|'*added'|'absent'|'modified'|'deleted'|'added'|'*unmodified'|'*absent'|'*undeleted'|'*undeletemodified'>} Resolves successfully with the file's git status
|
2890 | *
|
2891 | * @example
|
2892 | * let status = await git.status({ fs, dir: '/tutorial', filepath: 'README.md' })
|
2893 | * console.log(status)
|
2894 | *
|
2895 | */
|
2896 | export function status({ fs: _fs, dir, gitdir, filepath, cache, }: {
|
2897 | fs: CallbackFsClient | PromiseFsClient;
|
2898 | dir: string;
|
2899 | gitdir?: string;
|
2900 | filepath: string;
|
2901 | cache?: any;
|
2902 | }): Promise<"modified" | "ignored" | "unmodified" | "*modified" | "*deleted" | "*added" | "absent" | "deleted" | "added" | "*unmodified" | "*absent" | "*undeleted" | "*undeletemodified">;
|
2903 | /**
|
2904 | * Efficiently get the status of multiple files at once.
|
2905 | *
|
2906 | * The returned `StatusMatrix` is admittedly not the easiest format to read.
|
2907 | * However it conveys a large amount of information in dense format that should make it easy to create reports about the current state of the repository;
|
2908 | * without having to do multiple, time-consuming isomorphic-git calls.
|
2909 | * My hope is that the speed and flexibility of the function will make up for the learning curve of interpreting the return value.
|
2910 | *
|
2911 | * ```js live
|
2912 | * // get the status of all the files in 'src'
|
2913 | * let status = await git.statusMatrix({
|
2914 | * fs,
|
2915 | * dir: '/tutorial',
|
2916 | * filter: f => f.startsWith('src/')
|
2917 | * })
|
2918 | * console.log(status)
|
2919 | * ```
|
2920 | *
|
2921 | * ```js live
|
2922 | * // get the status of all the JSON and Markdown files
|
2923 | * let status = await git.statusMatrix({
|
2924 | * fs,
|
2925 | * dir: '/tutorial',
|
2926 | * filter: f => f.endsWith('.json') || f.endsWith('.md')
|
2927 | * })
|
2928 | * console.log(status)
|
2929 | * ```
|
2930 | *
|
2931 | * The result is returned as a 2D array.
|
2932 | * The outer array represents the files and/or blobs in the repo, in alphabetical order.
|
2933 | * The inner arrays describe the status of the file:
|
2934 | * the first value is the filepath, and the next three are integers
|
2935 | * representing the HEAD status, WORKDIR status, and STAGE status of the entry.
|
2936 | *
|
2937 | * ```js
|
2938 | * // example StatusMatrix
|
2939 | * [
|
2940 | * ["a.txt", 0, 2, 0], // new, untracked
|
2941 | * ["b.txt", 0, 2, 2], // added, staged
|
2942 | * ["c.txt", 0, 2, 3], // added, staged, with unstaged changes
|
2943 | * ["d.txt", 1, 1, 1], // unmodified
|
2944 | * ["e.txt", 1, 2, 1], // modified, unstaged
|
2945 | * ["f.txt", 1, 2, 2], // modified, staged
|
2946 | * ["g.txt", 1, 2, 3], // modified, staged, with unstaged changes
|
2947 | * ["h.txt", 1, 0, 1], // deleted, unstaged
|
2948 | * ["i.txt", 1, 0, 0], // deleted, staged
|
2949 | * ]
|
2950 | * ```
|
2951 | *
|
2952 | * - The HEAD status is either absent (0) or present (1).
|
2953 | * - The WORKDIR status is either absent (0), identical to HEAD (1), or different from HEAD (2).
|
2954 | * - The STAGE status is either absent (0), identical to HEAD (1), identical to WORKDIR (2), or different from WORKDIR (3).
|
2955 | *
|
2956 | * ```ts
|
2957 | * type Filename = string
|
2958 | * type HeadStatus = 0 | 1
|
2959 | * type WorkdirStatus = 0 | 1 | 2
|
2960 | * type StageStatus = 0 | 1 | 2 | 3
|
2961 | *
|
2962 | * type StatusRow = [Filename, HeadStatus, WorkdirStatus, StageStatus]
|
2963 | *
|
2964 | * type StatusMatrix = StatusRow[]
|
2965 | * ```
|
2966 | *
|
2967 | * > Think of the natural progression of file modifications as being from HEAD (previous) -> WORKDIR (current) -> STAGE (next).
|
2968 | * > Then HEAD is "version 1", WORKDIR is "version 2", and STAGE is "version 3".
|
2969 | * > Then, imagine a "version 0" which is before the file was created.
|
2970 | * > Then the status value in each column corresponds to the oldest version of the file it is identical to.
|
2971 | * > (For a file to be identical to "version 0" means the file is deleted.)
|
2972 | *
|
2973 | * Here are some examples of queries you can answer using the result:
|
2974 | *
|
2975 | * #### Q: What files have been deleted?
|
2976 | * ```js
|
2977 | * const FILE = 0, WORKDIR = 2
|
2978 | *
|
2979 | * const filenames = (await statusMatrix({ dir }))
|
2980 | * .filter(row => row[WORKDIR] === 0)
|
2981 | * .map(row => row[FILE])
|
2982 | * ```
|
2983 | *
|
2984 | * #### Q: What files have unstaged changes?
|
2985 | * ```js
|
2986 | * const FILE = 0, WORKDIR = 2, STAGE = 3
|
2987 | *
|
2988 | * const filenames = (await statusMatrix({ dir }))
|
2989 | * .filter(row => row[WORKDIR] !== row[STAGE])
|
2990 | * .map(row => row[FILE])
|
2991 | * ```
|
2992 | *
|
2993 | * #### Q: What files have been modified since the last commit?
|
2994 | * ```js
|
2995 | * const FILE = 0, HEAD = 1, WORKDIR = 2
|
2996 | *
|
2997 | * const filenames = (await statusMatrix({ dir }))
|
2998 | * .filter(row => row[HEAD] !== row[WORKDIR])
|
2999 | * .map(row => row[FILE])
|
3000 | * ```
|
3001 | *
|
3002 | * #### Q: What files will NOT be changed if I commit right now?
|
3003 | * ```js
|
3004 | * const FILE = 0, HEAD = 1, STAGE = 3
|
3005 | *
|
3006 | * const filenames = (await statusMatrix({ dir }))
|
3007 | * .filter(row => row[HEAD] === row[STAGE])
|
3008 | * .map(row => row[FILE])
|
3009 | * ```
|
3010 | *
|
3011 | * For reference, here are all possible combinations:
|
3012 | *
|
3013 | * | HEAD | WORKDIR | STAGE | `git status --short` equivalent |
|
3014 | * | ---- | ------- | ----- | ------------------------------- |
|
3015 | * | 0 | 0 | 0 | `` |
|
3016 | * | 0 | 0 | 3 | `AD` |
|
3017 | * | 0 | 2 | 0 | `??` |
|
3018 | * | 0 | 2 | 2 | `A ` |
|
3019 | * | 0 | 2 | 3 | `AM` |
|
3020 | * | 1 | 0 | 0 | `D ` |
|
3021 | * | 1 | 0 | 1 | ` D` |
|
3022 | * | 1 | 0 | 3 | `MD` |
|
3023 | * | 1 | 1 | 0 | `D ` + `??` |
|
3024 | * | 1 | 1 | 1 | `` |
|
3025 | * | 1 | 1 | 3 | `MM` |
|
3026 | * | 1 | 2 | 0 | `D ` + `??` |
|
3027 | * | 1 | 2 | 1 | ` M` |
|
3028 | * | 1 | 2 | 2 | `M ` |
|
3029 | * | 1 | 2 | 3 | `MM` |
|
3030 | *
|
3031 | * @param {object} args
|
3032 | * @param {FsClient} args.fs - a file system client
|
3033 | * @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
|
3034 | * @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
3035 | * @param {string} [args.ref = 'HEAD'] - Optionally specify a different commit to compare against the workdir and stage instead of the HEAD
|
3036 | * @param {string[]} [args.filepaths = ['.']] - Limit the query to the given files and directories
|
3037 | * @param {function(string): boolean} [args.filter] - Filter the results to only those whose filepath matches a function.
|
3038 | * @param {object} [args.cache] - a [cache](cache.md) object
|
3039 | *
|
3040 | * @returns {Promise<Array<StatusRow>>} Resolves with a status matrix, described below.
|
3041 | * @see StatusRow
|
3042 | */
|
3043 | export function statusMatrix({ fs: _fs, dir, gitdir, ref, filepaths, filter, cache, }: {
|
3044 | fs: CallbackFsClient | PromiseFsClient;
|
3045 | dir: string;
|
3046 | gitdir?: string;
|
3047 | ref?: string;
|
3048 | filepaths?: string[];
|
3049 | filter?: (arg0: string) => boolean;
|
3050 | cache?: any;
|
3051 | }): Promise<[string, 0 | 1, 0 | 1 | 2, 0 | 1 | 2 | 3][]>;
|
3052 | /**
|
3053 | * Create a lightweight tag
|
3054 | *
|
3055 | * @param {object} args
|
3056 | * @param {FsClient} args.fs - a file system client
|
3057 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
3058 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
3059 | * @param {string} args.ref - What to name the tag
|
3060 | * @param {string} [args.object = 'HEAD'] - What oid the tag refers to. (Will resolve to oid if value is a ref.) By default, the commit object which is referred by the current `HEAD` is used.
|
3061 | * @param {boolean} [args.force = false] - Instead of throwing an error if a tag named `ref` already exists, overwrite the existing tag.
|
3062 | *
|
3063 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
3064 | *
|
3065 | * @example
|
3066 | * await git.tag({ fs, dir: '/tutorial', ref: 'test-tag' })
|
3067 | * console.log('done')
|
3068 | *
|
3069 | */
|
3070 | export function tag({ fs: _fs, dir, gitdir, ref, object, force, }: {
|
3071 | fs: CallbackFsClient | PromiseFsClient;
|
3072 | dir?: string;
|
3073 | gitdir?: string;
|
3074 | ref: string;
|
3075 | object?: string;
|
3076 | force?: boolean;
|
3077 | }): Promise<void>;
|
3078 | /**
|
3079 | * Return the version number of isomorphic-git
|
3080 | *
|
3081 | * I don't know why you might need this. I added it just so I could check that I was getting
|
3082 | * the correct version of the library and not a cached version.
|
3083 | *
|
3084 | * @returns {string} the version string taken from package.json at publication time
|
3085 | *
|
3086 | * @example
|
3087 | * console.log(git.version())
|
3088 | *
|
3089 | */
|
3090 | export function version(): string;
|
3091 | /**
|
3092 | * @callback WalkerMap
|
3093 | * @param {string} filename
|
3094 | * @param {Array<WalkerEntry | null>} entries
|
3095 | * @returns {Promise<any>}
|
3096 | */
|
3097 | /**
|
3098 | * @callback WalkerReduce
|
3099 | * @param {any} parent
|
3100 | * @param {any[]} children
|
3101 | * @returns {Promise<any>}
|
3102 | */
|
3103 | /**
|
3104 | * @callback WalkerIterateCallback
|
3105 | * @param {WalkerEntry[]} entries
|
3106 | * @returns {Promise<any[]>}
|
3107 | */
|
3108 | /**
|
3109 | * @callback WalkerIterate
|
3110 | * @param {WalkerIterateCallback} walk
|
3111 | * @param {IterableIterator<WalkerEntry[]>} children
|
3112 | * @returns {Promise<any[]>}
|
3113 | */
|
3114 | /**
|
3115 | * A powerful recursive tree-walking utility.
|
3116 | *
|
3117 | * The `walk` API simplifies gathering detailed information about a tree or comparing all the filepaths in two or more trees.
|
3118 | * Trees can be git commits, the working directory, or the or git index (staging area).
|
3119 | * As long as a file or directory is present in at least one of the trees, it will be traversed.
|
3120 | * Entries are traversed in alphabetical order.
|
3121 | *
|
3122 | * The arguments to `walk` are the `trees` you want to traverse, and 3 optional transform functions:
|
3123 | * `map`, `reduce`, and `iterate`.
|
3124 | *
|
3125 | * ## `TREE`, `WORKDIR`, and `STAGE`
|
3126 | *
|
3127 | * Tree walkers are represented by three separate functions that can be imported:
|
3128 | *
|
3129 | * ```js
|
3130 | * import { TREE, WORKDIR, STAGE } from 'isomorphic-git'
|
3131 | * ```
|
3132 | *
|
3133 | * These functions return opaque handles called `Walker`s.
|
3134 | * The only thing that `Walker` objects are good for is passing into `walk`.
|
3135 | * Here are the three `Walker`s passed into `walk` by the `statusMatrix` command for example:
|
3136 | *
|
3137 | * ```js
|
3138 | * let ref = 'HEAD'
|
3139 | *
|
3140 | * let trees = [TREE({ ref }), WORKDIR(), STAGE()]
|
3141 | * ```
|
3142 | *
|
3143 | * For the arguments, see the doc pages for [TREE](./TREE.md), [WORKDIR](./WORKDIR.md), and [STAGE](./STAGE.md).
|
3144 | *
|
3145 | * `map`, `reduce`, and `iterate` allow you control the recursive walk by pruning and transforming `WalkerEntry`s into the desired result.
|
3146 | *
|
3147 | * ## WalkerEntry
|
3148 | *
|
3149 | * {@link WalkerEntry typedef}
|
3150 | *
|
3151 | * `map` receives an array of `WalkerEntry[]` as its main argument, one `WalkerEntry` for each `Walker` in the `trees` argument.
|
3152 | * The methods are memoized per `WalkerEntry` so calling them multiple times in a `map` function does not adversely impact performance.
|
3153 | * By only computing these values if needed, you build can build lean, mean, efficient walking machines.
|
3154 | *
|
3155 | * ### WalkerEntry#type()
|
3156 | *
|
3157 | * Returns the kind as a string. This is normally either `tree` or `blob`.
|
3158 | *
|
3159 | * `TREE`, `STAGE`, and `WORKDIR` walkers all return a string.
|
3160 | *
|
3161 | * Possible values:
|
3162 | *
|
3163 | * - `'tree'` directory
|
3164 | * - `'blob'` file
|
3165 | * - `'special'` used by `WORKDIR` to represent irregular files like sockets and FIFOs
|
3166 | * - `'commit'` used by `TREE` to represent submodules
|
3167 | *
|
3168 | * ```js
|
3169 | * await entry.type()
|
3170 | * ```
|
3171 | *
|
3172 | * ### WalkerEntry#mode()
|
3173 | *
|
3174 | * Returns the file mode as a number. Use this to distinguish between regular files, symlinks, and executable files.
|
3175 | *
|
3176 | * `TREE`, `STAGE`, and `WORKDIR` walkers all return a number for all `type`s of entries.
|
3177 | *
|
3178 | * It has been normalized to one of the 4 values that are allowed in git commits:
|
3179 | *
|
3180 | * - `0o40000` directory
|
3181 | * - `0o100644` file
|
3182 | * - `0o100755` file (executable)
|
3183 | * - `0o120000` symlink
|
3184 | *
|
3185 | * Tip: to make modes more readable, you can print them to octal using `.toString(8)`.
|
3186 | *
|
3187 | * ```js
|
3188 | * await entry.mode()
|
3189 | * ```
|
3190 | *
|
3191 | * ### WalkerEntry#oid()
|
3192 | *
|
3193 | * Returns the SHA-1 object id for blobs and trees.
|
3194 | *
|
3195 | * `TREE` walkers return a string for `blob` and `tree` entries.
|
3196 | *
|
3197 | * `STAGE` and `WORKDIR` walkers return a string for `blob` entries and `undefined` for `tree` entries.
|
3198 | *
|
3199 | * ```js
|
3200 | * await entry.oid()
|
3201 | * ```
|
3202 | *
|
3203 | * ### WalkerEntry#content()
|
3204 | *
|
3205 | * Returns the file contents as a Buffer.
|
3206 | *
|
3207 | * `TREE` and `WORKDIR` walkers return a Buffer for `blob` entries and `undefined` for `tree` entries.
|
3208 | *
|
3209 | * `STAGE` walkers always return `undefined` since the file contents are never stored in the stage.
|
3210 | *
|
3211 | * ```js
|
3212 | * await entry.content()
|
3213 | * ```
|
3214 | *
|
3215 | * ### WalkerEntry#stat()
|
3216 | *
|
3217 | * Returns a normalized subset of filesystem Stat data.
|
3218 | *
|
3219 | * `WORKDIR` walkers return a `Stat` for `blob` and `tree` entries.
|
3220 | *
|
3221 | * `STAGE` walkers return a `Stat` for `blob` entries and `undefined` for `tree` entries.
|
3222 | *
|
3223 | * `TREE` walkers return `undefined` for all entry types.
|
3224 | *
|
3225 | * ```js
|
3226 | * await entry.stat()
|
3227 | * ```
|
3228 | *
|
3229 | * {@link Stat typedef}
|
3230 | *
|
3231 | * ## map(string, Array<WalkerEntry|null>) => Promise<any>
|
3232 | *
|
3233 | * {@link WalkerMap typedef}
|
3234 | *
|
3235 | * This is the function that is called once per entry BEFORE visiting the children of that node.
|
3236 | *
|
3237 | * If you return `null` for a `tree` entry, then none of the children of that `tree` entry will be walked.
|
3238 | *
|
3239 | * This is a good place for query logic, such as examining the contents of a file.
|
3240 | * Ultimately, compare all the entries and return any values you are interested in.
|
3241 | * If you do not return a value (or return undefined) that entry will be filtered from the results.
|
3242 | *
|
3243 | * Example 1: Find all the files containing the word 'foo'.
|
3244 | * ```js
|
3245 | * async function map(filepath, [head, workdir]) {
|
3246 | * let content = (await workdir.content()).toString('utf8')
|
3247 | * if (content.contains('foo')) {
|
3248 | * return {
|
3249 | * filepath,
|
3250 | * content
|
3251 | * }
|
3252 | * }
|
3253 | * }
|
3254 | * ```
|
3255 | *
|
3256 | * Example 2: Return the difference between the working directory and the HEAD commit
|
3257 | * ```js
|
3258 | * const diff = require('diff-lines')
|
3259 | * async function map(filepath, [head, workdir]) {
|
3260 | * return {
|
3261 | * filepath,
|
3262 | * oid: await head.oid(),
|
3263 | * diff: diff((await head.content()).toString('utf8'), (await workdir.content()).toString('utf8'))
|
3264 | * }
|
3265 | * }
|
3266 | * ```
|
3267 | *
|
3268 | * Example 3:
|
3269 | * ```js
|
3270 | * let path = require('path')
|
3271 | * // Only examine files in the directory `cwd`
|
3272 | * let cwd = 'src/app'
|
3273 | * async function map (filepath, [head, workdir, stage]) {
|
3274 | * if (
|
3275 | * // don't skip the root directory
|
3276 | * head.fullpath !== '.' &&
|
3277 | * // return true for 'src' and 'src/app'
|
3278 | * !cwd.startsWith(filepath) &&
|
3279 | * // return true for 'src/app/*'
|
3280 | * path.dirname(filepath) !== cwd
|
3281 | * ) {
|
3282 | * return null
|
3283 | * } else {
|
3284 | * return filepath
|
3285 | * }
|
3286 | * }
|
3287 | * ```
|
3288 | *
|
3289 | * ## reduce(parent, children)
|
3290 | *
|
3291 | * {@link WalkerReduce typedef}
|
3292 | *
|
3293 | * This is the function that is called once per entry AFTER visiting the children of that node.
|
3294 | *
|
3295 | * Default: `async (parent, children) => parent === undefined ? children.flat() : [parent, children].flat()`
|
3296 | *
|
3297 | * The default implementation of this function returns all directories and children in a giant flat array.
|
3298 | * You can define a different accumulation method though.
|
3299 | *
|
3300 | * Example: Return a hierarchical structure
|
3301 | * ```js
|
3302 | * async function reduce (parent, children) {
|
3303 | * return Object.assign(parent, { children })
|
3304 | * }
|
3305 | * ```
|
3306 | *
|
3307 | * ## iterate(walk, children)
|
3308 | *
|
3309 | * {@link WalkerIterate typedef}
|
3310 | *
|
3311 | * {@link WalkerIterateCallback typedef}
|
3312 | *
|
3313 | * Default: `(walk, children) => Promise.all([...children].map(walk))`
|
3314 | *
|
3315 | * The default implementation recurses all children concurrently using Promise.all.
|
3316 | * However you could use a custom function to traverse children serially or use a global queue to throttle recursion.
|
3317 | *
|
3318 | * @param {object} args
|
3319 | * @param {FsClient} args.fs - a file system client
|
3320 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
3321 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
3322 | * @param {Walker[]} args.trees - The trees you want to traverse
|
3323 | * @param {WalkerMap} [args.map] - Transform `WalkerEntry`s into a result form
|
3324 | * @param {WalkerReduce} [args.reduce] - Control how mapped entries are combined with their parent result
|
3325 | * @param {WalkerIterate} [args.iterate] - Fine-tune how entries within a tree are iterated over
|
3326 | * @param {object} [args.cache] - a [cache](cache.md) object
|
3327 | *
|
3328 | * @returns {Promise<any>} The finished tree-walking result
|
3329 | */
|
3330 | export function walk({ fs, dir, gitdir, trees, map, reduce, iterate, cache, }: {
|
3331 | fs: CallbackFsClient | PromiseFsClient;
|
3332 | dir?: string;
|
3333 | gitdir?: string;
|
3334 | trees: Walker[];
|
3335 | map?: WalkerMap;
|
3336 | reduce?: WalkerReduce;
|
3337 | iterate?: WalkerIterate;
|
3338 | cache?: any;
|
3339 | }): Promise<any>;
|
3340 | /**
|
3341 | * Write a blob object directly
|
3342 | *
|
3343 | * @param {object} args
|
3344 | * @param {FsClient} args.fs - a file system client
|
3345 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
3346 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
3347 | * @param {Uint8Array} args.blob - The blob object to write
|
3348 | *
|
3349 | * @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object
|
3350 | *
|
3351 | * @example
|
3352 | * // Manually create a blob.
|
3353 | * let oid = await git.writeBlob({
|
3354 | * fs,
|
3355 | * dir: '/tutorial',
|
3356 | * blob: new Uint8Array([])
|
3357 | * })
|
3358 | *
|
3359 | * console.log('oid', oid) // should be 'e69de29bb2d1d6434b8b29ae775ad8c2e48c5391'
|
3360 | *
|
3361 | */
|
3362 | export function writeBlob({ fs, dir, gitdir, blob }: {
|
3363 | fs: CallbackFsClient | PromiseFsClient;
|
3364 | dir?: string;
|
3365 | gitdir?: string;
|
3366 | blob: Uint8Array;
|
3367 | }): Promise<string>;
|
3368 | /**
|
3369 | * Write a commit object directly
|
3370 | *
|
3371 | * @param {object} args
|
3372 | * @param {FsClient} args.fs - a file system client
|
3373 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
3374 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
3375 | * @param {CommitObject} args.commit - The object to write
|
3376 | *
|
3377 | * @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object
|
3378 | * @see CommitObject
|
3379 | *
|
3380 | */
|
3381 | export function writeCommit({ fs, dir, gitdir, commit, }: {
|
3382 | fs: CallbackFsClient | PromiseFsClient;
|
3383 | dir?: string;
|
3384 | gitdir?: string;
|
3385 | commit: CommitObject;
|
3386 | }): Promise<string>;
|
3387 | /**
|
3388 | * Write a git object directly
|
3389 | *
|
3390 | * `format` can have the following values:
|
3391 | *
|
3392 | * | param | description |
|
3393 | * | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
3394 | * | 'deflated' | Treat `object` as the raw deflate-compressed buffer for an object, meaning can be written to `.git/objects/**` as-is. |
|
3395 | * | 'wrapped' | Treat `object` as the inflated object buffer wrapped in the git object header. This is the raw buffer used when calculating the SHA-1 object id of a git object. |
|
3396 | * | 'content' | Treat `object` as the object buffer without the git header. |
|
3397 | * | 'parsed' | Treat `object` as a parsed representation of the object. |
|
3398 | *
|
3399 | * If `format` is `'parsed'`, then `object` must match one of the schemas for `CommitObject`, `TreeObject`, `TagObject`, or a `string` (for blobs).
|
3400 | *
|
3401 | * {@link CommitObject typedef}
|
3402 | *
|
3403 | * {@link TreeObject typedef}
|
3404 | *
|
3405 | * {@link TagObject typedef}
|
3406 | *
|
3407 | * If `format` is `'content'`, `'wrapped'`, or `'deflated'`, `object` should be a `Uint8Array`.
|
3408 | *
|
3409 | * @deprecated
|
3410 | * > This command is overly complicated.
|
3411 | * >
|
3412 | * > If you know the type of object you are writing, use [`writeBlob`](./writeBlob.md), [`writeCommit`](./writeCommit.md), [`writeTag`](./writeTag.md), or [`writeTree`](./writeTree.md).
|
3413 | *
|
3414 | * @param {object} args
|
3415 | * @param {FsClient} args.fs - a file system client
|
3416 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
3417 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
3418 | * @param {string | Uint8Array | CommitObject | TreeObject | TagObject} args.object - The object to write.
|
3419 | * @param {'blob'|'tree'|'commit'|'tag'} [args.type] - The kind of object to write.
|
3420 | * @param {'deflated' | 'wrapped' | 'content' | 'parsed'} [args.format = 'parsed'] - What format the object is in. The possible choices are listed below.
|
3421 | * @param {string} [args.oid] - If `format` is `'deflated'` then this param is required. Otherwise it is calculated.
|
3422 | * @param {string} [args.encoding] - If `type` is `'blob'` then `object` will be converted to a Uint8Array using `encoding`.
|
3423 | *
|
3424 | * @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object.
|
3425 | *
|
3426 | * @example
|
3427 | * // Manually create an annotated tag.
|
3428 | * let sha = await git.resolveRef({ fs, dir: '/tutorial', ref: 'HEAD' })
|
3429 | * console.log('commit', sha)
|
3430 | *
|
3431 | * let oid = await git.writeObject({
|
3432 | * fs,
|
3433 | * dir: '/tutorial',
|
3434 | * type: 'tag',
|
3435 | * object: {
|
3436 | * object: sha,
|
3437 | * type: 'commit',
|
3438 | * tag: 'my-tag',
|
3439 | * tagger: {
|
3440 | * name: 'your name',
|
3441 | * email: 'email@example.com',
|
3442 | * timestamp: Math.floor(Date.now()/1000),
|
3443 | * timezoneOffset: new Date().getTimezoneOffset()
|
3444 | * },
|
3445 | * message: 'Optional message'
|
3446 | * }
|
3447 | * })
|
3448 | *
|
3449 | * console.log('tag', oid)
|
3450 | *
|
3451 | */
|
3452 | export function writeObject({ fs: _fs, dir, gitdir, type, object, format, oid, encoding, }: {
|
3453 | fs: CallbackFsClient | PromiseFsClient;
|
3454 | dir?: string;
|
3455 | gitdir?: string;
|
3456 | object: string | Uint8Array | TreeEntry[] | CommitObject | TagObject;
|
3457 | type?: "blob" | "tree" | "commit" | "tag";
|
3458 | format?: "parsed" | "deflated" | "content" | "wrapped";
|
3459 | oid?: string;
|
3460 | encoding?: string;
|
3461 | }): Promise<string>;
|
3462 | /**
|
3463 | * Write a ref which refers to the specified SHA-1 object id, or a symbolic ref which refers to the specified ref.
|
3464 | *
|
3465 | * @param {object} args
|
3466 | * @param {FsClient} args.fs - a file system client
|
3467 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
3468 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
3469 | * @param {string} args.ref - The name of the ref to write
|
3470 | * @param {string} args.value - When `symbolic` is false, a ref or an SHA-1 object id. When true, a ref starting with `refs/`.
|
3471 | * @param {boolean} [args.force = false] - Instead of throwing an error if a ref named `ref` already exists, overwrite the existing ref.
|
3472 | * @param {boolean} [args.symbolic = false] - Whether the ref is symbolic or not.
|
3473 | *
|
3474 | * @returns {Promise<void>} Resolves successfully when filesystem operations are complete
|
3475 | *
|
3476 | * @example
|
3477 | * await git.writeRef({
|
3478 | * fs,
|
3479 | * dir: '/tutorial',
|
3480 | * ref: 'refs/heads/another-branch',
|
3481 | * value: 'HEAD'
|
3482 | * })
|
3483 | * await git.writeRef({
|
3484 | * fs,
|
3485 | * dir: '/tutorial',
|
3486 | * ref: 'HEAD',
|
3487 | * value: 'refs/heads/another-branch',
|
3488 | * force: true,
|
3489 | * symbolic: true
|
3490 | * })
|
3491 | * console.log('done')
|
3492 | *
|
3493 | */
|
3494 | export function writeRef({ fs: _fs, dir, gitdir, ref, value, force, symbolic, }: {
|
3495 | fs: CallbackFsClient | PromiseFsClient;
|
3496 | dir?: string;
|
3497 | gitdir?: string;
|
3498 | ref: string;
|
3499 | value: string;
|
3500 | force?: boolean;
|
3501 | symbolic?: boolean;
|
3502 | }): Promise<void>;
|
3503 | /**
|
3504 | * Write an annotated tag object directly
|
3505 | *
|
3506 | * @param {object} args
|
3507 | * @param {FsClient} args.fs - a file system client
|
3508 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
3509 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
3510 | * @param {TagObject} args.tag - The object to write
|
3511 | *
|
3512 | * @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object
|
3513 | * @see TagObject
|
3514 | *
|
3515 | * @example
|
3516 | * // Manually create an annotated tag.
|
3517 | * let sha = await git.resolveRef({ fs, dir: '/tutorial', ref: 'HEAD' })
|
3518 | * console.log('commit', sha)
|
3519 | *
|
3520 | * let oid = await git.writeTag({
|
3521 | * fs,
|
3522 | * dir: '/tutorial',
|
3523 | * tag: {
|
3524 | * object: sha,
|
3525 | * type: 'commit',
|
3526 | * tag: 'my-tag',
|
3527 | * tagger: {
|
3528 | * name: 'your name',
|
3529 | * email: 'email@example.com',
|
3530 | * timestamp: Math.floor(Date.now()/1000),
|
3531 | * timezoneOffset: new Date().getTimezoneOffset()
|
3532 | * },
|
3533 | * message: 'Optional message'
|
3534 | * }
|
3535 | * })
|
3536 | *
|
3537 | * console.log('tag', oid)
|
3538 | *
|
3539 | */
|
3540 | export function writeTag({ fs, dir, gitdir, tag }: {
|
3541 | fs: CallbackFsClient | PromiseFsClient;
|
3542 | dir?: string;
|
3543 | gitdir?: string;
|
3544 | tag: TagObject;
|
3545 | }): Promise<string>;
|
3546 | /**
|
3547 | * Write a tree object directly
|
3548 | *
|
3549 | * @param {object} args
|
3550 | * @param {FsClient} args.fs - a file system client
|
3551 | * @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
|
3552 | * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
|
3553 | * @param {TreeObject} args.tree - The object to write
|
3554 | *
|
3555 | * @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object.
|
3556 | * @see TreeObject
|
3557 | * @see TreeEntry
|
3558 | *
|
3559 | */
|
3560 | export function writeTree({ fs, dir, gitdir, tree }: {
|
3561 | fs: CallbackFsClient | PromiseFsClient;
|
3562 | dir?: string;
|
3563 | gitdir?: string;
|
3564 | tree: TreeEntry[];
|
3565 | }): Promise<string>;
|
3566 | declare class AlreadyExistsError extends BaseError {
|
3567 | /**
|
3568 | * @param {'note'|'remote'|'tag'|'branch'} noun
|
3569 | * @param {string} where
|
3570 | * @param {boolean} canForce
|
3571 | */
|
3572 | constructor(noun: "tag" | "remote" | "note" | "branch", where: string, canForce?: boolean);
|
3573 | code: "AlreadyExistsError";
|
3574 | name: "AlreadyExistsError";
|
3575 | data: {
|
3576 | noun: "tag" | "remote" | "note" | "branch";
|
3577 | where: string;
|
3578 | canForce: boolean;
|
3579 | };
|
3580 | }
|
3581 | declare namespace AlreadyExistsError {
|
3582 | export const code: 'AlreadyExistsError';
|
3583 | }
|
3584 | declare class AmbiguousError extends BaseError {
|
3585 | /**
|
3586 | * @param {'oids'|'refs'} nouns
|
3587 | * @param {string} short
|
3588 | * @param {string[]} matches
|
3589 | */
|
3590 | constructor(nouns: "refs" | "oids", short: string, matches: string[]);
|
3591 | code: "AmbiguousError";
|
3592 | name: "AmbiguousError";
|
3593 | data: {
|
3594 | nouns: "refs" | "oids";
|
3595 | short: string;
|
3596 | matches: string[];
|
3597 | };
|
3598 | }
|
3599 | declare namespace AmbiguousError {
|
3600 | const code_1: 'AmbiguousError';
|
3601 | export { code_1 as code };
|
3602 | }
|
3603 | declare class CheckoutConflictError extends BaseError {
|
3604 | /**
|
3605 | * @param {string[]} filepaths
|
3606 | */
|
3607 | constructor(filepaths: string[]);
|
3608 | code: "CheckoutConflictError";
|
3609 | name: "CheckoutConflictError";
|
3610 | data: {
|
3611 | filepaths: string[];
|
3612 | };
|
3613 | }
|
3614 | declare namespace CheckoutConflictError {
|
3615 | const code_2: 'CheckoutConflictError';
|
3616 | export { code_2 as code };
|
3617 | }
|
3618 | declare class CommitNotFetchedError extends BaseError {
|
3619 | /**
|
3620 | * @param {string} ref
|
3621 | * @param {string} oid
|
3622 | */
|
3623 | constructor(ref: string, oid: string);
|
3624 | code: "CommitNotFetchedError";
|
3625 | name: "CommitNotFetchedError";
|
3626 | data: {
|
3627 | ref: string;
|
3628 | oid: string;
|
3629 | };
|
3630 | }
|
3631 | declare namespace CommitNotFetchedError {
|
3632 | const code_3: 'CommitNotFetchedError';
|
3633 | export { code_3 as code };
|
3634 | }
|
3635 | declare class EmptyServerResponseError extends BaseError {
|
3636 | code: "EmptyServerResponseError";
|
3637 | name: "EmptyServerResponseError";
|
3638 | data: {};
|
3639 | }
|
3640 | declare namespace EmptyServerResponseError {
|
3641 | const code_4: 'EmptyServerResponseError';
|
3642 | export { code_4 as code };
|
3643 | }
|
3644 | declare class FastForwardError extends BaseError {
|
3645 | code: "FastForwardError";
|
3646 | name: "FastForwardError";
|
3647 | data: {};
|
3648 | }
|
3649 | declare namespace FastForwardError {
|
3650 | const code_5: 'FastForwardError';
|
3651 | export { code_5 as code };
|
3652 | }
|
3653 | declare class GitPushError extends BaseError {
|
3654 | /**
|
3655 | * @param {string} prettyDetails
|
3656 | * @param {PushResult} result
|
3657 | */
|
3658 | constructor(prettyDetails: string, result: PushResult);
|
3659 | code: "GitPushError";
|
3660 | name: "GitPushError";
|
3661 | data: {
|
3662 | prettyDetails: string;
|
3663 | result: PushResult;
|
3664 | };
|
3665 | }
|
3666 | declare namespace GitPushError {
|
3667 | const code_6: 'GitPushError';
|
3668 | export { code_6 as code };
|
3669 | }
|
3670 | declare class HttpError extends BaseError {
|
3671 | /**
|
3672 | * @param {number} statusCode
|
3673 | * @param {string} statusMessage
|
3674 | * @param {string} response
|
3675 | */
|
3676 | constructor(statusCode: number, statusMessage: string, response: string);
|
3677 | code: "HttpError";
|
3678 | name: "HttpError";
|
3679 | data: {
|
3680 | statusCode: number;
|
3681 | statusMessage: string;
|
3682 | response: string;
|
3683 | };
|
3684 | }
|
3685 | declare namespace HttpError {
|
3686 | const code_7: 'HttpError';
|
3687 | export { code_7 as code };
|
3688 | }
|
3689 | declare class InternalError extends BaseError {
|
3690 | /**
|
3691 | * @param {string} message
|
3692 | */
|
3693 | constructor(message: string);
|
3694 | code: "InternalError";
|
3695 | name: "InternalError";
|
3696 | data: {
|
3697 | message: string;
|
3698 | };
|
3699 | }
|
3700 | declare namespace InternalError {
|
3701 | const code_8: 'InternalError';
|
3702 | export { code_8 as code };
|
3703 | }
|
3704 | declare class InvalidFilepathError extends BaseError {
|
3705 | /**
|
3706 | * @param {'leading-slash'|'trailing-slash'} [reason]
|
3707 | */
|
3708 | constructor(reason?: "leading-slash" | "trailing-slash" | undefined);
|
3709 | code: "InvalidFilepathError";
|
3710 | name: "InvalidFilepathError";
|
3711 | data: {
|
3712 | reason: "leading-slash" | "trailing-slash" | undefined;
|
3713 | };
|
3714 | }
|
3715 | declare namespace InvalidFilepathError {
|
3716 | const code_9: 'InvalidFilepathError';
|
3717 | export { code_9 as code };
|
3718 | }
|
3719 | declare class InvalidOidError extends BaseError {
|
3720 | /**
|
3721 | * @param {string} value
|
3722 | */
|
3723 | constructor(value: string);
|
3724 | code: "InvalidOidError";
|
3725 | name: "InvalidOidError";
|
3726 | data: {
|
3727 | value: string;
|
3728 | };
|
3729 | }
|
3730 | declare namespace InvalidOidError {
|
3731 | const code_10: 'InvalidOidError';
|
3732 | export { code_10 as code };
|
3733 | }
|
3734 | declare class InvalidRefNameError extends BaseError {
|
3735 | /**
|
3736 | * @param {string} ref
|
3737 | * @param {string} suggestion
|
3738 | * @param {boolean} canForce
|
3739 | */
|
3740 | constructor(ref: string, suggestion: string);
|
3741 | code: "InvalidRefNameError";
|
3742 | name: "InvalidRefNameError";
|
3743 | data: {
|
3744 | ref: string;
|
3745 | suggestion: string;
|
3746 | };
|
3747 | }
|
3748 | declare namespace InvalidRefNameError {
|
3749 | const code_11: 'InvalidRefNameError';
|
3750 | export { code_11 as code };
|
3751 | }
|
3752 | declare class MaxDepthError extends BaseError {
|
3753 | /**
|
3754 | * @param {number} depth
|
3755 | */
|
3756 | constructor(depth: number);
|
3757 | code: "MaxDepthError";
|
3758 | name: "MaxDepthError";
|
3759 | data: {
|
3760 | depth: number;
|
3761 | };
|
3762 | }
|
3763 | declare namespace MaxDepthError {
|
3764 | const code_12: 'MaxDepthError';
|
3765 | export { code_12 as code };
|
3766 | }
|
3767 | declare class MergeNotSupportedError extends BaseError {
|
3768 | code: "MergeNotSupportedError";
|
3769 | name: "MergeNotSupportedError";
|
3770 | data: {};
|
3771 | }
|
3772 | declare namespace MergeNotSupportedError {
|
3773 | const code_13: 'MergeNotSupportedError';
|
3774 | export { code_13 as code };
|
3775 | }
|
3776 | declare class MissingNameError extends BaseError {
|
3777 | /**
|
3778 | * @param {'author'|'committer'|'tagger'} role
|
3779 | */
|
3780 | constructor(role: "author" | "committer" | "tagger");
|
3781 | code: "MissingNameError";
|
3782 | name: "MissingNameError";
|
3783 | data: {
|
3784 | role: "author" | "committer" | "tagger";
|
3785 | };
|
3786 | }
|
3787 | declare namespace MissingNameError {
|
3788 | const code_14: 'MissingNameError';
|
3789 | export { code_14 as code };
|
3790 | }
|
3791 | declare class MissingParameterError extends BaseError {
|
3792 | /**
|
3793 | * @param {string} parameter
|
3794 | */
|
3795 | constructor(parameter: string);
|
3796 | code: "MissingParameterError";
|
3797 | name: "MissingParameterError";
|
3798 | data: {
|
3799 | parameter: string;
|
3800 | };
|
3801 | }
|
3802 | declare namespace MissingParameterError {
|
3803 | const code_15: 'MissingParameterError';
|
3804 | export { code_15 as code };
|
3805 | }
|
3806 | declare class NoRefspecError extends BaseError {
|
3807 | /**
|
3808 | * @param {string} remote
|
3809 | */
|
3810 | constructor(remote: string);
|
3811 | code: "NoRefspecError";
|
3812 | name: "NoRefspecError";
|
3813 | data: {
|
3814 | remote: string;
|
3815 | };
|
3816 | }
|
3817 | declare namespace NoRefspecError {
|
3818 | const code_16: 'NoRefspecError';
|
3819 | export { code_16 as code };
|
3820 | }
|
3821 | declare class NotFoundError extends BaseError {
|
3822 | /**
|
3823 | * @param {string} what
|
3824 | */
|
3825 | constructor(what: string);
|
3826 | code: "NotFoundError";
|
3827 | name: "NotFoundError";
|
3828 | data: {
|
3829 | what: string;
|
3830 | };
|
3831 | }
|
3832 | declare namespace NotFoundError {
|
3833 | const code_17: 'NotFoundError';
|
3834 | export { code_17 as code };
|
3835 | }
|
3836 | declare class ObjectTypeError extends BaseError {
|
3837 | /**
|
3838 | * @param {string} oid
|
3839 | * @param {'blob'|'commit'|'tag'|'tree'} actual
|
3840 | * @param {'blob'|'commit'|'tag'|'tree'} expected
|
3841 | * @param {string} [filepath]
|
3842 | */
|
3843 | constructor(oid: string, actual: "blob" | "tree" | "commit" | "tag", expected: "blob" | "tree" | "commit" | "tag", filepath?: string | undefined);
|
3844 | code: "ObjectTypeError";
|
3845 | name: "ObjectTypeError";
|
3846 | data: {
|
3847 | oid: string;
|
3848 | actual: "blob" | "tree" | "commit" | "tag";
|
3849 | expected: "blob" | "tree" | "commit" | "tag";
|
3850 | filepath: string | undefined;
|
3851 | };
|
3852 | }
|
3853 | declare namespace ObjectTypeError {
|
3854 | const code_18: 'ObjectTypeError';
|
3855 | export { code_18 as code };
|
3856 | }
|
3857 | declare class ParseError extends BaseError {
|
3858 | /**
|
3859 | * @param {string} expected
|
3860 | * @param {string} actual
|
3861 | */
|
3862 | constructor(expected: string, actual: string);
|
3863 | code: "ParseError";
|
3864 | name: "ParseError";
|
3865 | data: {
|
3866 | expected: string;
|
3867 | actual: string;
|
3868 | };
|
3869 | }
|
3870 | declare namespace ParseError {
|
3871 | const code_19: 'ParseError';
|
3872 | export { code_19 as code };
|
3873 | }
|
3874 | declare class PushRejectedError extends BaseError {
|
3875 | /**
|
3876 | * @param {'not-fast-forward'|'tag-exists'} reason
|
3877 | */
|
3878 | constructor(reason: "not-fast-forward" | "tag-exists");
|
3879 | code: "PushRejectedError";
|
3880 | name: "PushRejectedError";
|
3881 | data: {
|
3882 | reason: "not-fast-forward" | "tag-exists";
|
3883 | };
|
3884 | }
|
3885 | declare namespace PushRejectedError {
|
3886 | const code_20: 'PushRejectedError';
|
3887 | export { code_20 as code };
|
3888 | }
|
3889 | declare class RemoteCapabilityError extends BaseError {
|
3890 | /**
|
3891 | * @param {'shallow'|'deepen-since'|'deepen-not'|'deepen-relative'} capability
|
3892 | * @param {'depth'|'since'|'exclude'|'relative'} parameter
|
3893 | */
|
3894 | constructor(capability: "shallow" | "deepen-since" | "deepen-not" | "deepen-relative", parameter: "depth" | "since" | "exclude" | "relative");
|
3895 | code: "RemoteCapabilityError";
|
3896 | name: "RemoteCapabilityError";
|
3897 | data: {
|
3898 | capability: "shallow" | "deepen-since" | "deepen-not" | "deepen-relative";
|
3899 | parameter: "depth" | "since" | "exclude" | "relative";
|
3900 | };
|
3901 | }
|
3902 | declare namespace RemoteCapabilityError {
|
3903 | const code_21: 'RemoteCapabilityError';
|
3904 | export { code_21 as code };
|
3905 | }
|
3906 | declare class SmartHttpError extends BaseError {
|
3907 | /**
|
3908 | * @param {string} preview
|
3909 | * @param {string} response
|
3910 | */
|
3911 | constructor(preview: string, response: string);
|
3912 | code: "SmartHttpError";
|
3913 | name: "SmartHttpError";
|
3914 | data: {
|
3915 | preview: string;
|
3916 | response: string;
|
3917 | };
|
3918 | }
|
3919 | declare namespace SmartHttpError {
|
3920 | const code_22: 'SmartHttpError';
|
3921 | export { code_22 as code };
|
3922 | }
|
3923 | declare class UnknownTransportError extends BaseError {
|
3924 | /**
|
3925 | * @param {string} url
|
3926 | * @param {string} transport
|
3927 | * @param {string} suggestion
|
3928 | */
|
3929 | constructor(url: string, transport: string, suggestion: string);
|
3930 | code: "UnknownTransportError";
|
3931 | name: "UnknownTransportError";
|
3932 | data: {
|
3933 | url: string;
|
3934 | transport: string;
|
3935 | suggestion: string;
|
3936 | };
|
3937 | }
|
3938 | declare namespace UnknownTransportError {
|
3939 | const code_23: 'UnknownTransportError';
|
3940 | export { code_23 as code };
|
3941 | }
|
3942 | declare class UnsafeFilepathError extends BaseError {
|
3943 | /**
|
3944 | * @param {string} filepath
|
3945 | */
|
3946 | constructor(filepath: string);
|
3947 | code: "UnsafeFilepathError";
|
3948 | name: "UnsafeFilepathError";
|
3949 | data: {
|
3950 | filepath: string;
|
3951 | };
|
3952 | }
|
3953 | declare namespace UnsafeFilepathError {
|
3954 | const code_24: 'UnsafeFilepathError';
|
3955 | export { code_24 as code };
|
3956 | }
|
3957 | declare class UrlParseError extends BaseError {
|
3958 | /**
|
3959 | * @param {string} url
|
3960 | */
|
3961 | constructor(url: string);
|
3962 | code: "UrlParseError";
|
3963 | name: "UrlParseError";
|
3964 | data: {
|
3965 | url: string;
|
3966 | };
|
3967 | }
|
3968 | declare namespace UrlParseError {
|
3969 | const code_25: 'UrlParseError';
|
3970 | export { code_25 as code };
|
3971 | }
|
3972 | declare class UserCanceledError extends BaseError {
|
3973 | code: "UserCanceledError";
|
3974 | name: "UserCanceledError";
|
3975 | data: {};
|
3976 | }
|
3977 | declare namespace UserCanceledError {
|
3978 | const code_26: 'UserCanceledError';
|
3979 | export { code_26 as code };
|
3980 | }
|
3981 | /**
|
3982 | * @typedef {Object} GitProgressEvent
|
3983 | * @property {string} phase
|
3984 | * @property {number} loaded
|
3985 | * @property {number} total
|
3986 | */
|
3987 | /**
|
3988 | * @callback ProgressCallback
|
3989 | * @param {GitProgressEvent} progress
|
3990 | * @returns {void | Promise<void>}
|
3991 | */
|
3992 | /**
|
3993 | * @typedef {Object} GitHttpRequest
|
3994 | * @property {string} url - The URL to request
|
3995 | * @property {string} [method='GET'] - The HTTP method to use
|
3996 | * @property {Object<string, string>} [headers={}] - Headers to include in the HTTP request
|
3997 | * @property {AsyncIterableIterator<Uint8Array>} [body] - An async iterator of Uint8Arrays that make up the body of POST requests
|
3998 | * @property {ProgressCallback} [onProgress] - Reserved for future use (emitting `GitProgressEvent`s)
|
3999 | * @property {object} [signal] - Reserved for future use (canceling a request)
|
4000 | */
|
4001 | /**
|
4002 | * @typedef {Object} GitHttpResponse
|
4003 | * @property {string} url - The final URL that was fetched after any redirects
|
4004 | * @property {string} [method] - The HTTP method that was used
|
4005 | * @property {Object<string, string>} [headers] - HTTP response headers
|
4006 | * @property {AsyncIterableIterator<Uint8Array>} [body] - An async iterator of Uint8Arrays that make up the body of the response
|
4007 | * @property {number} statusCode - The HTTP status code
|
4008 | * @property {string} statusMessage - The HTTP status message
|
4009 | */
|
4010 | /**
|
4011 | * @callback HttpFetch
|
4012 | * @param {GitHttpRequest} request
|
4013 | * @returns {Promise<GitHttpResponse>}
|
4014 | */
|
4015 | /**
|
4016 | * @typedef {Object} HttpClient
|
4017 | * @property {HttpFetch} request
|
4018 | */
|
4019 | /**
|
4020 | * A git commit object.
|
4021 | *
|
4022 | * @typedef {Object} CommitObject
|
4023 | * @property {string} message Commit message
|
4024 | * @property {string} tree SHA-1 object id of corresponding file tree
|
4025 | * @property {string[]} parent an array of zero or more SHA-1 object ids
|
4026 | * @property {Object} author
|
4027 | * @property {string} author.name The author's name
|
4028 | * @property {string} author.email The author's email
|
4029 | * @property {number} author.timestamp UTC Unix timestamp in seconds
|
4030 | * @property {number} author.timezoneOffset Timezone difference from UTC in minutes
|
4031 | * @property {Object} committer
|
4032 | * @property {string} committer.name The committer's name
|
4033 | * @property {string} committer.email The committer's email
|
4034 | * @property {number} committer.timestamp UTC Unix timestamp in seconds
|
4035 | * @property {number} committer.timezoneOffset Timezone difference from UTC in minutes
|
4036 | * @property {string} [gpgsig] PGP signature (if present)
|
4037 | */
|
4038 | /**
|
4039 | * An entry from a git tree object. Files are called 'blobs' and directories are called 'trees'.
|
4040 | *
|
4041 | * @typedef {Object} TreeEntry
|
4042 | * @property {string} mode the 6 digit hexadecimal mode
|
4043 | * @property {string} path the name of the file or directory
|
4044 | * @property {string} oid the SHA-1 object id of the blob or tree
|
4045 | * @property {'commit'|'blob'|'tree'} type the type of object
|
4046 | */
|
4047 | /**
|
4048 | * A git tree object. Trees represent a directory snapshot.
|
4049 | *
|
4050 | * @typedef {TreeEntry[]} TreeObject
|
4051 | */
|
4052 | /**
|
4053 | * A git annotated tag object.
|
4054 | *
|
4055 | * @typedef {Object} TagObject
|
4056 | * @property {string} object SHA-1 object id of object being tagged
|
4057 | * @property {'blob' | 'tree' | 'commit' | 'tag'} type the type of the object being tagged
|
4058 | * @property {string} tag the tag name
|
4059 | * @property {Object} tagger
|
4060 | * @property {string} tagger.name the tagger's name
|
4061 | * @property {string} tagger.email the tagger's email
|
4062 | * @property {number} tagger.timestamp UTC Unix timestamp in seconds
|
4063 | * @property {number} tagger.timezoneOffset timezone difference from UTC in minutes
|
4064 | * @property {string} message tag message
|
4065 | * @property {string} [gpgsig] PGP signature (if present)
|
4066 | */
|
4067 | /**
|
4068 | * @typedef {Object} ReadCommitResult
|
4069 | * @property {string} oid - SHA-1 object id of this commit
|
4070 | * @property {CommitObject} commit - the parsed commit object
|
4071 | * @property {string} payload - PGP signing payload
|
4072 | */
|
4073 | /**
|
4074 | * @typedef {Object} ServerRef - This object has the following schema:
|
4075 | * @property {string} ref - The name of the ref
|
4076 | * @property {string} oid - The SHA-1 object id the ref points to
|
4077 | * @property {string} [target] - The target ref pointed to by a symbolic ref
|
4078 | * @property {string} [peeled] - If the oid is the SHA-1 object id of an annotated tag, this is the SHA-1 object id that the annotated tag points to
|
4079 | */
|
4080 | /**
|
4081 | * @typedef Walker
|
4082 | * @property {Symbol} Symbol('GitWalkerSymbol')
|
4083 | */
|
4084 | /**
|
4085 | * Normalized subset of filesystem `stat` data:
|
4086 | *
|
4087 | * @typedef {Object} Stat
|
4088 | * @property {number} ctimeSeconds
|
4089 | * @property {number} ctimeNanoseconds
|
4090 | * @property {number} mtimeSeconds
|
4091 | * @property {number} mtimeNanoseconds
|
4092 | * @property {number} dev
|
4093 | * @property {number} ino
|
4094 | * @property {number} mode
|
4095 | * @property {number} uid
|
4096 | * @property {number} gid
|
4097 | * @property {number} size
|
4098 | */
|
4099 | /**
|
4100 | * The `WalkerEntry` is an interface that abstracts computing many common tree / blob stats.
|
4101 | *
|
4102 | * @typedef {Object} WalkerEntry
|
4103 | * @property {function(): Promise<'tree'|'blob'|'special'|'commit'>} type
|
4104 | * @property {function(): Promise<number>} mode
|
4105 | * @property {function(): Promise<string>} oid
|
4106 | * @property {function(): Promise<Uint8Array|void>} content
|
4107 | * @property {function(): Promise<Stat>} stat
|
4108 | */
|
4109 | /**
|
4110 | * @typedef {Object} CallbackFsClient
|
4111 | * @property {function} readFile - https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback
|
4112 | * @property {function} writeFile - https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback
|
4113 | * @property {function} unlink - https://nodejs.org/api/fs.html#fs_fs_unlink_path_callback
|
4114 | * @property {function} readdir - https://nodejs.org/api/fs.html#fs_fs_readdir_path_options_callback
|
4115 | * @property {function} mkdir - https://nodejs.org/api/fs.html#fs_fs_mkdir_path_mode_callback
|
4116 | * @property {function} rmdir - https://nodejs.org/api/fs.html#fs_fs_rmdir_path_callback
|
4117 | * @property {function} stat - https://nodejs.org/api/fs.html#fs_fs_stat_path_options_callback
|
4118 | * @property {function} lstat - https://nodejs.org/api/fs.html#fs_fs_lstat_path_options_callback
|
4119 | * @property {function} [readlink] - https://nodejs.org/api/fs.html#fs_fs_readlink_path_options_callback
|
4120 | * @property {function} [symlink] - https://nodejs.org/api/fs.html#fs_fs_symlink_target_path_type_callback
|
4121 | * @property {function} [chmod] - https://nodejs.org/api/fs.html#fs_fs_chmod_path_mode_callback
|
4122 | */
|
4123 | /**
|
4124 | * @typedef {Object} PromiseFsClient
|
4125 | * @property {Object} promises
|
4126 | * @property {function} promises.readFile - https://nodejs.org/api/fs.html#fs_fspromises_readfile_path_options
|
4127 | * @property {function} promises.writeFile - https://nodejs.org/api/fs.html#fs_fspromises_writefile_file_data_options
|
4128 | * @property {function} promises.unlink - https://nodejs.org/api/fs.html#fs_fspromises_unlink_path
|
4129 | * @property {function} promises.readdir - https://nodejs.org/api/fs.html#fs_fspromises_readdir_path_options
|
4130 | * @property {function} promises.mkdir - https://nodejs.org/api/fs.html#fs_fspromises_mkdir_path_options
|
4131 | * @property {function} promises.rmdir - https://nodejs.org/api/fs.html#fs_fspromises_rmdir_path
|
4132 | * @property {function} promises.stat - https://nodejs.org/api/fs.html#fs_fspromises_stat_path_options
|
4133 | * @property {function} promises.lstat - https://nodejs.org/api/fs.html#fs_fspromises_lstat_path_options
|
4134 | * @property {function} [promises.readlink] - https://nodejs.org/api/fs.html#fs_fspromises_readlink_path_options
|
4135 | * @property {function} [promises.symlink] - https://nodejs.org/api/fs.html#fs_fspromises_symlink_target_path_type
|
4136 | * @property {function} [promises.chmod] - https://nodejs.org/api/fs.html#fs_fspromises_chmod_path_mode
|
4137 | */
|
4138 | /**
|
4139 | * @typedef {CallbackFsClient | PromiseFsClient} FsClient
|
4140 | */
|
4141 | /**
|
4142 | * @callback MessageCallback
|
4143 | * @param {string} message
|
4144 | * @returns {void | Promise<void>}
|
4145 | */
|
4146 | /**
|
4147 | * @typedef {Object} GitAuth
|
4148 | * @property {string} [username]
|
4149 | * @property {string} [password]
|
4150 | * @property {Object<string, string>} [headers]
|
4151 | * @property {boolean} [cancel] Tells git to throw a `UserCanceledError` (instead of an `HttpError`).
|
4152 | */
|
4153 | /**
|
4154 | * @callback AuthCallback
|
4155 | * @param {string} url
|
4156 | * @param {GitAuth} auth Might have some values if the URL itself originally contained a username or password.
|
4157 | * @returns {GitAuth | void | Promise<GitAuth | void>}
|
4158 | */
|
4159 | /**
|
4160 | * @callback AuthFailureCallback
|
4161 | * @param {string} url
|
4162 | * @param {GitAuth} auth The credentials that failed
|
4163 | * @returns {GitAuth | void | Promise<GitAuth | void>}
|
4164 | */
|
4165 | /**
|
4166 | * @callback AuthSuccessCallback
|
4167 | * @param {string} url
|
4168 | * @param {GitAuth} auth
|
4169 | * @returns {void | Promise<void>}
|
4170 | */
|
4171 | /**
|
4172 | * @typedef {Object} SignParams
|
4173 | * @property {string} payload - a plaintext message
|
4174 | * @property {string} secretKey - an 'ASCII armor' encoded PGP key (technically can actually contain _multiple_ keys)
|
4175 | */
|
4176 | /**
|
4177 | * @callback SignCallback
|
4178 | * @param {SignParams} args
|
4179 | * @return {{signature: string} | Promise<{signature: string}>} - an 'ASCII armor' encoded "detached" signature
|
4180 | */
|
4181 | /**
|
4182 | * @callback WalkerMap
|
4183 | * @param {string} filename
|
4184 | * @param {WalkerEntry[]} entries
|
4185 | * @returns {Promise<any>}
|
4186 | */
|
4187 | /**
|
4188 | * @callback WalkerReduce
|
4189 | * @param {any} parent
|
4190 | * @param {any[]} children
|
4191 | * @returns {Promise<any>}
|
4192 | */
|
4193 | /**
|
4194 | * @callback WalkerIterateCallback
|
4195 | * @param {WalkerEntry[]} entries
|
4196 | * @returns {Promise<any[]>}
|
4197 | */
|
4198 | /**
|
4199 | * @callback WalkerIterate
|
4200 | * @param {WalkerIterateCallback} walk
|
4201 | * @param {IterableIterator<WalkerEntry[]>} children
|
4202 | * @returns {Promise<any[]>}
|
4203 | */
|
4204 | /**
|
4205 | * @typedef {Object} RefUpdateStatus
|
4206 | * @property {boolean} ok
|
4207 | * @property {string} error
|
4208 | */
|
4209 | /**
|
4210 | * @typedef {Object} PushResult
|
4211 | * @property {boolean} ok
|
4212 | * @property {?string} error
|
4213 | * @property {Object<string, RefUpdateStatus>} refs
|
4214 | * @property {Object<string, string>} [headers]
|
4215 | */
|
4216 | /**
|
4217 | * @typedef {0|1} HeadStatus
|
4218 | */
|
4219 | /**
|
4220 | * @typedef {0|1|2} WorkdirStatus
|
4221 | */
|
4222 | /**
|
4223 | * @typedef {0|1|2|3} StageStatus
|
4224 | */
|
4225 | /**
|
4226 | * @typedef {[string, HeadStatus, WorkdirStatus, StageStatus]} StatusRow
|
4227 | */
|
4228 | declare class BaseError extends Error {
|
4229 | constructor(message: any);
|
4230 | caller: string;
|
4231 | toJSON(): {
|
4232 | code: any;
|
4233 | data: any;
|
4234 | caller: string;
|
4235 | message: string;
|
4236 | stack: string | undefined;
|
4237 | };
|
4238 | fromJSON(json: any): BaseError;
|
4239 | get isIsomorphicGitError(): boolean;
|
4240 | }
|