SecurityOps
/
securityos
mirror of https://codeberg.org/berkeley/securityos.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
securityos/node_modules/isomorphic-git/index.d.ts

4528 lines
168 KiB
TypeScript
Raw Normal View History

First commit
2024-09-06 15:32:35 +00:00
export default index;
export type TreeEntry = {
/**
* - the 6 digit hexadecimal mode
*/
mode: string;
/**
* - the name of the file or directory
*/
path: string;
/**
* - the SHA-1 object id of the blob or tree
*/
oid: string;
/**
* - the type of object
*/
type: "blob" | "tree" | "commit";
};
/**
* - The object returned has the following schema:
*/
export type ReadTreeResult = {
/**
* - SHA-1 object id of this tree
*/
oid: string;
/**
* - the parsed tree object
*/
tree: TreeEntry[];
};
/**
* - The object returned has the following schema:
*/
export type FetchResult = {
/**
* - The branch that is cloned if no branch is specified
*/
defaultBranch: string | null;
/**
* - The SHA-1 object id of the fetched head commit
*/
fetchHead: string | null;
/**
* - a textual description of the branch that was fetched
*/
fetchHeadDescription: string | null;
/**
* - The HTTP response headers returned by the git server
*/
headers?: {
[x: string]: string;
};
/**
* - A list of branches that were pruned, if you provided the `prune` parameter
*/
pruned?: string[];
};
/**
* - Returns an object with a schema like this:
*/
export type MergeResult = {
/**
* - The SHA-1 object id that is now at the head of the branch. Absent only if `dryRun` was specified and `mergeCommit` is true.
*/
oid?: string;
/**
* - True if the branch was already merged so no changes were made
*/
alreadyMerged?: boolean;
/**
* - True if it was a fast-forward merge
*/
fastForward?: boolean;
/**
* - True if merge resulted in a merge commit
*/
mergeCommit?: boolean;
/**
* - The SHA-1 object id of the tree resulting from a merge commit
*/
tree?: string;
};
/**
* - The object returned has the following schema:
*/
export type GetRemoteInfoResult = {
/**
* - The list of capabilities returned by the server (part of the Git protocol)
*/
capabilities: string[];
refs?: any;
/**
* - The default branch of the remote
*/
HEAD?: string;
/**
* - The branches on the remote
*/
heads?: {
[x: string]: string;
};
/**
* - The special branches representing pull requests (non-standard)
*/
pull?: {
[x: string]: string;
};
/**
* - The tags on the remote
*/
tags?: {
[x: string]: string;
};
};
/**
* - This object has the following schema:
*/
export type GetRemoteInfo2Result = {
/**
* - Git protocol version the server supports
*/
protocolVersion: 1 | 2;
/**
* - An object of capabilities represented as keys and values
*/
capabilities: {
[x: string]: string | true;
};
/**
* - Server refs (they get returned by protocol version 1 whether you want them or not)
*/
refs?: ServerRef[];
};
/**
* - The object returned has the following schema:
*/
export type HashBlobResult = {
/**
* - The SHA-1 object id
*/
oid: string;
/**
* - The type of the object
*/
type: "blob";
/**
* - The wrapped git object (the thing that is hashed)
*/
object: Uint8Array;
/**
* - The format of the object
*/
format: "wrapped";
};
/**
* - This object has the following schema:
*/
export type ServerRef = {
/**
* - The name of the ref
*/
ref: string;
/**
* - The SHA-1 object id the ref points to
*/
oid: string;
/**
* - The target ref pointed to by a symbolic ref
*/
target?: string;
/**
* - 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
*/
peeled?: string;
};
/**
* The packObjects command returns an object with two properties:
*/
export type PackObjectsResult = {
/**
* - The suggested filename for the packfile if you want to save it to disk somewhere. It includes the packfile SHA.
*/
filename: string;
/**
* - The packfile contents. Not present if `write` parameter was true, in which case the packfile was written straight to disk.
*/
packfile?: Uint8Array;
};
/**
* - The object returned has the following schema:
*/
export type ReadBlobResult = {
oid: string;
blob: Uint8Array;
};
export type DeflatedObject = {
oid: string;
type: "deflated";
format: "deflated";
object: Uint8Array;
source?: string;
};
export type WrappedObject = {
oid: string;
type: "wrapped";
format: "wrapped";
object: Uint8Array;
source?: string;
};
export type RawObject = {
oid: string;
type: "blob" | "tree" | "commit" | "tag";
format: "content";
object: Uint8Array;
source?: string;
};
export type ParsedBlobObject = {
oid: string;
type: "blob";
format: "parsed";
object: string;
source?: string;
};
export type ParsedCommitObject = {
oid: string;
type: "commit";
format: "parsed";
object: CommitObject;
source?: string;
};
export type ParsedTreeObject = {
oid: string;
type: "tree";
format: "parsed";
object: TreeEntry[];
source?: string;
};
export type ParsedTagObject = {
oid: string;
type: "tag";
format: "parsed";
object: TagObject;
source?: string;
};
export type ParsedObject = ParsedBlobObject | ParsedCommitObject | ParsedTreeObject | ParsedTagObject;
export type ReadObjectResult = ParsedBlobObject | ParsedCommitObject | ParsedTreeObject | ParsedTagObject | DeflatedObject | WrappedObject | RawObject;
/**
* - The object returned has the following schema:
*/
export type ReadTagResult = {
/**
* - SHA-1 object id of this tag
*/
oid: string;
/**
* - the parsed tag object
*/
tag: TagObject;
/**
* - PGP signing payload
*/
payload: string;
};
export type WalkerMap = (filename: string, entries: (WalkerEntry | null)[]) => Promise<any>;
export type WalkerReduce = (parent: any, children: any[]) => Promise<any>;
export type WalkerIterateCallback = (entries: WalkerEntry[]) => Promise<any[]>;
export type WalkerIterate = (walk: WalkerIterateCallback, children: any) => Promise<any[]>;
export type GitProgressEvent = {
phase: string;
loaded: number;
total: number;
};
export type ProgressCallback = (progress: GitProgressEvent) => void | Promise<void>;
export type GitHttpRequest = {
/**
* - The URL to request
*/
url: string;
/**
* - The HTTP method to use
*/
method?: string;
/**
* - Headers to include in the HTTP request
*/
headers?: {
[x: string]: string;
};
/**
* - An HTTP or HTTPS agent that manages connections for the HTTP client (Node.js only)
*/
agent?: any;
/**
* - An async iterator of Uint8Arrays that make up the body of POST requests
*/
body?: any;
/**
* - Reserved for future use (emitting `GitProgressEvent`s)
*/
onProgress?: ProgressCallback;
/**
* - Reserved for future use (canceling a request)
*/
signal?: any;
};
export type GitHttpResponse = {
/**
* - The final URL that was fetched after any redirects
*/
url: string;
/**
* - The HTTP method that was used
*/
method?: string;
/**
* - HTTP response headers
*/
headers?: {
[x: string]: string;
};
/**
* - An async iterator of Uint8Arrays that make up the body of the response
*/
body?: any;
/**
* - The HTTP status code
*/
statusCode: number;
/**
* - The HTTP status message
*/
statusMessage: string;
};
export type HttpFetch = (request: GitHttpRequest) => Promise<GitHttpResponse>;
export type HttpClient = {
request: HttpFetch;
};
/**
* A git commit object.
*/
export type CommitObject = {
/**
* Commit message
*/
message: string;
/**
* SHA-1 object id of corresponding file tree
*/
tree: string;
/**
* an array of zero or more SHA-1 object ids
*/
parent: string[];
author: {
/**
* The author's name
*/
name: string;
/**
* The author's email
*/
email: string;
/**
* UTC Unix timestamp in seconds
*/
timestamp: number;
/**
* Timezone difference from UTC in minutes
*/
timezoneOffset: number;
};
committer: {
/**
* The committer's name
*/
name: string;
/**
* The committer's email
*/
email: string;
/**
* UTC Unix timestamp in seconds
*/
timestamp: number;
/**
* Timezone difference from UTC in minutes
*/
timezoneOffset: number;
};
/**
* PGP signature (if present)
*/
gpgsig?: string;
};
/**
* A git tree object. Trees represent a directory snapshot.
*/
export type TreeObject = TreeEntry[];
/**
* A git annotated tag object.
*/
export type TagObject = {
/**
* SHA-1 object id of object being tagged
*/
object: string;
/**
* the type of the object being tagged
*/
type: "blob" | "tree" | "commit" | "tag";
/**
* the tag name
*/
tag: string;
tagger: {
/**
* the tagger's name
*/
name: string;
/**
* the tagger's email
*/
email: string;
/**
* UTC Unix timestamp in seconds
*/
timestamp: number;
/**
* timezone difference from UTC in minutes
*/
timezoneOffset: number;
};
/**
* tag message
*/
message: string;
/**
* PGP signature (if present)
*/
gpgsig?: string;
};
export type ReadCommitResult = {
/**
* - SHA-1 object id of this commit
*/
oid: string;
/**
* - the parsed commit object
*/
commit: CommitObject;
/**
* - PGP signing payload
*/
payload: string;
};
export type Walker = {
/**
* ('GitWalkerSymbol')
*/
Symbol: Symbol;
};
/**
* Normalized subset of filesystem `stat` data:
*/
export type Stat = {
ctimeSeconds: number;
ctimeNanoseconds: number;
mtimeSeconds: number;
mtimeNanoseconds: number;
dev: number;
ino: number;
mode: number;
uid: number;
gid: number;
size: number;
};
/**
* The `WalkerEntry` is an interface that abstracts computing many common tree / blob stats.
*/
export type WalkerEntry = {
type: () => Promise<"blob" | "tree" | "commit" | "special">;
mode: () => Promise<number>;
oid: () => Promise<string>;
content: () => Promise<void | Uint8Array>;
stat: () => Promise<Stat>;
};
export type CallbackFsClient = {
/**
* - https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback
*/
readFile: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback
*/
writeFile: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_unlink_path_callback
*/
unlink: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_readdir_path_options_callback
*/
readdir: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_mkdir_path_mode_callback
*/
mkdir: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_rmdir_path_callback
*/
rmdir: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_stat_path_options_callback
*/
stat: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_lstat_path_options_callback
*/
lstat: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_readlink_path_options_callback
*/
readlink?: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_symlink_target_path_type_callback
*/
symlink?: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fs_chmod_path_mode_callback
*/
chmod?: Function;
};
export type PromiseFsClient = {
promises: {
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_readfile_path_options
*/
readFile: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_writefile_file_data_options
*/
writeFile: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_unlink_path
*/
unlink: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_readdir_path_options
*/
readdir: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_mkdir_path_options
*/
mkdir: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_rmdir_path
*/
rmdir: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_stat_path_options
*/
stat: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_lstat_path_options
*/
lstat: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_readlink_path_options
*/
readlink?: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_symlink_target_path_type
*/
symlink?: Function;
/**
* - https://nodejs.org/api/fs.html#fs_fspromises_chmod_path_mode
*/
chmod?: Function;
};
};
export type FsClient = CallbackFsClient | PromiseFsClient;
export type MessageCallback = (message: string) => void | Promise<void>;
export type GitAuth = {
username?: string;
password?: string;
headers?: {
[x: string]: string;
};
/**
* Tells git to throw a `UserCanceledError` (instead of an `HttpError`).
*/
cancel?: boolean;
};
export type AuthCallback = (url: string, auth: GitAuth) => void | GitAuth | Promise<void | GitAuth>;
export type AuthFailureCallback = (url: string, auth: GitAuth) => void | GitAuth | Promise<void | GitAuth>;
export type AuthSuccessCallback = (url: string, auth: GitAuth) => void | Promise<void>;
export type SignParams = {
/**
* - a plaintext message
*/
payload: string;
/**
* - an 'ASCII armor' encoded PGP key (technically can actually contain _multiple_ keys)
*/
secretKey: string;
};
export type SignCallback = (args: SignParams) => {
signature: string;
} | Promise<{
signature: string;
}>;
export type MergeDriverParams = {
branches: string[];
contents: string[];
path: string;
};
export type MergeDriverCallback = (args: MergeDriverParams) => {
cleanMerge: boolean;
mergedText: string;
} | Promise<{
cleanMerge: boolean;
mergedText: string;
}>;
export type RefUpdateStatus = {
ok: boolean;
error: string;
};
export type PushResult = {
ok: boolean;
error: string | null;
refs: {
[x: string]: RefUpdateStatus;
};
headers?: {
[x: string]: string;
};
};
export type HeadStatus = 0 | 1;
export type WorkdirStatus = 0 | 1 | 2;
export type StageStatus = 0 | 1 | 2 | 3;
export type StatusRow = [string, 0 | 1, 0 | 1 | 2, 0 | 1 | 2 | 3];
export type types = number;
declare namespace index {
export { Errors };
export { STAGE };
export { TREE };
export { WORKDIR };
export { add };
export { abortMerge };
export { addNote };
export { addRemote };
export { annotatedTag };
export { branch };
export { checkout };
export { clone };
export { commit };
export { getConfig };
export { getConfigAll };
export { setConfig };
export { currentBranch };
export { deleteBranch };
export { deleteRef };
export { deleteRemote };
export { deleteTag };
export { expandOid };
export { expandRef };
export { fastForward };
export { fetch };
export { findMergeBase };
export { findRoot };
export { getRemoteInfo };
export { getRemoteInfo2 };
export { hashBlob };
export { indexPack };
export { init };
export { isDescendent };
export { isIgnored };
export { listBranches };
export { listFiles };
export { listNotes };
export { listRemotes };
export { listServerRefs };
export { listTags };
export { log };
export { merge };
export { packObjects };
export { pull };
export { push };
export { readBlob };
export { readCommit };
export { readNote };
export { readObject };
export { readTag };
export { readTree };
export { remove };
export { removeNote };
export { renameBranch };
export { resetIndex };
export { updateIndex };
export { resolveRef };
export { status };
export { statusMatrix };
export { tag };
export { version };
export { walk };
export { writeBlob };
export { writeCommit };
export { writeObject };
export { writeRef };
export { writeTag };
export { writeTree };
}
export var Errors: Readonly<{
__proto__: null;
AlreadyExistsError: typeof AlreadyExistsError;
AmbiguousError: typeof AmbiguousError;
CheckoutConflictError: typeof CheckoutConflictError;
CommitNotFetchedError: typeof CommitNotFetchedError;
EmptyServerResponseError: typeof EmptyServerResponseError;
FastForwardError: typeof FastForwardError;
GitPushError: typeof GitPushError;
HttpError: typeof HttpError;
InternalError: typeof InternalError;
InvalidFilepathError: typeof InvalidFilepathError;
InvalidOidError: typeof InvalidOidError;
InvalidRefNameError: typeof InvalidRefNameError;
MaxDepthError: typeof MaxDepthError;
MergeNotSupportedError: typeof MergeNotSupportedError;
MergeConflictError: typeof MergeConflictError;
MissingNameError: typeof MissingNameError;
MissingParameterError: typeof MissingParameterError;
MultipleGitError: typeof MultipleGitError;
NoRefspecError: typeof NoRefspecError;
NotFoundError: typeof NotFoundError;
ObjectTypeError: typeof ObjectTypeError;
ParseError: typeof ParseError;
PushRejectedError: typeof PushRejectedError;
RemoteCapabilityError: typeof RemoteCapabilityError;
SmartHttpError: typeof SmartHttpError;
UnknownTransportError: typeof UnknownTransportError;
UnsafeFilepathError: typeof UnsafeFilepathError;
UrlParseError: typeof UrlParseError;
UserCanceledError: typeof UserCanceledError;
UnmergedPathsError: typeof UnmergedPathsError;
IndexResetError: typeof IndexResetError;
}>;
/**
* @returns {Walker}
*/
export function STAGE(): Walker;
/**
* @param {object} args
* @param {string} [args.ref='HEAD']
* @returns {Walker}
*/
export function TREE({ ref }?: {
ref?: string;
}): Walker;
/**
* @returns {Walker}
*/
export function WORKDIR(): Walker;
/**
* Abort a merge in progress.
*
* Based on the behavior of git reset --merge, i.e. "Resets the index and updates the files in the working tree that are different between <commit> and HEAD, but keeps those which are different between the index and working tree (i.e. which have changes which have not been added). If a file that is different between <commit> and the index has unstaged changes, reset is aborted."
*
* Essentially, abortMerge will reset any files affected by merge conflicts to their last known good version at HEAD.
* Any unstaged changes are saved and any staged changes are reset as well.
*
* NOTE: The behavior of this command differs slightly from canonical git in that an error will be thrown if a file exists in the index and nowhere else.
* Canonical git will reset the file and continue aborting the merge in this case.
*
* **WARNING:** Running git merge with non-trivial uncommitted changes is discouraged: while possible, it may leave you in a state that is hard to back out of in the case of a conflict.
* If there were uncommitted changes when the merge started (and especially if those changes were further modified after the merge was started), `git.abortMerge` will in some cases be unable to reconstruct the original (pre-merge) changes.
*
* @param {object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.commit='HEAD'] - commit to reset the index and worktree to, defaults to HEAD
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<void>} Resolves successfully once the git index has been updated
*
*/
export function abortMerge({ fs: _fs, dir, gitdir, commit, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir: string;
gitdir?: string;
commit?: string;
cache?: any;
}): Promise<void>;
/**
* Add a file to the git index (aka staging area)
*
* @param {object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string|string[]} args.filepath - The path to the file to add to the index
* @param {object} [args.cache] - a [cache](cache.md) object
* @param {boolean} [args.force=false] - add to index even if matches gitignore. Think `git add --force`
* @param {boolean} [args.parallel=false] - process each input file in parallel. Parallel processing will result in more memory consumption but less process time
*
* @returns {Promise<void>} Resolves successfully once the git index has been updated
*
* @example
* await fs.promises.writeFile('/tutorial/README.md', `# TEST`)
* await git.add({ fs, dir: '/tutorial', filepath: 'README.md' })
* console.log('done')
*
*/
export function add({ fs: _fs, dir, gitdir, filepath, cache, force, parallel, }: {
fs: CallbackFsClient | PromiseFsClient;
dir: string;
gitdir?: string;
filepath: string | string[];
cache?: any;
force?: boolean;
parallel?: boolean;
}): Promise<void>;
/**
* Add or update an object note
*
* @param {object} args
* @param {FsClient} args.fs - a file system implementation
* @param {SignCallback} [args.onSign] - a PGP signing implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ref] - The notes ref to look under
* @param {string} args.oid - The SHA-1 object id of the object to add the note to.
* @param {string|Uint8Array} args.note - The note to add
* @param {boolean} [args.force] - Over-write note if it already exists.
* @param {Object} [args.author] - The details about the author.
* @param {string} [args.author.name] - Default is `user.name` config.
* @param {string} [args.author.email] - Default is `user.email` config.
* @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).
* @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()`.
* @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.
* @param {string} [args.committer.name] - Default is `user.name` config.
* @param {string} [args.committer.email] - Default is `user.email` config.
* @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).
* @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()`.
* @param {string} [args.signingKey] - Sign the note commit using this private PGP key.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the commit object for the added note.
*/
export function addNote({ fs: _fs, onSign, dir, gitdir, ref, oid, note, force, author: _author, committer: _committer, signingKey, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
onSign?: SignCallback;
dir?: string;
gitdir?: string;
ref?: string;
oid: string;
note: string | Uint8Array;
force?: boolean;
author?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
committer?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
signingKey?: string;
cache?: any;
}): Promise<string>;
/**
* Add or update a remote
*
* @param {object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.remote - The name of the remote
* @param {string} args.url - The URL of the remote
* @param {boolean} [args.force = false] - Instead of throwing an error if a remote named `remote` already exists, overwrite the existing remote.
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.addRemote({
* fs,
* dir: '/tutorial',
* remote: 'upstream',
* url: 'https://github.com/isomorphic-git/isomorphic-git'
* })
* console.log('done')
*
*/
export function addRemote({ fs, dir, gitdir, remote, url, force, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
remote: string;
url: string;
force?: boolean;
}): Promise<void>;
/**
* Create an annotated tag.
*
* @param {object} args
* @param {FsClient} args.fs - a file system implementation
* @param {SignCallback} [args.onSign] - a PGP signing implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - What to name the tag
* @param {string} [args.message = ref] - The tag message to use.
* @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.
* @param {object} [args.tagger] - The details about the tagger.
* @param {string} [args.tagger.name] - Default is `user.name` config.
* @param {string} [args.tagger.email] - Default is `user.email` config.
* @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).
* @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()`.
* @param {string} [args.gpgsig] - The gpgsig attached to the tag object. (Mutually exclusive with the `signingKey` option.)
* @param {string} [args.signingKey] - Sign the tag object using this private PGP key. (Mutually exclusive with the `gpgsig` option.)
* @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.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.annotatedTag({
* fs,
* dir: '/tutorial',
* ref: 'test-tag',
* message: 'This commit is awesome',
* tagger: {
* name: 'Mr. Test',
* email: 'mrtest@example.com'
* }
* })
* console.log('done')
*
*/
export function annotatedTag({ fs: _fs, onSign, dir, gitdir, ref, tagger: _tagger, message, gpgsig, object, signingKey, force, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
onSign?: SignCallback;
dir?: string;
gitdir?: string;
ref: string;
message?: string;
object?: string;
tagger?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
gpgsig?: string;
signingKey?: string;
force?: boolean;
cache?: any;
}): Promise<void>;
/**
* Create a branch
*
* @param {object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - What to name the branch
* @param {string} [args.object = 'HEAD'] - What oid to use as the start point. Accepts a symbolic ref.
* @param {boolean} [args.checkout = false] - Update `HEAD` to point at the newly created branch
* @param {boolean} [args.force = false] - Instead of throwing an error if a branched named `ref` already exists, overwrite the existing branch.
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.branch({ fs, dir: '/tutorial', ref: 'develop' })
* console.log('done')
*
*/
export function branch({ fs, dir, gitdir, ref, object, checkout, force, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref: string;
object?: string;
checkout?: boolean;
force?: boolean;
}): Promise<void>;
/**
* Checkout a branch
*
* 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.
*
* @param {object} args
* @param {FsClient} args.fs - a file system implementation
* @param {ProgressCallback} [args.onProgress] - optional progress event callback
* @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ref = 'HEAD'] - Source to checkout files from
* @param {string[]} [args.filepaths] - Limit the checkout to the given files and directories
* @param {string} [args.remote = 'origin'] - Which remote repository to use
* @param {boolean} [args.noCheckout = false] - If true, will update HEAD but won't update the working directory
* @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.
* @param {boolean} [args.dryRun = false] - If true, simulates a checkout so you can test whether it would succeed.
* @param {boolean} [args.force = false] - If true, conflicts will be ignored and files will be overwritten regardless of local changes.
* @param {boolean} [args.track = true] - If false, will not set the remote branch tracking information. Defaults to true.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* // switch to the main branch
* await git.checkout({
* fs,
* dir: '/tutorial',
* ref: 'main'
* })
* console.log('done')
*
* @example
* // restore the 'docs' and 'src/docs' folders to the way they were, overwriting any changes
* await git.checkout({
* fs,
* dir: '/tutorial',
* force: true,
* filepaths: ['docs', 'src/docs']
* })
* console.log('done')
*
* @example
* // restore the 'docs' and 'src/docs' folders to the way they are in the 'develop' branch, overwriting any changes
* await git.checkout({
* fs,
* dir: '/tutorial',
* ref: 'develop',
* noUpdateHead: true,
* force: true,
* filepaths: ['docs', 'src/docs']
* })
* console.log('done')
*/
export function checkout({ fs, onProgress, dir, gitdir, remote, ref: _ref, filepaths, noCheckout, noUpdateHead, dryRun, force, track, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
onProgress?: ProgressCallback;
dir: string;
gitdir?: string;
ref?: string;
filepaths?: string[];
remote?: string;
noCheckout?: boolean;
noUpdateHead?: boolean;
dryRun?: boolean;
force?: boolean;
track?: boolean;
cache?: any;
}): Promise<void>;
/**
* Clone a repository
*
* @param {object} args
* @param {FsClient} args.fs - a file system implementation
* @param {HttpClient} args.http - an HTTP client
* @param {ProgressCallback} [args.onProgress] - optional progress event callback
* @param {MessageCallback} [args.onMessage] - optional message event callback
* @param {AuthCallback} [args.onAuth] - optional auth fill callback
* @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
* @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
* @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.url - The URL of the remote repository
* @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.
* @param {string} [args.ref] - Which branch to checkout. By default this is the designated "main branch" of the repository.
* @param {boolean} [args.singleBranch = false] - Instead of the default behavior of fetching all the branches, only fetch a single branch.
* @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.
* @param {boolean} [args.noTags = false] - By default clone will fetch all tags. `noTags` disables that behavior.
* @param {string} [args.remote = 'origin'] - What to name the remote that is created.
* @param {number} [args.depth] - Integer. Determines how much of the git repository's history to retrieve
* @param {Date} [args.since] - Only fetch commits created after the given date. Mutually exclusive with `depth`.
* @param {string[]} [args.exclude = []] - A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs.
* @param {boolean} [args.relative = false] - Changes the meaning of `depth` to be measured from the current shallow depth rather than from the branch tip.
* @param {Object<string, string>} [args.headers = {}] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<void>} Resolves successfully when clone completes
*
* @example
* await git.clone({
* fs,
* http,
* dir: '/tutorial',
* corsProxy: 'https://cors.isomorphic-git.org',
* url: 'https://github.com/isomorphic-git/isomorphic-git',
* singleBranch: true,
* depth: 1
* })
* console.log('done')
*
*/
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, }: {
fs: CallbackFsClient | PromiseFsClient;
http: HttpClient;
onProgress?: ProgressCallback;
onMessage?: MessageCallback;
onAuth?: AuthCallback;
onAuthFailure?: AuthFailureCallback;
onAuthSuccess?: AuthSuccessCallback;
dir: string;
gitdir?: string;
url: string;
corsProxy?: string;
ref?: string;
singleBranch?: boolean;
noCheckout?: boolean;
noTags?: boolean;
remote?: string;
depth?: number;
since?: Date;
exclude?: string[];
relative?: boolean;
headers?: {
[x: string]: string;
};
cache?: any;
}): Promise<void>;
/**
* Create a new commit
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {SignCallback} [args.onSign] - a PGP signing implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.message - The commit message to use.
* @param {Object} [args.author] - The details about the author.
* @param {string} [args.author.name] - Default is `user.name` config.
* @param {string} [args.author.email] - Default is `user.email` config.
* @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).
* @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()`.
* @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.
* @param {string} [args.committer.name] - Default is `user.name` config.
* @param {string} [args.committer.email] - Default is `user.email` config.
* @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).
* @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()`.
* @param {string} [args.signingKey] - Sign the tag object using this private PGP key.
* @param {boolean} [args.dryRun = false] - If true, simulates making a commit so you can test whether it would succeed. Implies `noUpdateBranch`.
* @param {boolean} [args.noUpdateBranch = false] - If true, does not update the branch pointer after creating the commit.
* @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.)
* @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.
* @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.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly created commit.
*
* @example
* let sha = await git.commit({
* fs,
* dir: '/tutorial',
* author: {
* name: 'Mr. Test',
* email: 'mrtest@example.com',
* },
* message: 'Added the a.txt file'
* })
* console.log(sha)
*
*/
export function commit({ fs: _fs, onSign, dir, gitdir, message, author: _author, committer: _committer, signingKey, dryRun, noUpdateBranch, ref, parent, tree, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
onSign?: SignCallback;
dir?: string;
gitdir?: string;
message: string;
author?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
committer?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
signingKey?: string;
dryRun?: boolean;
noUpdateBranch?: boolean;
ref?: string;
parent?: string[];
tree?: string;
cache?: any;
}): Promise<string>;
/**
* Get the name of the branch currently pointed to by .git/HEAD
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {boolean} [args.fullname = false] - Return the full path (e.g. "refs/heads/main") instead of the abbreviated form.
* @param {boolean} [args.test = false] - If the current branch doesn't actually exist (such as right after git init) then return `undefined`.
*
* @returns {Promise<string|void>} The name of the current branch or undefined if the HEAD is detached.
*
* @example
* // Get the current branch name
* let branch = await git.currentBranch({
* fs,
* dir: '/tutorial',
* fullname: false
* })
* console.log(branch)
*
*/
export function currentBranch({ fs, dir, gitdir, fullname, test, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
fullname?: boolean;
test?: boolean;
}): Promise<string | void>;
/**
* Delete a local branch
*
* > Note: This only deletes loose branches - it should be fixed in the future to delete packed branches as well.
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - The branch to delete
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.deleteBranch({ fs, dir: '/tutorial', ref: 'local-branch' })
* console.log('done')
*
*/
export function deleteBranch({ fs, dir, gitdir, ref, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref: string;
}): Promise<void>;
/**
* Delete a local ref
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - The ref to delete
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.deleteRef({ fs, dir: '/tutorial', ref: 'refs/tags/test-tag' })
* console.log('done')
*
*/
export function deleteRef({ fs, dir, gitdir, ref }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref: string;
}): Promise<void>;
/**
* Removes the local config entry for a given remote
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.remote - The name of the remote to delete
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.deleteRemote({ fs, dir: '/tutorial', remote: 'upstream' })
* console.log('done')
*
*/
export function deleteRemote({ fs, dir, gitdir, remote, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
remote: string;
}): Promise<void>;
/**
* Delete a local tag ref
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - The tag to delete
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.deleteTag({ fs, dir: '/tutorial', ref: 'test-tag' })
* console.log('done')
*
*/
export function deleteTag({ fs, dir, gitdir, ref }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref: string;
}): Promise<void>;
/**
* Expand and resolve a short oid into a full oid
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.oid - The shortened oid prefix to expand (like "0414d2a")
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<string>} Resolves successfully with the full oid (like "0414d2a286d7bbc7a4a326a61c1f9f888a8ab87f")
*
* @example
* let oid = await git.expandOid({ fs, dir: '/tutorial', oid: '0414d2a'})
* console.log(oid)
*
*/
export function expandOid({ fs, dir, gitdir, oid, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
oid: string;
cache?: any;
}): Promise<string>;
/**
* Expand an abbreviated ref to its full name
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - The ref to expand (like "v1.0.0")
*
* @returns {Promise<string>} Resolves successfully with a full ref name ("refs/tags/v1.0.0")
*
* @example
* let fullRef = await git.expandRef({ fs, dir: '/tutorial', ref: 'main'})
* console.log(fullRef)
*
*/
export function expandRef({ fs, dir, gitdir, ref }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref: string;
}): Promise<string>;
/**
* Like `pull`, but hard-coded with `fastForward: true` so there is no need for an `author` parameter.
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {HttpClient} args.http - an HTTP client
* @param {ProgressCallback} [args.onProgress] - optional progress event callback
* @param {MessageCallback} [args.onMessage] - optional message event callback
* @param {AuthCallback} [args.onAuth] - optional auth fill callback
* @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
* @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
* @param {string} args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ref] - Which branch to merge into. By default this is the currently checked out branch.
* @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.
* @param {string} [args.remote] - (Added in 1.1.0) If URL is not specified, determines which remote to use.
* @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.
* @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
* @param {boolean} [args.singleBranch = false] - Instead of the default behavior of fetching all the branches, only fetch a single branch.
* @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<void>} Resolves successfully when pull operation completes
*
* @example
* await git.fastForward({
* fs,
* http,
* dir: '/tutorial',
* ref: 'main',
* singleBranch: true
* })
* console.log('done')
*
*/
export function fastForward({ fs, http, onProgress, onMessage, onAuth, onAuthSuccess, onAuthFailure, dir, gitdir, ref, url, remote, remoteRef, corsProxy, singleBranch, headers, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
http: HttpClient;
onProgress?: ProgressCallback;
onMessage?: MessageCallback;
onAuth?: AuthCallback;
onAuthFailure?: AuthFailureCallback;
onAuthSuccess?: AuthSuccessCallback;
dir: string;
gitdir?: string;
ref?: string;
url?: string;
remote?: string;
remoteRef?: string;
corsProxy?: string;
singleBranch?: boolean;
headers?: {
[x: string]: string;
};
cache?: any;
}): Promise<void>;
/**
*
* @typedef {object} FetchResult - The object returned has the following schema:
* @property {string | null} defaultBranch - The branch that is cloned if no branch is specified
* @property {string | null} fetchHead - The SHA-1 object id of the fetched head commit
* @property {string | null} fetchHeadDescription - a textual description of the branch that was fetched
* @property {Object<string, string>} [headers] - The HTTP response headers returned by the git server
* @property {string[]} [pruned] - A list of branches that were pruned, if you provided the `prune` parameter
*
*/
/**
* Fetch commits from a remote repository
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {HttpClient} args.http - an HTTP client
* @param {ProgressCallback} [args.onProgress] - optional progress event callback
* @param {MessageCallback} [args.onMessage] - optional message event callback
* @param {AuthCallback} [args.onAuth] - optional auth fill callback
* @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
* @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.url] - The URL of the remote repository. The default is the value set in the git config for that remote.
* @param {string} [args.remote] - If URL is not specified, determines which remote to use.
* @param {boolean} [args.singleBranch = false] - Instead of the default behavior of fetching all the branches, only fetch a single branch.
* @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.
* @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.
* @param {boolean} [args.tags = false] - Also fetch tags
* @param {number} [args.depth] - Integer. Determines how much of the git repository's history to retrieve
* @param {boolean} [args.relative = false] - Changes the meaning of `depth` to be measured from the current shallow depth rather than from the branch tip.
* @param {Date} [args.since] - Only fetch commits created after the given date. Mutually exclusive with `depth`.
* @param {string[]} [args.exclude = []] - A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs.
* @param {boolean} [args.prune = false] - Delete local remote-tracking branches that are not present on the remote
* @param {boolean} [args.pruneTags = false] - Prune local tags that don’t exist on the remote, and force-update those tags that differ
* @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
* @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<FetchResult>} Resolves successfully when fetch completes
* @see FetchResult
*
* @example
* let result = await git.fetch({
* fs,
* http,
* dir: '/tutorial',
* corsProxy: 'https://cors.isomorphic-git.org',
* url: 'https://github.com/isomorphic-git/isomorphic-git',
* ref: 'main',
* depth: 1,
* singleBranch: true,
* tags: false
* })
* console.log(result)
*
*/
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, }: {
fs: CallbackFsClient | PromiseFsClient;
http: HttpClient;
onProgress?: ProgressCallback;
onMessage?: MessageCallback;
onAuth?: AuthCallback;
onAuthFailure?: AuthFailureCallback;
onAuthSuccess?: AuthSuccessCallback;
dir?: string;
gitdir?: string;
url?: string;
remote?: string;
singleBranch?: boolean;
ref?: string;
remoteRef?: string;
tags?: boolean;
depth?: number;
relative?: boolean;
since?: Date;
exclude?: string[];
prune?: boolean;
pruneTags?: boolean;
corsProxy?: string;
headers?: {
[x: string]: string;
};
cache?: any;
}): Promise<FetchResult>;
/**
* Find the merge base for a set of commits
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string[]} args.oids - Which commits
* @param {object} [args.cache] - a [cache](cache.md) object
*
*/
export function findMergeBase({ fs, dir, gitdir, oids, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
oids: string[];
cache?: any;
}): Promise<any[]>;
/**
* Find the root git directory
*
* Starting at `filepath`, walks upward until it finds a directory that contains a subdirectory called '.git'.
*
* @param {Object} args
* @param {FsClient} args.fs - a file system client
* @param {string} args.filepath - The file directory to start searching in.
*
* @returns {Promise<string>} Resolves successfully with a root git directory path
* @throws {NotFoundError}
*
* @example
* let gitroot = await git.findRoot({
* fs,
* filepath: '/tutorial/src/utils'
* })
* console.log(gitroot)
*
*/
export function findRoot({ fs, filepath }: {
fs: CallbackFsClient | PromiseFsClient;
filepath: string;
}): Promise<string>;
/**
* Read an entry from the git config files.
*
* *Caveats:*
* - 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.
* - The current parser does not support the more exotic features of the git-config file format such as `[include]` and `[includeIf]`.
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.path - The key of the git config entry
*
* @returns {Promise<any>} Resolves with the config value
*
* @example
* // Read config value
* let value = await git.getConfig({
* fs,
* dir: '/tutorial',
* path: 'remote.origin.url'
* })
* console.log(value)
*
*/
export function getConfig({ fs, dir, gitdir, path }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
path: string;
}): Promise<any>;
/**
* Read a multi-valued entry from the git config files.
*
* *Caveats:*
* - 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.
* - The current parser does not support the more exotic features of the git-config file format such as `[include]` and `[includeIf]`.
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.path - The key of the git config entry
*
* @returns {Promise<Array<any>>} Resolves with the config value
*
*/
export function getConfigAll({ fs, dir, gitdir, path, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
path: string;
}): Promise<any[]>;
/**
*
* @typedef {Object} GetRemoteInfoResult - The object returned has the following schema:
* @property {string[]} capabilities - The list of capabilities returned by the server (part of the Git protocol)
* @property {Object} [refs]
* @property {string} [HEAD] - The default branch of the remote
* @property {Object<string, string>} [refs.heads] - The branches on the remote
* @property {Object<string, string>} [refs.pull] - The special branches representing pull requests (non-standard)
* @property {Object<string, string>} [refs.tags] - The tags on the remote
*
*/
/**
* List a remote servers branches, tags, and capabilities.
*
* This is a rare command that doesn't require an `fs`, `dir`, or even `gitdir` argument.
* 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.
*
* @param {object} args
* @param {HttpClient} args.http - an HTTP client
* @param {AuthCallback} [args.onAuth] - optional auth fill callback
* @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
* @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
* @param {string} args.url - The URL of the remote repository. Will be gotten from gitconfig if absent.
* @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
* @param {boolean} [args.forPush = false] - By default, the command queries the 'fetch' capabilities. If true, it will ask for the 'push' capabilities.
* @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
*
* @returns {Promise<GetRemoteInfoResult>} Resolves successfully with an object listing the branches, tags, and capabilities of the remote.
* @see GetRemoteInfoResult
*
* @example
* let info = await git.getRemoteInfo({
* http,
* url:
* "https://cors.isomorphic-git.org/github.com/isomorphic-git/isomorphic-git.git"
* });
* console.log(info);
*
*/
export function getRemoteInfo({ http, onAuth, onAuthSuccess, onAuthFailure, corsProxy, url, headers, forPush, }: {
http: HttpClient;
onAuth?: AuthCallback;
onAuthFailure?: AuthFailureCallback;
onAuthSuccess?: AuthSuccessCallback;
url: string;
corsProxy?: string;
forPush?: boolean;
headers?: {
[x: string]: string;
};
}): Promise<GetRemoteInfoResult>;
/**
* @typedef {Object} GetRemoteInfo2Result - This object has the following schema:
* @property {1 | 2} protocolVersion - Git protocol version the server supports
* @property {Object<string, string | true>} capabilities - An object of capabilities represented as keys and values
* @property {ServerRef[]} [refs] - Server refs (they get returned by protocol version 1 whether you want them or not)
*/
/**
* List a remote server's capabilities.
*
* This is a rare command that doesn't require an `fs`, `dir`, or even `gitdir` argument.
* It just communicates to a remote git server, determining what protocol version, commands, and features it supports.
*
* > The successor to [`getRemoteInfo`](./getRemoteInfo.md), this command supports Git Wire Protocol Version 2.
* > Therefore its return type is more complicated as either:
* >
* > - v1 capabilities (and refs) or
* > - v2 capabilities (and no refs)
* >
* > are returned.
* > If you just care about refs, use [`listServerRefs`](./listServerRefs.md)
*
* @param {object} args
* @param {HttpClient} args.http - an HTTP client
* @param {AuthCallback} [args.onAuth] - optional auth fill callback
* @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
* @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
* @param {string} args.url - The URL of the remote repository. Will be gotten from gitconfig if absent.
* @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
* @param {boolean} [args.forPush = false] - By default, the command queries the 'fetch' capabilities. If true, it will ask for the 'push' capabilities.
* @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
* @param {1 | 2} [args.protocolVersion = 2] - Which version of the Git Protocol to use.
*
* @returns {Promise<GetRemoteInfo2Result>} Resolves successfully with an object listing the capabilities of the remote.
* @see GetRemoteInfo2Result
* @see ServerRef
*
* @example
* let info = await git.getRemoteInfo2({
* http,
* corsProxy: "https://cors.isomorphic-git.org",
* url: "https://github.com/isomorphic-git/isomorphic-git.git"
* });
* console.log(info);
*
*/
export function getRemoteInfo2({ http, onAuth, onAuthSuccess, onAuthFailure, corsProxy, url, headers, forPush, protocolVersion, }: {
http: HttpClient;
onAuth?: AuthCallback;
onAuthFailure?: AuthFailureCallback;
onAuthSuccess?: AuthSuccessCallback;
url: string;
corsProxy?: string;
forPush?: boolean;
headers?: {
[x: string]: string;
};
protocolVersion?: 1 | 2;
}): Promise<GetRemoteInfo2Result>;
/**
*
* @typedef {object} HashBlobResult - The object returned has the following schema:
* @property {string} oid - The SHA-1 object id
* @property {'blob'} type - The type of the object
* @property {Uint8Array} object - The wrapped git object (the thing that is hashed)
* @property {'wrapped'} format - The format of the object
*
*/
/**
* Compute what the SHA-1 object id of a file would be
*
* @param {object} args
* @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.
*
* @returns {Promise<HashBlobResult>} Resolves successfully with the SHA-1 object id and the wrapped object Uint8Array.
* @see HashBlobResult
*
* @example
* let { oid, type, object, format } = await git.hashBlob({
* object: 'Hello world!',
* })
*
* console.log('oid', oid)
* console.log('type', type)
* console.log('object', object)
* console.log('format', format)
*
*/
export function hashBlob({ object }: {
object: string | Uint8Array;
}): Promise<HashBlobResult>;
/**
* Create the .idx file for a given .pack file
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {ProgressCallback} [args.onProgress] - optional progress event callback
* @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.filepath - The path to the .pack file to index
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<{oids: string[]}>} Resolves with a list of the SHA-1 object ids contained in the packfile
*
* @example
* let packfiles = await fs.promises.readdir('/tutorial/.git/objects/pack')
* packfiles = packfiles.filter(name => name.endsWith('.pack'))
* console.log('packfiles', packfiles)
*
* const { oids } = await git.indexPack({
* fs,
* dir: '/tutorial',
* filepath: `.git/objects/pack/${packfiles[0]}`,
* async onProgress (evt) {
* console.log(`${evt.phase}: ${evt.loaded} / ${evt.total}`)
* }
* })
* console.log(oids)
*
*/
export function indexPack({ fs, onProgress, dir, gitdir, filepath, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
onProgress?: ProgressCallback;
dir: string;
gitdir?: string;
filepath: string;
cache?: any;
}): Promise<{
oids: string[];
}>;
/**
* Initialize a new repository
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {boolean} [args.bare = false] - Initialize a bare repository
* @param {string} [args.defaultBranch = 'master'] - The name of the default branch (might be changed to a required argument in 2.0.0)
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.init({ fs, dir: '/tutorial' })
* console.log('done')
*
*/
export function init({ fs, bare, dir, gitdir, defaultBranch, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
bare?: boolean;
defaultBranch?: string;
}): Promise<void>;
/**
* Check whether a git commit is descended from another
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.oid - The descendent commit
* @param {string} args.ancestor - The (proposed) ancestor commit
* @param {number} [args.depth = -1] - Maximum depth to search before giving up. -1 means no maximum depth.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<boolean>} Resolves to true if `oid` is a descendent of `ancestor`
*
* @example
* let oid = await git.resolveRef({ fs, dir: '/tutorial', ref: 'main' })
* let ancestor = await git.resolveRef({ fs, dir: '/tutorial', ref: 'v0.20.0' })
* console.log(oid, ancestor)
* await git.isDescendent({ fs, dir: '/tutorial', oid, ancestor, depth: -1 })
*
*/
export function isDescendent({ fs, dir, gitdir, oid, ancestor, depth, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
oid: string;
ancestor: string;
depth?: number;
cache?: any;
}): Promise<boolean>;
/**
* Test whether a filepath should be ignored (because of .gitignore or .git/exclude)
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.filepath - The filepath to test
*
* @returns {Promise<boolean>} Resolves to true if the file should be ignored
*
* @example
* await git.isIgnored({ fs, dir: '/tutorial', filepath: 'docs/add.md' })
*
*/
export function isIgnored({ fs, dir, gitdir, filepath, }: {
fs: CallbackFsClient | PromiseFsClient;
dir: string;
gitdir?: string;
filepath: string;
}): Promise<boolean>;
/**
* List branches
*
* 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.
*
* Note that specifying a remote does not actually contact the server and update the list of branches.
* If you want an up-to-date list, first do a `fetch` to that remote.
* (Which branch you fetch doesn't matter - the list of branches available on the remote is updated during the fetch handshake.)
*
* Also note, that a branch is a reference to a commit. If you initialize a new repository it has no commits, so the
* `listBranches` function will return an empty list, until you create the first commit.
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.remote] - Instead of the branches in `refs/heads`, list the branches in `refs/remotes/${remote}`.
*
* @returns {Promise<Array<string>>} Resolves successfully with an array of branch names
*
* @example
* let branches = await git.listBranches({ fs, dir: '/tutorial' })
* console.log(branches)
* let remoteBranches = await git.listBranches({ fs, dir: '/tutorial', remote: 'origin' })
* console.log(remoteBranches)
*
*/
export function listBranches({ fs, dir, gitdir, remote, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
remote?: string;
}): Promise<string[]>;
/**
* List all the files in the git index or a commit
*
* > 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.
* > 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.
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @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)
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<Array<string>>} Resolves successfully with an array of filepaths
*
* @example
* // All the files in the previous commit
* let files = await git.listFiles({ fs, dir: '/tutorial', ref: 'HEAD' })
* console.log(files)
* // All the files in the current staging area
* files = await git.listFiles({ fs, dir: '/tutorial' })
* console.log(files)
*
*/
export function listFiles({ fs, dir, gitdir, ref, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref?: string;
cache?: any;
}): Promise<string[]>;
/**
* List all the object notes
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ref] - The notes ref to look under
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @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
*/
export function listNotes({ fs, dir, gitdir, ref, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref?: string;
cache?: any;
}): Promise<{
target: string;
note: string;
}[]>;
/**
* List remotes
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
*
* @returns {Promise<Array<{remote: string, url: string}>>} Resolves successfully with an array of `{remote, url}` objects
*
* @example
* let remotes = await git.listRemotes({ fs, dir: '/tutorial' })
* console.log(remotes)
*
*/
export function listRemotes({ fs, dir, gitdir }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
}): Promise<{
remote: string;
url: string;
}[]>;
/**
* Fetch a list of refs (branches, tags, etc) from a server.
*
* This is a rare command that doesn't require an `fs`, `dir`, or even `gitdir` argument.
* It just requires an `http` argument.
*
* ### About `protocolVersion`
*
* There's a rather fun trade-off between Git Protocol Version 1 and Git Protocol Version 2.
* Version 2 actually requires 2 HTTP requests instead of 1, making it similar to fetch or push in that regard.
* However, version 2 supports server-side filtering by prefix, whereas that filtering is done client-side in version 1.
* 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.
* For an small repos (or fast Internet connections), the requirement to make two trips to the server makes protocol 2 slower.
* But for large repos (or slow Internet connections), the decreased payload size of the second request makes up for the additional request.
*
* Hard numbers vary by situation, but here's some numbers from my machine:
*
* Using isomorphic-git in a browser, with a CORS proxy, listing only the branches (refs/heads) of https://github.com/isomorphic-git/isomorphic-git
* - Protocol Version 1 took ~300ms and transferred 84 KB.
* - Protocol Version 2 took ~500ms and transferred 4.1 KB.
*
* Using isomorphic-git in a browser, with a CORS proxy, listing only the branches (refs/heads) of https://gitlab.com/gitlab-org/gitlab
* - Protocol Version 1 took ~4900ms and transferred 9.41 MB.
* - Protocol Version 2 took ~1280ms and transferred 433 KB.
*
* Finally, there is a fun quirk regarding the `symrefs` parameter.
* Protocol Version 1 will generally only return the `HEAD` symref and not others.
* Historically, this meant that servers don't use symbolic refs except for `HEAD`, which is used to point at the "default branch".
* However Protocol Version 2 can return *all* the symbolic refs on the server.
* So if you are running your own git server, you could take advantage of that I guess.
*
* #### TL;DR
* If you are _not_ taking advantage of `prefix` I would recommend `protocolVersion: 1`.
* Otherwise, I recommend to use the default which is `protocolVersion: 2`.
*
* @param {object} args
* @param {HttpClient} args.http - an HTTP client
* @param {AuthCallback} [args.onAuth] - optional auth fill callback
* @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
* @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
* @param {string} args.url - The URL of the remote repository. Will be gotten from gitconfig if absent.
* @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
* @param {boolean} [args.forPush = false] - By default, the command queries the 'fetch' capabilities. If true, it will ask for the 'push' capabilities.
* @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
* @param {1 | 2} [args.protocolVersion = 2] - Which version of the Git Protocol to use.
* @param {string} [args.prefix] - Only list refs that start with this prefix
* @param {boolean} [args.symrefs = false] - Include symbolic ref targets
* @param {boolean} [args.peelTags = false] - Include annotated tag peeled targets
*
* @returns {Promise<ServerRef[]>} Resolves successfully with an array of ServerRef objects
* @see ServerRef
*
* @example
* // List all the branches on a repo
* let refs = await git.listServerRefs({
* http,
* corsProxy: "https://cors.isomorphic-git.org",
* url: "https://github.com/isomorphic-git/isomorphic-git.git",
* prefix: "refs/heads/",
* });
* console.log(refs);
*
* @example
* // Get the default branch on a repo
* let refs = await git.listServerRefs({
* http,
* corsProxy: "https://cors.isomorphic-git.org",
* url: "https://github.com/isomorphic-git/isomorphic-git.git",
* prefix: "HEAD",
* symrefs: true,
* });
* console.log(refs);
*
* @example
* // List all the tags on a repo
* let refs = await git.listServerRefs({
* http,
* corsProxy: "https://cors.isomorphic-git.org",
* url: "https://github.com/isomorphic-git/isomorphic-git.git",
* prefix: "refs/tags/",
* peelTags: true,
* });
* console.log(refs);
*
* @example
* // List all the pull requests on a repo
* let refs = await git.listServerRefs({
* http,
* corsProxy: "https://cors.isomorphic-git.org",
* url: "https://github.com/isomorphic-git/isomorphic-git.git",
* prefix: "refs/pull/",
* });
* console.log(refs);
*
*/
export function listServerRefs({ http, onAuth, onAuthSuccess, onAuthFailure, corsProxy, url, headers, forPush, protocolVersion, prefix, symrefs, peelTags, }: {
http: HttpClient;
onAuth?: AuthCallback;
onAuthFailure?: AuthFailureCallback;
onAuthSuccess?: AuthSuccessCallback;
url: string;
corsProxy?: string;
forPush?: boolean;
headers?: {
[x: string]: string;
};
protocolVersion?: 1 | 2;
prefix?: string;
symrefs?: boolean;
peelTags?: boolean;
}): Promise<ServerRef[]>;
/**
* List tags
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
*
* @returns {Promise<Array<string>>} Resolves successfully with an array of tag names
*
* @example
* let tags = await git.listTags({ fs, dir: '/tutorial' })
* console.log(tags)
*
*/
export function listTags({ fs, dir, gitdir }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
}): Promise<string[]>;
/**
* Get commit descriptions from the git history
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string=} args.filepath optional get the commit for the filepath only
* @param {string} [args.ref = 'HEAD'] - The commit to begin walking backwards through the history from
* @param {number=} [args.depth] - Limit the number of commits returned. No limit by default.
* @param {Date} [args.since] - Return history newer than the given date. Can be combined with `depth` to get whichever is shorter.
* @param {boolean=} [args.force=false] do not throw error if filepath is not exist (works only for a single file). defaults to false
* @param {boolean=} [args.follow=false] Continue listing the history of a file beyond renames (works only for a single file). defaults to false
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<Array<ReadCommitResult>>} Resolves to an array of ReadCommitResult objects
* @see ReadCommitResult
* @see CommitObject
*
* @example
* let commits = await git.log({
* fs,
* dir: '/tutorial',
* depth: 5,
* ref: 'main'
* })
* console.log(commits)
*
*/
export function log({ fs, dir, gitdir, filepath, ref, depth, since, force, follow, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
filepath?: string | undefined;
ref?: string;
depth?: number | undefined;
since?: Date;
force?: boolean | undefined;
follow?: boolean | undefined;
cache?: any;
}): Promise<ReadCommitResult[]>;
/**
*
* @typedef {Object} MergeResult - Returns an object with a schema like this:
* @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.
* @property {boolean} [alreadyMerged] - True if the branch was already merged so no changes were made
* @property {boolean} [fastForward] - True if it was a fast-forward merge
* @property {boolean} [mergeCommit] - True if merge resulted in a merge commit
* @property {string} [tree] - The SHA-1 object id of the tree resulting from a merge commit
*
*/
/**
* Merge two branches
*
* Currently it will fail if multiple candidate merge bases are found. (It doesn't yet implement the recursive merge strategy.)
*
* Currently it does not support selecting alternative merge strategies.
*
* Currently it is not possible to abort an incomplete merge. To restore the worktree to a clean state, you will need to checkout an earlier commit.
*
* Currently it does not directly support the behavior of `git merge --continue`. To complete a merge after manual conflict resolution, you will need to add and commit the files manually, and specify the appropriate parent commits.
*
* ## Manually resolving merge conflicts
* By default, if isomorphic-git encounters a merge conflict it cannot resolve using the builtin diff3 algorithm or provided merge driver, it will abort and throw a `MergeNotSupportedError`.
* This leaves the index and working tree untouched.
*
* When `abortOnConflict` is set to `false`, and a merge conflict cannot be automatically resolved, a `MergeConflictError` is thrown and the results of the incomplete merge will be written to the working directory.
* This includes conflict markers in files with unresolved merge conflicts.
*
* To complete the merge, edit the conflicting files as you see fit, and then add and commit the resolved merge.
*
* For a proper merge commit, be sure to specify the branches or commits you are merging in the `parent` argument to `git.commit`.
* For example, say we are merging the branch `feature` into the branch `main` and there is a conflict we want to resolve manually.
* The flow would look like this:
*
* ```
* await git.merge({
* fs,
* dir,
* ours: 'main',
* theirs: 'feature',
* abortOnConflict: false,
* }).catch(e => {
* if (e instanceof Errors.MergeConflictError) {
* console.log(
* 'Automatic merge failed for the following files: '
* + `${e.data}. `
* + 'Resolve these conflicts and then commit your changes.'
* )
* } else throw e
* })
*
* // This is the where we manually edit the files that have been written to the working directory
* // ...
* // Files have been edited and we are ready to commit
*
* await git.add({
* fs,
* dir,
* filepath: '.',
* })
*
* await git.commit({
* fs,
* dir,
* ref: 'main',
* message: "Merge branch 'feature' into main",
* parent: ['main', 'feature'], // Be sure to specify the parents when creating a merge commit
* })
* ```
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {SignCallback} [args.onSign] - a PGP signing implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ours] - The branch receiving the merge. If undefined, defaults to the current branch.
* @param {string} args.theirs - The branch to be merged
* @param {boolean} [args.fastForward = true] - If false, create a merge commit in all cases.
* @param {boolean} [args.fastForwardOnly = false] - If true, then non-fast-forward merges will throw an Error instead of performing a merge.
* @param {boolean} [args.dryRun = false] - If true, simulates a merge so you can test whether it would succeed.
* @param {boolean} [args.noUpdateBranch = false] - If true, does not update the branch pointer after creating the commit.
* @param {boolean} [args.abortOnConflict = true] - If true, merges with conflicts will not update the worktree or index.
* @param {string} [args.message] - Overrides the default auto-generated merge commit message
* @param {Object} [args.author] - passed to [commit](commit.md) when creating a merge commit
* @param {string} [args.author.name] - Default is `user.name` config.
* @param {string} [args.author.email] - Default is `user.email` config.
* @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).
* @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()`.
* @param {Object} [args.committer] - passed to [commit](commit.md) when creating a merge commit
* @param {string} [args.committer.name] - Default is `user.name` config.
* @param {string} [args.committer.email] - Default is `user.email` config.
* @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).
* @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()`.
* @param {string} [args.signingKey] - passed to [commit](commit.md) when creating a merge commit
* @param {object} [args.cache] - a [cache](cache.md) object
* @param {MergeDriverCallback} [args.mergeDriver] - a [merge driver](mergeDriver.md) implementation
*
* @returns {Promise<MergeResult>} Resolves to a description of the merge operation
* @see MergeResult
*
* @example
* let m = await git.merge({
* fs,
* dir: '/tutorial',
* ours: 'main',
* theirs: 'remotes/origin/main'
* })
* console.log(m)
*
*/
export function merge({ fs: _fs, onSign, dir, gitdir, ours, theirs, fastForward, fastForwardOnly, dryRun, noUpdateBranch, abortOnConflict, message, author: _author, committer: _committer, signingKey, cache, mergeDriver, }: {
fs: CallbackFsClient | PromiseFsClient;
onSign?: SignCallback;
dir?: string;
gitdir?: string;
ours?: string;
theirs: string;
fastForward?: boolean;
fastForwardOnly?: boolean;
dryRun?: boolean;
noUpdateBranch?: boolean;
abortOnConflict?: boolean;
message?: string;
author?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
committer?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
signingKey?: string;
cache?: any;
mergeDriver?: MergeDriverCallback;
}): Promise<MergeResult>;
/**
*
* @typedef {Object} PackObjectsResult The packObjects command returns an object with two properties:
* @property {string} filename - The suggested filename for the packfile if you want to save it to disk somewhere. It includes the packfile SHA.
* @property {Uint8Array} [packfile] - The packfile contents. Not present if `write` parameter was true, in which case the packfile was written straight to disk.
*/
/**
* Create a packfile from an array of SHA-1 object ids
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string[]} args.oids - An array of SHA-1 object ids to be included in the packfile
* @param {boolean} [args.write = false] - Whether to save the packfile to disk or not
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<PackObjectsResult>} Resolves successfully when the packfile is ready with the filename and buffer
* @see PackObjectsResult
*
* @example
* // Create a packfile containing only an empty tree
* let { packfile } = await git.packObjects({
* fs,
* dir: '/tutorial',
* oids: ['4b825dc642cb6eb9a060e54bf8d69288fbee4904']
* })
* console.log(packfile)
*
*/
export function packObjects({ fs, dir, gitdir, oids, write, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
oids: string[];
write?: boolean;
cache?: any;
}): Promise<PackObjectsResult>;
/**
* Fetch and merge commits from a remote repository
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {HttpClient} args.http - an HTTP client
* @param {ProgressCallback} [args.onProgress] - optional progress event callback
* @param {MessageCallback} [args.onMessage] - optional message event callback
* @param {AuthCallback} [args.onAuth] - optional auth fill callback
* @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
* @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
* @param {string} args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ref] - Which branch to merge into. By default this is the currently checked out branch.
* @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.
* @param {string} [args.remote] - (Added in 1.1.0) If URL is not specified, determines which remote to use.
* @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.
* @param {boolean} [args.prune = false] - Delete local remote-tracking branches that are not present on the remote
* @param {boolean} [args.pruneTags = false] - Prune local tags that don’t exist on the remote, and force-update those tags that differ
* @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
* @param {boolean} [args.singleBranch = false] - Instead of the default behavior of fetching all the branches, only fetch a single branch.
* @param {boolean} [args.fastForward = true] - If false, only create merge commits.
* @param {boolean} [args.fastForwardOnly = false] - Only perform simple fast-forward merges. (Don't create merge commits.)
* @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
* @param {Object} [args.author] - The details about the author.
* @param {string} [args.author.name] - Default is `user.name` config.
* @param {string} [args.author.email] - Default is `user.email` config.
* @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).
* @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()`.
* @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.
* @param {string} [args.committer.name] - Default is `user.name` config.
* @param {string} [args.committer.email] - Default is `user.email` config.
* @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).
* @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()`.
* @param {string} [args.signingKey] - passed to [commit](commit.md) when creating a merge commit
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<void>} Resolves successfully when pull operation completes
*
* @example
* await git.pull({
* fs,
* http,
* dir: '/tutorial',
* ref: 'main',
* singleBranch: true
* })
* console.log('done')
*
*/
export function pull({ fs: _fs, http, onProgress, onMessage, onAuth, onAuthSuccess, onAuthFailure, dir, gitdir, ref, url, remote, remoteRef, prune, pruneTags, fastForward, fastForwardOnly, corsProxy, singleBranch, headers, author: _author, committer: _committer, signingKey, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
http: HttpClient;
onProgress?: ProgressCallback;
onMessage?: MessageCallback;
onAuth?: AuthCallback;
onAuthFailure?: AuthFailureCallback;
onAuthSuccess?: AuthSuccessCallback;
dir: string;
gitdir?: string;
ref?: string;
url?: string;
remote?: string;
remoteRef?: string;
prune?: boolean;
pruneTags?: boolean;
corsProxy?: string;
singleBranch?: boolean;
fastForward?: boolean;
fastForwardOnly?: boolean;
headers?: {
[x: string]: string;
};
author?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
committer?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
signingKey?: string;
cache?: any;
}): Promise<void>;
/**
* Push a branch or tag
*
* The push command returns an object that describes the result of the attempted push operation.
* *Notes:* If there were no errors, then there will be no `errors` property. There can be a mix of `ok` messages and `errors` messages.
*
* | param | type [= default] | description |
* | ------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* | 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. |
* | 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}". |
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {HttpClient} args.http - an HTTP client
* @param {ProgressCallback} [args.onProgress] - optional progress event callback
* @param {MessageCallback} [args.onMessage] - optional message event callback
* @param {AuthCallback} [args.onAuth] - optional auth fill callback
* @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
* @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ref] - Which branch to push. By default this is the currently checked out branch.
* @param {string} [args.url] - The URL of the remote repository. The default is the value set in the git config for that remote.
* @param {string} [args.remote] - If URL is not specified, determines which remote to use.
* @param {string} [args.remoteRef] - The name of the receiving branch on the remote. By default this is the configured remote tracking branch.
* @param {boolean} [args.force = false] - If true, behaves the same as `git push --force`
* @param {boolean} [args.delete = false] - If true, delete the remote ref
* @param {string} [args.corsProxy] - Optional [CORS proxy](https://www.npmjs.com/%40isomorphic-git/cors-proxy). Overrides value in repo config.
* @param {Object<string, string>} [args.headers] - Additional headers to include in HTTP requests, similar to git's `extraHeader` config
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<PushResult>} Resolves successfully when push completes with a detailed description of the operation from the server.
* @see PushResult
* @see RefUpdateStatus
*
* @example
* let pushResult = await git.push({
* fs,
* http,
* dir: '/tutorial',
* remote: 'origin',
* ref: 'main',
* onAuth: () => ({ username: process.env.GITHUB_TOKEN }),
* })
* console.log(pushResult)
*
*/
export function push({ fs, http, onProgress, onMessage, onAuth, onAuthSuccess, onAuthFailure, dir, gitdir, ref, remoteRef, remote, url, force, delete: _delete, corsProxy, headers, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
http: HttpClient;
onProgress?: ProgressCallback;
onMessage?: MessageCallback;
onAuth?: AuthCallback;
onAuthFailure?: AuthFailureCallback;
onAuthSuccess?: AuthSuccessCallback;
dir?: string;
gitdir?: string;
ref?: string;
url?: string;
remote?: string;
remoteRef?: string;
force?: boolean;
delete?: boolean;
corsProxy?: string;
headers?: {
[x: string]: string;
};
cache?: any;
}): Promise<PushResult>;
/**
*
* @typedef {Object} ReadBlobResult - The object returned has the following schema:
* @property {string} oid
* @property {Uint8Array} blob
*
*/
/**
* Read a blob object directly
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.oid - The SHA-1 object id to get. Annotated tags, commits, and trees are peeled.
* @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.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<ReadBlobResult>} Resolves successfully with a blob object description
* @see ReadBlobResult
*
* @example
* // Get the contents of 'README.md' in the main branch.
* let commitOid = await git.resolveRef({ fs, dir: '/tutorial', ref: 'main' })
* console.log(commitOid)
* let { blob } = await git.readBlob({
* fs,
* dir: '/tutorial',
* oid: commitOid,
* filepath: 'README.md'
* })
* console.log(Buffer.from(blob).toString('utf8'))
*
*/
export function readBlob({ fs, dir, gitdir, oid, filepath, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
oid: string;
filepath?: string;
cache?: any;
}): Promise<ReadBlobResult>;
/**
* Read a commit object directly
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.oid - The SHA-1 object id to get. Annotated tags are peeled.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<ReadCommitResult>} Resolves successfully with a git commit object
* @see ReadCommitResult
* @see CommitObject
*
* @example
* // Read a commit object
* let sha = await git.resolveRef({ fs, dir: '/tutorial', ref: 'main' })
* console.log(sha)
* let commit = await git.readCommit({ fs, dir: '/tutorial', oid: sha })
* console.log(commit)
*
*/
export function readCommit({ fs, dir, gitdir, oid, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
oid: string;
cache?: any;
}): Promise<ReadCommitResult>;
/**
* Read the contents of a note
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ref] - The notes ref to look under
* @param {string} args.oid - The SHA-1 object id of the object to get the note for.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<Uint8Array>} Resolves successfully with note contents as a Buffer.
*/
export function readNote({ fs, dir, gitdir, ref, oid, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref?: string;
oid: string;
cache?: any;
}): Promise<Uint8Array>;
/**
*
* @typedef {Object} DeflatedObject
* @property {string} oid
* @property {'deflated'} type
* @property {'deflated'} format
* @property {Uint8Array} object
* @property {string} [source]
*
*/
/**
*
* @typedef {Object} WrappedObject
* @property {string} oid
* @property {'wrapped'} type
* @property {'wrapped'} format
* @property {Uint8Array} object
* @property {string} [source]
*
*/
/**
*
* @typedef {Object} RawObject
* @property {string} oid
* @property {'blob'|'commit'|'tree'|'tag'} type
* @property {'content'} format
* @property {Uint8Array} object
* @property {string} [source]
*
*/
/**
*
* @typedef {Object} ParsedBlobObject
* @property {string} oid
* @property {'blob'} type
* @property {'parsed'} format
* @property {string} object
* @property {string} [source]
*
*/
/**
*
* @typedef {Object} ParsedCommitObject
* @property {string} oid
* @property {'commit'} type
* @property {'parsed'} format
* @property {CommitObject} object
* @property {string} [source]
*
*/
/**
*
* @typedef {Object} ParsedTreeObject
* @property {string} oid
* @property {'tree'} type
* @property {'parsed'} format
* @property {TreeObject} object
* @property {string} [source]
*
*/
/**
*
* @typedef {Object} ParsedTagObject
* @property {string} oid
* @property {'tag'} type
* @property {'parsed'} format
* @property {TagObject} object
* @property {string} [source]
*
*/
/**
*
* @typedef {ParsedBlobObject | ParsedCommitObject | ParsedTreeObject | ParsedTagObject} ParsedObject
*/
/**
*
* @typedef {DeflatedObject | WrappedObject | RawObject | ParsedObject } ReadObjectResult
*/
/**
* Read a git object directly by its SHA-1 object id
*
* Regarding `ReadObjectResult`:
*
* - `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.
* - `type` of deflated objects is `'deflated'`, and `type` of wrapped objects is `'wrapped'`
* - `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'.
* - `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.
* - `source` is the name of the packfile or loose object file where the object was found.
*
* The `format` parameter can have the following values:
*
* | param | description |
* | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* | '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. |
* | '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. |
* | 'content' | Return the object buffer without the git header. |
* | 'parsed' | Returns a parsed representation of the object. |
*
* The result will be in one of the following schemas:
*
* ## `'deflated'` format
*
* {@link DeflatedObject typedef}
*
* ## `'wrapped'` format
*
* {@link WrappedObject typedef}
*
* ## `'content'` format
*
* {@link RawObject typedef}
*
* ## `'parsed'` format
*
* ### parsed `'blob'` type
*
* {@link ParsedBlobObject typedef}
*
* ### parsed `'commit'` type
*
* {@link ParsedCommitObject typedef}
* {@link CommitObject typedef}
*
* ### parsed `'tree'` type
*
* {@link ParsedTreeObject typedef}
* {@link TreeObject typedef}
* {@link TreeEntry typedef}
*
* ### parsed `'tag'` type
*
* {@link ParsedTagObject typedef}
* {@link TagObject typedef}
*
* @deprecated
* > This command is overly complicated.
* >
* > If you know the type of object you are reading, use [`readBlob`](./readBlob.md), [`readCommit`](./readCommit.md), [`readTag`](./readTag.md), or [`readTree`](./readTree.md).
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.oid - The SHA-1 object id to get
* @param {'deflated' | 'wrapped' | 'content' | 'parsed'} [args.format = 'parsed'] - What format to return the object in. The choices are described in more detail below.
* @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 `''`
* @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.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<ReadObjectResult>} Resolves successfully with a git object description
* @see ReadObjectResult
*
* @example
* // Given a ransom SHA-1 object id, figure out what it is
* let { type, object } = await git.readObject({
* fs,
* dir: '/tutorial',
* oid: '0698a781a02264a6f37ba3ff41d78067eaf0f075'
* })
* switch (type) {
* case 'commit': {
* console.log(object)
* break
* }
* case 'tree': {
* console.log(object)
* break
* }
* case 'blob': {
* console.log(object)
* break
* }
* case 'tag': {
* console.log(object)
* break
* }
* }
*
*/
export function readObject({ fs: _fs, dir, gitdir, oid, format, filepath, encoding, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
oid: string;
format?: "parsed" | "deflated" | "content" | "wrapped";
filepath?: string;
encoding?: string;
cache?: any;
}): Promise<ParsedBlobObject | ParsedCommitObject | ParsedTreeObject | ParsedTagObject | DeflatedObject | WrappedObject | RawObject>;
/**
*
* @typedef {Object} ReadTagResult - The object returned has the following schema:
* @property {string} oid - SHA-1 object id of this tag
* @property {TagObject} tag - the parsed tag object
* @property {string} payload - PGP signing payload
*/
/**
* Read an annotated tag object directly
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.oid - The SHA-1 object id to get
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<ReadTagResult>} Resolves successfully with a git object description
* @see ReadTagResult
* @see TagObject
*
*/
export function readTag({ fs, dir, gitdir, oid, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
oid: string;
cache?: any;
}): Promise<ReadTagResult>;
/**
*
* @typedef {Object} ReadTreeResult - The object returned has the following schema:
* @property {string} oid - SHA-1 object id of this tree
* @property {TreeObject} tree - the parsed tree object
*/
/**
* Read a tree object directly
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.oid - The SHA-1 object id to get. Annotated tags and commits are peeled.
* @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.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<ReadTreeResult>} Resolves successfully with a git tree object
* @see ReadTreeResult
* @see TreeObject
* @see TreeEntry
*
*/
export function readTree({ fs, dir, gitdir, oid, filepath, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
oid: string;
filepath?: string;
cache?: any;
}): Promise<ReadTreeResult>;
/**
* Remove a file from the git index (aka staging area)
*
* Note that this does NOT delete the file in the working directory.
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.filepath - The path to the file to remove from the index
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<void>} Resolves successfully once the git index has been updated
*
* @example
* await git.remove({ fs, dir: '/tutorial', filepath: 'README.md' })
* console.log('done')
*
*/
export function remove({ fs: _fs, dir, gitdir, filepath, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
filepath: string;
cache?: any;
}): Promise<void>;
/**
* Remove an object note
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {SignCallback} [args.onSign] - a PGP signing implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ref] - The notes ref to look under
* @param {string} args.oid - The SHA-1 object id of the object to remove the note from.
* @param {Object} [args.author] - The details about the author.
* @param {string} [args.author.name] - Default is `user.name` config.
* @param {string} [args.author.email] - Default is `user.email` config.
* @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).
* @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()`.
* @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.
* @param {string} [args.committer.name] - Default is `user.name` config.
* @param {string} [args.committer.email] - Default is `user.email` config.
* @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).
* @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()`.
* @param {string} [args.signingKey] - Sign the tag object using this private PGP key.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the commit object for the note removal.
*/
export function removeNote({ fs: _fs, onSign, dir, gitdir, ref, oid, author: _author, committer: _committer, signingKey, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
onSign?: SignCallback;
dir?: string;
gitdir?: string;
ref?: string;
oid: string;
author?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
committer?: {
name?: string;
email?: string;
timestamp?: number;
timezoneOffset?: number;
};
signingKey?: string;
cache?: any;
}): Promise<string>;
/**
* Rename a branch
*
* @param {object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - What to name the branch
* @param {string} args.oldref - What the name of the branch was
* @param {boolean} [args.checkout = false] - Update `HEAD` to point at the newly created branch
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.renameBranch({ fs, dir: '/tutorial', ref: 'main', oldref: 'master' })
* console.log('done')
*
*/
export function renameBranch({ fs, dir, gitdir, ref, oldref, checkout, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref: string;
oldref: string;
checkout?: boolean;
}): Promise<void>;
/**
* Reset a file in the git index (aka staging area)
*
* Note that this does NOT modify the file in the working directory.
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.filepath - The path to the file to reset in the index
* @param {string} [args.ref = 'HEAD'] - A ref to the commit to use
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<void>} Resolves successfully once the git index has been updated
*
* @example
* await git.resetIndex({ fs, dir: '/tutorial', filepath: 'README.md' })
* console.log('done')
*
*/
export function resetIndex({ fs: _fs, dir, gitdir, filepath, ref, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
filepath: string;
ref?: string;
cache?: any;
}): Promise<void>;
/**
* Get the value of a symbolic ref or resolve a ref to its SHA-1 object id
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - The ref to resolve
* @param {number} [args.depth = undefined] - How many symbolic references to follow before returning
*
* @returns {Promise<string>} Resolves successfully with a SHA-1 object id or the value of a symbolic ref
*
* @example
* let currentCommit = await git.resolveRef({ fs, dir: '/tutorial', ref: 'HEAD' })
* console.log(currentCommit)
* let currentBranch = await git.resolveRef({ fs, dir: '/tutorial', ref: 'HEAD', depth: 2 })
* console.log(currentBranch)
*
*/
export function resolveRef({ fs, dir, gitdir, ref, depth, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref: string;
depth?: number;
}): Promise<string>;
/**
* Write an entry to the git config files.
*
* *Caveats:*
* - 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.
* - The current parser does not support the more exotic features of the git-config file format such as `[include]` and `[includeIf]`.
*
* @param {Object} args
* @param {FsClient} args.fs - a file system implementation
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.path - The key of the git config entry
* @param {string | boolean | number | void} args.value - A value to store at that path. (Use `undefined` as the value to delete a config entry.)
* @param {boolean} [args.append = false] - If true, will append rather than replace when setting (use with multi-valued config options).
*
* @returns {Promise<void>} Resolves successfully when operation completed
*
* @example
* // Write config value
* await git.setConfig({
* fs,
* dir: '/tutorial',
* path: 'user.name',
* value: 'Mr. Test'
* })
*
* // Print out config file
* let file = await fs.promises.readFile('/tutorial/.git/config', 'utf8')
* console.log(file)
*
* // Delete a config entry
* await git.setConfig({
* fs,
* dir: '/tutorial',
* path: 'user.name',
* value: undefined
* })
*
* // Print out config file
* file = await fs.promises.readFile('/tutorial/.git/config', 'utf8')
* console.log(file)
*/
export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
path: string;
value: string | number | boolean | void;
append?: boolean;
}): Promise<void>;
/**
* Tell whether a file has been changed
*
* The possible resolve values are:
*
* | status | description |
* | --------------------- | ------------------------------------------------------------------------------------- |
* | `"ignored"` | file ignored by a .gitignore rule |
* | `"unmodified"` | file unchanged from HEAD commit |
* | `"*modified"` | file has modifications, not yet staged |
* | `"*deleted"` | file has been removed, but the removal is not yet staged |
* | `"*added"` | file is untracked, not yet staged |
* | `"absent"` | file not present in HEAD commit, staging area, or working dir |
* | `"modified"` | file has modifications, staged |
* | `"deleted"` | file has been removed, staged |
* | `"added"` | previously untracked file, staged |
* | `"*unmodified"` | working dir and HEAD commit match, but index differs |
* | `"*absent"` | file not present in working dir or HEAD commit, but present in the index |
* | `"*undeleted"` | file was deleted from the index, but is still in the working dir |
* | `"*undeletemodified"` | file was deleted from the index, but is present with modifications in the working dir |
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.filepath - The path to the file to query
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<'ignored'|'unmodified'|'*modified'|'*deleted'|'*added'|'absent'|'modified'|'deleted'|'added'|'*unmodified'|'*absent'|'*undeleted'|'*undeletemodified'>} Resolves successfully with the file's git status
*
* @example
* let status = await git.status({ fs, dir: '/tutorial', filepath: 'README.md' })
* console.log(status)
*
*/
export function status({ fs: _fs, dir, gitdir, filepath, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir: string;
gitdir?: string;
filepath: string;
cache?: any;
}): Promise<"modified" | "ignored" | "unmodified" | "*modified" | "*deleted" | "*added" | "absent" | "deleted" | "added" | "*unmodified" | "*absent" | "*undeleted" | "*undeletemodified">;
/**
* Efficiently get the status of multiple files at once.
*
* The returned `StatusMatrix` is admittedly not the easiest format to read.
* 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;
* without having to do multiple, time-consuming isomorphic-git calls.
* My hope is that the speed and flexibility of the function will make up for the learning curve of interpreting the return value.
*
* ```js live
* // get the status of all the files in 'src'
* let status = await git.statusMatrix({
* fs,
* dir: '/tutorial',
* filter: f => f.startsWith('src/')
* })
* console.log(status)
* ```
*
* ```js live
* // get the status of all the JSON and Markdown files
* let status = await git.statusMatrix({
* fs,
* dir: '/tutorial',
* filter: f => f.endsWith('.json') || f.endsWith('.md')
* })
* console.log(status)
* ```
*
* The result is returned as a 2D array.
* The outer array represents the files and/or blobs in the repo, in alphabetical order.
* The inner arrays describe the status of the file:
* the first value is the filepath, and the next three are integers
* representing the HEAD status, WORKDIR status, and STAGE status of the entry.
*
* ```js
* // example StatusMatrix
* [
* ["a.txt", 0, 2, 0], // new, untracked
* ["b.txt", 0, 2, 2], // added, staged
* ["c.txt", 0, 2, 3], // added, staged, with unstaged changes
* ["d.txt", 1, 1, 1], // unmodified
* ["e.txt", 1, 2, 1], // modified, unstaged
* ["f.txt", 1, 2, 2], // modified, staged
* ["g.txt", 1, 2, 3], // modified, staged, with unstaged changes
* ["h.txt", 1, 0, 1], // deleted, unstaged
* ["i.txt", 1, 0, 0], // deleted, staged
* ["j.txt", 1, 2, 0], // deleted, staged, with unstaged-modified changes (new file of the same name)
* ["k.txt", 1, 1, 0], // deleted, staged, with unstaged changes (new file of the same name)
* ]
* ```
*
* - The HEAD status is either absent (0) or present (1).
* - The WORKDIR status is either absent (0), identical to HEAD (1), or different from HEAD (2).
* - The STAGE status is either absent (0), identical to HEAD (1), identical to WORKDIR (2), or different from WORKDIR (3).
*
* ```ts
* type Filename = string
* type HeadStatus = 0 | 1
* type WorkdirStatus = 0 | 1 | 2
* type StageStatus = 0 | 1 | 2 | 3
*
* type StatusRow = [Filename, HeadStatus, WorkdirStatus, StageStatus]
*
* type StatusMatrix = StatusRow[]
* ```
*
* > Think of the natural progression of file modifications as being from HEAD (previous) -> WORKDIR (current) -> STAGE (next).
* > Then HEAD is "version 1", WORKDIR is "version 2", and STAGE is "version 3".
* > Then, imagine a "version 0" which is before the file was created.
* > Then the status value in each column corresponds to the oldest version of the file it is identical to.
* > (For a file to be identical to "version 0" means the file is deleted.)
*
* Here are some examples of queries you can answer using the result:
*
* #### Q: What files have been deleted?
* ```js
* const FILE = 0, WORKDIR = 2
*
* const filenames = (await statusMatrix({ dir }))
* .filter(row => row[WORKDIR] === 0)
* .map(row => row[FILE])
* ```
*
* #### Q: What files have unstaged changes?
* ```js
* const FILE = 0, WORKDIR = 2, STAGE = 3
*
* const filenames = (await statusMatrix({ dir }))
* .filter(row => row[WORKDIR] !== row[STAGE])
* .map(row => row[FILE])
* ```
*
* #### Q: What files have been modified since the last commit?
* ```js
* const FILE = 0, HEAD = 1, WORKDIR = 2
*
* const filenames = (await statusMatrix({ dir }))
* .filter(row => row[HEAD] !== row[WORKDIR])
* .map(row => row[FILE])
* ```
*
* #### Q: What files will NOT be changed if I commit right now?
* ```js
* const FILE = 0, HEAD = 1, STAGE = 3
*
* const filenames = (await statusMatrix({ dir }))
* .filter(row => row[HEAD] === row[STAGE])
* .map(row => row[FILE])
* ```
*
* For reference, here are all possible combinations:
*
* | HEAD | WORKDIR | STAGE | `git status --short` equivalent |
* | ---- | ------- | ----- | ------------------------------- |
* | 0 | 0 | 0 | `` |
* | 0 | 0 | 3 | `AD` |
* | 0 | 2 | 0 | `??` |
* | 0 | 2 | 2 | `A ` |
* | 0 | 2 | 3 | `AM` |
* | 1 | 0 | 0 | `D ` |
* | 1 | 0 | 1 | ` D` |
* | 1 | 0 | 3 | `MD` |
* | 1 | 1 | 0 | `D ` + `??` |
* | 1 | 1 | 1 | `` |
* | 1 | 1 | 3 | `MM` |
* | 1 | 2 | 0 | `D ` + `??` |
* | 1 | 2 | 1 | ` M` |
* | 1 | 2 | 2 | `M ` |
* | 1 | 2 | 3 | `MM` |
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} [args.ref = 'HEAD'] - Optionally specify a different commit to compare against the workdir and stage instead of the HEAD
* @param {string[]} [args.filepaths = ['.']] - Limit the query to the given files and directories
* @param {function(string): boolean} [args.filter] - Filter the results to only those whose filepath matches a function.
* @param {object} [args.cache] - a [cache](cache.md) object
* @param {boolean} [args.ignored = false] - include ignored files in the result
*
* @returns {Promise<Array<StatusRow>>} Resolves with a status matrix, described below.
* @see StatusRow
*/
export function statusMatrix({ fs: _fs, dir, gitdir, ref, filepaths, filter, cache, ignored: shouldIgnore, }: {
fs: CallbackFsClient | PromiseFsClient;
dir: string;
gitdir?: string;
ref?: string;
filepaths?: string[];
filter?: (arg0: string) => boolean;
cache?: any;
ignored?: boolean;
}): Promise<[string, 0 | 1, 0 | 1 | 2, 0 | 1 | 2 | 3][]>;
/**
* Create a lightweight tag
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - What to name the tag
* @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.
* @param {boolean} [args.force = false] - Instead of throwing an error if a tag named `ref` already exists, overwrite the existing tag.
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.tag({ fs, dir: '/tutorial', ref: 'test-tag' })
* console.log('done')
*
*/
export function tag({ fs: _fs, dir, gitdir, ref, object, force, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref: string;
object?: string;
force?: boolean;
}): Promise<void>;
/**
* Register file contents in the working tree or object database to the git index (aka staging area).
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.filepath - File to act upon.
* @param {string} [args.oid] - OID of the object in the object database to add to the index with the specified filepath.
* @param {number} [args.mode = 100644] - The file mode to add the file to the index.
* @param {boolean} [args.add] - Adds the specified file to the index if it does not yet exist in the index.
* @param {boolean} [args.remove] - Remove the specified file from the index if it does not exist in the workspace anymore.
* @param {boolean} [args.force] - Remove the specified file from the index, even if it still exists in the workspace.
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<string | void>} Resolves successfully with the SHA-1 object id of the object written or updated in the index, or nothing if the file was removed.
*
* @example
* await git.updateIndex({
* fs,
* dir: '/tutorial',
* filepath: 'readme.md'
* })
*
* @example
* // Manually create a blob in the object database.
* let oid = await git.writeBlob({
* fs,
* dir: '/tutorial',
* blob: new Uint8Array([])
* })
*
* // Write the object in the object database to the index.
* await git.updateIndex({
* fs,
* dir: '/tutorial',
* add: true,
* filepath: 'readme.md',
* oid
* })
*/
export function updateIndex({ fs: _fs, dir, gitdir, cache, filepath, oid, mode, add, remove, force, }: {
fs: CallbackFsClient | PromiseFsClient;
dir: string;
gitdir?: string;
filepath: string;
oid?: string;
mode?: number;
add?: boolean;
remove?: boolean;
force?: boolean;
cache?: any;
}): Promise<string | void>;
/**
* Return the version number of isomorphic-git
*
* I don't know why you might need this. I added it just so I could check that I was getting
* the correct version of the library and not a cached version.
*
* @returns {string} the version string taken from package.json at publication time
*
* @example
* console.log(git.version())
*
*/
export function version(): string;
/**
* @callback WalkerMap
* @param {string} filename
* @param {Array<WalkerEntry | null>} entries
* @returns {Promise<any>}
*/
/**
* @callback WalkerReduce
* @param {any} parent
* @param {any[]} children
* @returns {Promise<any>}
*/
/**
* @callback WalkerIterateCallback
* @param {WalkerEntry[]} entries
* @returns {Promise<any[]>}
*/
/**
* @callback WalkerIterate
* @param {WalkerIterateCallback} walk
* @param {IterableIterator<WalkerEntry[]>} children
* @returns {Promise<any[]>}
*/
/**
* A powerful recursive tree-walking utility.
*
* The `walk` API simplifies gathering detailed information about a tree or comparing all the filepaths in two or more trees.
* Trees can be git commits, the working directory, or the or git index (staging area).
* As long as a file or directory is present in at least one of the trees, it will be traversed.
* Entries are traversed in alphabetical order.
*
* The arguments to `walk` are the `trees` you want to traverse, and 3 optional transform functions:
* `map`, `reduce`, and `iterate`.
*
* ## `TREE`, `WORKDIR`, and `STAGE`
*
* Tree walkers are represented by three separate functions that can be imported:
*
* ```js
* import { TREE, WORKDIR, STAGE } from 'isomorphic-git'
* ```
*
* These functions return opaque handles called `Walker`s.
* The only thing that `Walker` objects are good for is passing into `walk`.
* Here are the three `Walker`s passed into `walk` by the `statusMatrix` command for example:
*
* ```js
* let ref = 'HEAD'
*
* let trees = [TREE({ ref }), WORKDIR(), STAGE()]
* ```
*
* For the arguments, see the doc pages for [TREE](./TREE.md), [WORKDIR](./WORKDIR.md), and [STAGE](./STAGE.md).
*
* `map`, `reduce`, and `iterate` allow you control the recursive walk by pruning and transforming `WalkerEntry`s into the desired result.
*
* ## WalkerEntry
*
* {@link WalkerEntry typedef}
*
* `map` receives an array of `WalkerEntry[]` as its main argument, one `WalkerEntry` for each `Walker` in the `trees` argument.
* The methods are memoized per `WalkerEntry` so calling them multiple times in a `map` function does not adversely impact performance.
* By only computing these values if needed, you build can build lean, mean, efficient walking machines.
*
* ### WalkerEntry#type()
*
* Returns the kind as a string. This is normally either `tree` or `blob`.
*
* `TREE`, `STAGE`, and `WORKDIR` walkers all return a string.
*
* Possible values:
*
* - `'tree'` directory
* - `'blob'` file
* - `'special'` used by `WORKDIR` to represent irregular files like sockets and FIFOs
* - `'commit'` used by `TREE` to represent submodules
*
* ```js
* await entry.type()
* ```
*
* ### WalkerEntry#mode()
*
* Returns the file mode as a number. Use this to distinguish between regular files, symlinks, and executable files.
*
* `TREE`, `STAGE`, and `WORKDIR` walkers all return a number for all `type`s of entries.
*
* It has been normalized to one of the 4 values that are allowed in git commits:
*
* - `0o40000` directory
* - `0o100644` file
* - `0o100755` file (executable)
* - `0o120000` symlink
*
* Tip: to make modes more readable, you can print them to octal using `.toString(8)`.
*
* ```js
* await entry.mode()
* ```
*
* ### WalkerEntry#oid()
*
* Returns the SHA-1 object id for blobs and trees.
*
* `TREE` walkers return a string for `blob` and `tree` entries.
*
* `STAGE` and `WORKDIR` walkers return a string for `blob` entries and `undefined` for `tree` entries.
*
* ```js
* await entry.oid()
* ```
*
* ### WalkerEntry#content()
*
* Returns the file contents as a Buffer.
*
* `TREE` and `WORKDIR` walkers return a Buffer for `blob` entries and `undefined` for `tree` entries.
*
* `STAGE` walkers always return `undefined` since the file contents are never stored in the stage.
*
* ```js
* await entry.content()
* ```
*
* ### WalkerEntry#stat()
*
* Returns a normalized subset of filesystem Stat data.
*
* `WORKDIR` walkers return a `Stat` for `blob` and `tree` entries.
*
* `STAGE` walkers return a `Stat` for `blob` entries and `undefined` for `tree` entries.
*
* `TREE` walkers return `undefined` for all entry types.
*
* ```js
* await entry.stat()
* ```
*
* {@link Stat typedef}
*
* ## map(string, Array<WalkerEntry|null>) => Promise<any>
*
* {@link WalkerMap typedef}
*
* This is the function that is called once per entry BEFORE visiting the children of that node.
*
* If you return `null` for a `tree` entry, then none of the children of that `tree` entry will be walked.
*
* This is a good place for query logic, such as examining the contents of a file.
* Ultimately, compare all the entries and return any values you are interested in.
* If you do not return a value (or return undefined) that entry will be filtered from the results.
*
* Example 1: Find all the files containing the word 'foo'.
* ```js
* async function map(filepath, [head, workdir]) {
* let content = (await workdir.content()).toString('utf8')
* if (content.contains('foo')) {
* return {
* filepath,
* content
* }
* }
* }
* ```
*
* Example 2: Return the difference between the working directory and the HEAD commit
* ```js
* const map = async (filepath, [head, workdir]) => {
* return {
* filepath,
* oid: await head?.oid(),
* diff: diff(
* (await head?.content())?.toString('utf8') || '',
* (await workdir?.content())?.toString('utf8') || ''
* )
* }
* }
* ```
*
* Example 3:
* ```js
* let path = require('path')
* // Only examine files in the directory `cwd`
* let cwd = 'src/app'
* async function map (filepath, [head, workdir, stage]) {
* if (
* // don't skip the root directory
* head.fullpath !== '.' &&
* // return true for 'src' and 'src/app'
* !cwd.startsWith(filepath) &&
* // return true for 'src/app/*'
* path.dirname(filepath) !== cwd
* ) {
* return null
* } else {
* return filepath
* }
* }
* ```
*
* ## reduce(parent, children)
*
* {@link WalkerReduce typedef}
*
* This is the function that is called once per entry AFTER visiting the children of that node.
*
* Default: `async (parent, children) => parent === undefined ? children.flat() : [parent, children].flat()`
*
* The default implementation of this function returns all directories and children in a giant flat array.
* You can define a different accumulation method though.
*
* Example: Return a hierarchical structure
* ```js
* async function reduce (parent, children) {
* return Object.assign(parent, { children })
* }
* ```
*
* ## iterate(walk, children)
*
* {@link WalkerIterate typedef}
*
* {@link WalkerIterateCallback typedef}
*
* Default: `(walk, children) => Promise.all([...children].map(walk))`
*
* The default implementation recurses all children concurrently using Promise.all.
* However you could use a custom function to traverse children serially or use a global queue to throttle recursion.
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {Walker[]} args.trees - The trees you want to traverse
* @param {WalkerMap} [args.map] - Transform `WalkerEntry`s into a result form
* @param {WalkerReduce} [args.reduce] - Control how mapped entries are combined with their parent result
* @param {WalkerIterate} [args.iterate] - Fine-tune how entries within a tree are iterated over
* @param {object} [args.cache] - a [cache](cache.md) object
*
* @returns {Promise<any>} The finished tree-walking result
*/
export function walk({ fs, dir, gitdir, trees, map, reduce, iterate, cache, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
trees: Walker[];
map?: WalkerMap;
reduce?: WalkerReduce;
iterate?: WalkerIterate;
cache?: any;
}): Promise<any>;
/**
* Write a blob object directly
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {Uint8Array} args.blob - The blob object to write
*
* @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object
*
* @example
* // Manually create a blob.
* let oid = await git.writeBlob({
* fs,
* dir: '/tutorial',
* blob: new Uint8Array([])
* })
*
* console.log('oid', oid) // should be 'e69de29bb2d1d6434b8b29ae775ad8c2e48c5391'
*
*/
export function writeBlob({ fs, dir, gitdir, blob }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
blob: Uint8Array;
}): Promise<string>;
/**
* Write a commit object directly
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {CommitObject} args.commit - The object to write
*
* @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object
* @see CommitObject
*
*/
export function writeCommit({ fs, dir, gitdir, commit, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
commit: CommitObject;
}): Promise<string>;
/**
* Write a git object directly
*
* `format` can have the following values:
*
* | param | description |
* | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* | 'deflated' | Treat `object` as the raw deflate-compressed buffer for an object, meaning can be written to `.git/objects/**` as-is. |
* | '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. |
* | 'content' | Treat `object` as the object buffer without the git header. |
* | 'parsed' | Treat `object` as a parsed representation of the object. |
*
* If `format` is `'parsed'`, then `object` must match one of the schemas for `CommitObject`, `TreeObject`, `TagObject`, or a `string` (for blobs).
*
* {@link CommitObject typedef}
*
* {@link TreeObject typedef}
*
* {@link TagObject typedef}
*
* If `format` is `'content'`, `'wrapped'`, or `'deflated'`, `object` should be a `Uint8Array`.
*
* @deprecated
* > This command is overly complicated.
* >
* > If you know the type of object you are writing, use [`writeBlob`](./writeBlob.md), [`writeCommit`](./writeCommit.md), [`writeTag`](./writeTag.md), or [`writeTree`](./writeTree.md).
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string | Uint8Array | CommitObject | TreeObject | TagObject} args.object - The object to write.
* @param {'blob'|'tree'|'commit'|'tag'} [args.type] - The kind of object to write.
* @param {'deflated' | 'wrapped' | 'content' | 'parsed'} [args.format = 'parsed'] - What format the object is in. The possible choices are listed below.
* @param {string} [args.oid] - If `format` is `'deflated'` then this param is required. Otherwise it is calculated.
* @param {string} [args.encoding] - If `type` is `'blob'` then `object` will be converted to a Uint8Array using `encoding`.
*
* @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object.
*
* @example
* // Manually create an annotated tag.
* let sha = await git.resolveRef({ fs, dir: '/tutorial', ref: 'HEAD' })
* console.log('commit', sha)
*
* let oid = await git.writeObject({
* fs,
* dir: '/tutorial',
* type: 'tag',
* object: {
* object: sha,
* type: 'commit',
* tag: 'my-tag',
* tagger: {
* name: 'your name',
* email: 'email@example.com',
* timestamp: Math.floor(Date.now()/1000),
* timezoneOffset: new Date().getTimezoneOffset()
* },
* message: 'Optional message'
* }
* })
*
* console.log('tag', oid)
*
*/
export function writeObject({ fs: _fs, dir, gitdir, type, object, format, oid, encoding, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
object: string | Uint8Array | TreeEntry[] | CommitObject | TagObject;
type?: "blob" | "tree" | "commit" | "tag";
format?: "parsed" | "deflated" | "content" | "wrapped";
oid?: string;
encoding?: string;
}): Promise<string>;
/**
* Write a ref which refers to the specified SHA-1 object id, or a symbolic ref which refers to the specified ref.
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {string} args.ref - The name of the ref to write
* @param {string} args.value - When `symbolic` is false, a ref or an SHA-1 object id. When true, a ref starting with `refs/`.
* @param {boolean} [args.force = false] - Instead of throwing an error if a ref named `ref` already exists, overwrite the existing ref.
* @param {boolean} [args.symbolic = false] - Whether the ref is symbolic or not.
*
* @returns {Promise<void>} Resolves successfully when filesystem operations are complete
*
* @example
* await git.writeRef({
* fs,
* dir: '/tutorial',
* ref: 'refs/heads/another-branch',
* value: 'HEAD'
* })
* await git.writeRef({
* fs,
* dir: '/tutorial',
* ref: 'HEAD',
* value: 'refs/heads/another-branch',
* force: true,
* symbolic: true
* })
* console.log('done')
*
*/
export function writeRef({ fs: _fs, dir, gitdir, ref, value, force, symbolic, }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
ref: string;
value: string;
force?: boolean;
symbolic?: boolean;
}): Promise<void>;
/**
* Write an annotated tag object directly
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {TagObject} args.tag - The object to write
*
* @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object
* @see TagObject
*
* @example
* // Manually create an annotated tag.
* let sha = await git.resolveRef({ fs, dir: '/tutorial', ref: 'HEAD' })
* console.log('commit', sha)
*
* let oid = await git.writeTag({
* fs,
* dir: '/tutorial',
* tag: {
* object: sha,
* type: 'commit',
* tag: 'my-tag',
* tagger: {
* name: 'your name',
* email: 'email@example.com',
* timestamp: Math.floor(Date.now()/1000),
* timezoneOffset: new Date().getTimezoneOffset()
* },
* message: 'Optional message'
* }
* })
*
* console.log('tag', oid)
*
*/
export function writeTag({ fs, dir, gitdir, tag }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
tag: TagObject;
}): Promise<string>;
/**
* Write a tree object directly
*
* @param {object} args
* @param {FsClient} args.fs - a file system client
* @param {string} [args.dir] - The [working tree](dir-vs-gitdir.md) directory path
* @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
* @param {TreeObject} args.tree - The object to write
*
* @returns {Promise<string>} Resolves successfully with the SHA-1 object id of the newly written object.
* @see TreeObject
* @see TreeEntry
*
*/
export function writeTree({ fs, dir, gitdir, tree }: {
fs: CallbackFsClient | PromiseFsClient;
dir?: string;
gitdir?: string;
tree: TreeEntry[];
}): Promise<string>;
declare class AlreadyExistsError extends BaseError {
/**
* @param {'note'|'remote'|'tag'|'branch'} noun
* @param {string} where
* @param {boolean} canForce
*/
constructor(noun: "tag" | "remote" | "note" | "branch", where: string, canForce?: boolean);
code: "AlreadyExistsError";
name: "AlreadyExistsError";
data: {
noun: "tag" | "remote" | "note" | "branch";
where: string;
canForce: boolean;
};
}
declare namespace AlreadyExistsError {
export const code: 'AlreadyExistsError';
}
declare class AmbiguousError extends BaseError {
/**
* @param {'oids'|'refs'} nouns
* @param {string} short
* @param {string[]} matches
*/
constructor(nouns: "refs" | "oids", short: string, matches: string[]);
code: "AmbiguousError";
name: "AmbiguousError";
data: {
nouns: "refs" | "oids";
short: string;
matches: string[];
};
}
declare namespace AmbiguousError {
const code_1: 'AmbiguousError';
export { code_1 as code };
}
declare class CheckoutConflictError extends BaseError {
/**
* @param {string[]} filepaths
*/
constructor(filepaths: string[]);
code: "CheckoutConflictError";
name: "CheckoutConflictError";
data: {
filepaths: string[];
};
}
declare namespace CheckoutConflictError {
const code_2: 'CheckoutConflictError';
export { code_2 as code };
}
declare class CommitNotFetchedError extends BaseError {
/**
* @param {string} ref
* @param {string} oid
*/
constructor(ref: string, oid: string);
code: "CommitNotFetchedError";
name: "CommitNotFetchedError";
data: {
ref: string;
oid: string;
};
}
declare namespace CommitNotFetchedError {
const code_3: 'CommitNotFetchedError';
export { code_3 as code };
}
declare class EmptyServerResponseError extends BaseError {
code: "EmptyServerResponseError";
name: "EmptyServerResponseError";
data: {};
}
declare namespace EmptyServerResponseError {
const code_4: 'EmptyServerResponseError';
export { code_4 as code };
}
declare class FastForwardError extends BaseError {
code: "FastForwardError";
name: "FastForwardError";
data: {};
}
declare namespace FastForwardError {
const code_5: 'FastForwardError';
export { code_5 as code };
}
declare class GitPushError extends BaseError {
/**
* @param {string} prettyDetails
* @param {PushResult} result
*/
constructor(prettyDetails: string, result: PushResult);
code: "GitPushError";
name: "GitPushError";
data: {
prettyDetails: string;
result: PushResult;
};
}
declare namespace GitPushError {
const code_6: 'GitPushError';
export { code_6 as code };
}
declare class HttpError extends BaseError {
/**
* @param {number} statusCode
* @param {string} statusMessage
* @param {string} response
*/
constructor(statusCode: number, statusMessage: string, response: string);
code: "HttpError";
name: "HttpError";
data: {
statusCode: number;
statusMessage: string;
response: string;
};
}
declare namespace HttpError {
const code_7: 'HttpError';
export { code_7 as code };
}
declare class InternalError extends BaseError {
/**
* @param {string} message
*/
constructor(message: string);
code: "InternalError";
name: "InternalError";
data: {
message: string;
};
}
declare namespace InternalError {
const code_8: 'InternalError';
export { code_8 as code };
}
declare class InvalidFilepathError extends BaseError {
/**
* @param {'leading-slash'|'trailing-slash'|'directory'} [reason]
*/
constructor(reason?: "leading-slash" | "trailing-slash" | "directory" | undefined);
code: "InvalidFilepathError";
name: "InvalidFilepathError";
data: {
reason: "leading-slash" | "trailing-slash" | "directory" | undefined;
};
}
declare namespace InvalidFilepathError {
const code_9: 'InvalidFilepathError';
export { code_9 as code };
}
declare class InvalidOidError extends BaseError {
/**
* @param {string} value
*/
constructor(value: string);
code: "InvalidOidError";
name: "InvalidOidError";
data: {
value: string;
};
}
declare namespace InvalidOidError {
const code_10: 'InvalidOidError';
export { code_10 as code };
}
declare class InvalidRefNameError extends BaseError {
/**
* @param {string} ref
* @param {string} suggestion
* @param {boolean} canForce
*/
constructor(ref: string, suggestion: string);
code: "InvalidRefNameError";
name: "InvalidRefNameError";
data: {
ref: string;
suggestion: string;
};
}
declare namespace InvalidRefNameError {
const code_11: 'InvalidRefNameError';
export { code_11 as code };
}
declare class MaxDepthError extends BaseError {
/**
* @param {number} depth
*/
constructor(depth: number);
code: "MaxDepthError";
name: "MaxDepthError";
data: {
depth: number;
};
}
declare namespace MaxDepthError {
const code_12: 'MaxDepthError';
export { code_12 as code };
}
declare class MergeNotSupportedError extends BaseError {
code: "MergeNotSupportedError";
name: "MergeNotSupportedError";
data: {};
}
declare namespace MergeNotSupportedError {
const code_13: 'MergeNotSupportedError';
export { code_13 as code };
}
declare class MergeConflictError extends BaseError {
/**
* @param {Array<string>} filepaths
* @param {Array<string>} bothModified
* @param {Array<string>} deleteByUs
* @param {Array<string>} deleteByTheirs
*/
constructor(filepaths: string[], bothModified: string[], deleteByUs: string[], deleteByTheirs: string[]);
code: "MergeConflictError";
name: "MergeConflictError";
data: {
filepaths: string[];
bothModified: string[];
deleteByUs: string[];
deleteByTheirs: string[];
};
}
declare namespace MergeConflictError {
const code_14: 'MergeConflictError';
export { code_14 as code };
}
declare class MissingNameError extends BaseError {
/**
* @param {'author'|'committer'|'tagger'} role
*/
constructor(role: "author" | "committer" | "tagger");
code: "MissingNameError";
name: "MissingNameError";
data: {
role: "author" | "committer" | "tagger";
};
}
declare namespace MissingNameError {
const code_15: 'MissingNameError';
export { code_15 as code };
}
declare class MissingParameterError extends BaseError {
/**
* @param {string} parameter
*/
constructor(parameter: string);
code: "MissingParameterError";
name: "MissingParameterError";
data: {
parameter: string;
};
}
declare namespace MissingParameterError {
const code_16: 'MissingParameterError';
export { code_16 as code };
}
declare class MultipleGitError extends BaseError {
/**
* @param {Error[]} errors
* @param {string} message
*/
constructor(errors: Error[]);
code: "MultipleGitError";
name: "MultipleGitError";
data: {
errors: Error[];
};
errors: Error[];
}
declare namespace MultipleGitError {
const code_17: 'MultipleGitError';
export { code_17 as code };
}
declare class NoRefspecError extends BaseError {
/**
* @param {string} remote
*/
constructor(remote: string);
code: "NoRefspecError";
name: "NoRefspecError";
data: {
remote: string;
};
}
declare namespace NoRefspecError {
const code_18: 'NoRefspecError';
export { code_18 as code };
}
declare class NotFoundError extends BaseError {
/**
* @param {string} what
*/
constructor(what: string);
code: "NotFoundError";
name: "NotFoundError";
data: {
what: string;
};
}
declare namespace NotFoundError {
const code_19: 'NotFoundError';
export { code_19 as code };
}
declare class ObjectTypeError extends BaseError {
/**
* @param {string} oid
* @param {'blob'|'commit'|'tag'|'tree'} actual
* @param {'blob'|'commit'|'tag'|'tree'} expected
* @param {string} [filepath]
*/
constructor(oid: string, actual: "blob" | "tree" | "commit" | "tag", expected: "blob" | "tree" | "commit" | "tag", filepath?: string | undefined);
code: "ObjectTypeError";
name: "ObjectTypeError";
data: {
oid: string;
actual: "blob" | "tree" | "commit" | "tag";
expected: "blob" | "tree" | "commit" | "tag";
filepath: string | undefined;
};
}
declare namespace ObjectTypeError {
const code_20: 'ObjectTypeError';
export { code_20 as code };
}
declare class ParseError extends BaseError {
/**
* @param {string} expected
* @param {string} actual
*/
constructor(expected: string, actual: string);
code: "ParseError";
name: "ParseError";
data: {
expected: string;
actual: string;
};
}
declare namespace ParseError {
const code_21: 'ParseError';
export { code_21 as code };
}
declare class PushRejectedError extends BaseError {
/**
* @param {'not-fast-forward'|'tag-exists'} reason
*/
constructor(reason: "not-fast-forward" | "tag-exists");
code: "PushRejectedError";
name: "PushRejectedError";
data: {
reason: "not-fast-forward" | "tag-exists";
};
}
declare namespace PushRejectedError {
const code_22: 'PushRejectedError';
export { code_22 as code };
}
declare class RemoteCapabilityError extends BaseError {
/**
* @param {'shallow'|'deepen-since'|'deepen-not'|'deepen-relative'} capability
* @param {'depth'|'since'|'exclude'|'relative'} parameter
*/
constructor(capability: "shallow" | "deepen-since" | "deepen-not" | "deepen-relative", parameter: "depth" | "since" | "exclude" | "relative");
code: "RemoteCapabilityError";
name: "RemoteCapabilityError";
data: {
capability: "shallow" | "deepen-since" | "deepen-not" | "deepen-relative";
parameter: "depth" | "since" | "exclude" | "relative";
};
}
declare namespace RemoteCapabilityError {
const code_23: 'RemoteCapabilityError';
export { code_23 as code };
}
declare class SmartHttpError extends BaseError {
/**
* @param {string} preview
* @param {string} response
*/
constructor(preview: string, response: string);
code: "SmartHttpError";
name: "SmartHttpError";
data: {
preview: string;
response: string;
};
}
declare namespace SmartHttpError {
const code_24: 'SmartHttpError';
export { code_24 as code };
}
declare class UnknownTransportError extends BaseError {
/**
* @param {string} url
* @param {string} transport
* @param {string} [suggestion]
*/
constructor(url: string, transport: string, suggestion?: string | undefined);
code: "UnknownTransportError";
name: "UnknownTransportError";
data: {
url: string;
transport: string;
suggestion: string | undefined;
};
}
declare namespace UnknownTransportError {
const code_25: 'UnknownTransportError';
export { code_25 as code };
}
declare class UnsafeFilepathError extends BaseError {
/**
* @param {string} filepath
*/
constructor(filepath: string);
code: "UnsafeFilepathError";
name: "UnsafeFilepathError";
data: {
filepath: string;
};
}
declare namespace UnsafeFilepathError {
const code_26: 'UnsafeFilepathError';
export { code_26 as code };
}
declare class UrlParseError extends BaseError {
/**
* @param {string} url
*/
constructor(url: string);
code: "UrlParseError";
name: "UrlParseError";
data: {
url: string;
};
}
declare namespace UrlParseError {
const code_27: 'UrlParseError';
export { code_27 as code };
}
declare class UserCanceledError extends BaseError {
code: "UserCanceledError";
name: "UserCanceledError";
data: {};
}
declare namespace UserCanceledError {
const code_28: 'UserCanceledError';
export { code_28 as code };
}
declare class UnmergedPathsError extends BaseError {
/**
* @param {Array<string>} filepaths
*/
constructor(filepaths: string[]);
code: "UnmergedPathsError";
name: "UnmergedPathsError";
data: {
filepaths: string[];
};
}
declare namespace UnmergedPathsError {
const code_29: 'UnmergedPathsError';
export { code_29 as code };
}
declare class IndexResetError extends BaseError {
/**
* @param {Array<string>} filepaths
*/
constructor(filepath: any);
code: "IndexResetError";
name: "IndexResetError";
data: {
filepath: any;
};
}
declare namespace IndexResetError {
const code_30: 'IndexResetError';
export { code_30 as code };
}
/**
* @typedef {Object} GitProgressEvent
* @property {string} phase
* @property {number} loaded
* @property {number} total
*/
/**
* @callback ProgressCallback
* @param {GitProgressEvent} progress
* @returns {void | Promise<void>}
*/
/**
* @typedef {Object} GitHttpRequest
* @property {string} url - The URL to request
* @property {string} [method='GET'] - The HTTP method to use
* @property {Object<string, string>} [headers={}] - Headers to include in the HTTP request
* @property {Object} [agent] - An HTTP or HTTPS agent that manages connections for the HTTP client (Node.js only)
* @property {AsyncIterableIterator<Uint8Array>} [body] - An async iterator of Uint8Arrays that make up the body of POST requests
* @property {ProgressCallback} [onProgress] - Reserved for future use (emitting `GitProgressEvent`s)
* @property {object} [signal] - Reserved for future use (canceling a request)
*/
/**
* @typedef {Object} GitHttpResponse
* @property {string} url - The final URL that was fetched after any redirects
* @property {string} [method] - The HTTP method that was used
* @property {Object<string, string>} [headers] - HTTP response headers
* @property {AsyncIterableIterator<Uint8Array>} [body] - An async iterator of Uint8Arrays that make up the body of the response
* @property {number} statusCode - The HTTP status code
* @property {string} statusMessage - The HTTP status message
*/
/**
* @callback HttpFetch
* @param {GitHttpRequest} request
* @returns {Promise<GitHttpResponse>}
*/
/**
* @typedef {Object} HttpClient
* @property {HttpFetch} request
*/
/**
* A git commit object.
*
* @typedef {Object} CommitObject
* @property {string} message Commit message
* @property {string} tree SHA-1 object id of corresponding file tree
* @property {string[]} parent an array of zero or more SHA-1 object ids
* @property {Object} author
* @property {string} author.name The author's name
* @property {string} author.email The author's email
* @property {number} author.timestamp UTC Unix timestamp in seconds
* @property {number} author.timezoneOffset Timezone difference from UTC in minutes
* @property {Object} committer
* @property {string} committer.name The committer's name
* @property {string} committer.email The committer's email
* @property {number} committer.timestamp UTC Unix timestamp in seconds
* @property {number} committer.timezoneOffset Timezone difference from UTC in minutes
* @property {string} [gpgsig] PGP signature (if present)
*/
/**
* An entry from a git tree object. Files are called 'blobs' and directories are called 'trees'.
*
* @typedef {Object} TreeEntry
* @property {string} mode the 6 digit hexadecimal mode
* @property {string} path the name of the file or directory
* @property {string} oid the SHA-1 object id of the blob or tree
* @property {'commit'|'blob'|'tree'} type the type of object
*/
/**
* A git tree object. Trees represent a directory snapshot.
*
* @typedef {TreeEntry[]} TreeObject
*/
/**
* A git annotated tag object.
*
* @typedef {Object} TagObject
* @property {string} object SHA-1 object id of object being tagged
* @property {'blob' | 'tree' | 'commit' | 'tag'} type the type of the object being tagged
* @property {string} tag the tag name
* @property {Object} tagger
* @property {string} tagger.name the tagger's name
* @property {string} tagger.email the tagger's email
* @property {number} tagger.timestamp UTC Unix timestamp in seconds
* @property {number} tagger.timezoneOffset timezone difference from UTC in minutes
* @property {string} message tag message
* @property {string} [gpgsig] PGP signature (if present)
*/
/**
* @typedef {Object} ReadCommitResult
* @property {string} oid - SHA-1 object id of this commit
* @property {CommitObject} commit - the parsed commit object
* @property {string} payload - PGP signing payload
*/
/**
* @typedef {Object} ServerRef - This object has the following schema:
* @property {string} ref - The name of the ref
* @property {string} oid - The SHA-1 object id the ref points to
* @property {string} [target] - The target ref pointed to by a symbolic ref
* @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
*/
/**
* @typedef Walker
* @property {Symbol} Symbol('GitWalkerSymbol')
*/
/**
* Normalized subset of filesystem `stat` data:
*
* @typedef {Object} Stat
* @property {number} ctimeSeconds
* @property {number} ctimeNanoseconds
* @property {number} mtimeSeconds
* @property {number} mtimeNanoseconds
* @property {number} dev
* @property {number} ino
* @property {number} mode
* @property {number} uid
* @property {number} gid
* @property {number} size
*/
/**
* The `WalkerEntry` is an interface that abstracts computing many common tree / blob stats.
*
* @typedef {Object} WalkerEntry
* @property {function(): Promise<'tree'|'blob'|'special'|'commit'>} type
* @property {function(): Promise<number>} mode
* @property {function(): Promise<string>} oid
* @property {function(): Promise<Uint8Array|void>} content
* @property {function(): Promise<Stat>} stat
*/
/**
* @typedef {Object} CallbackFsClient
* @property {function} readFile - https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback
* @property {function} writeFile - https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback
* @property {function} unlink - https://nodejs.org/api/fs.html#fs_fs_unlink_path_callback
* @property {function} readdir - https://nodejs.org/api/fs.html#fs_fs_readdir_path_options_callback
* @property {function} mkdir - https://nodejs.org/api/fs.html#fs_fs_mkdir_path_mode_callback
* @property {function} rmdir - https://nodejs.org/api/fs.html#fs_fs_rmdir_path_callback
* @property {function} stat - https://nodejs.org/api/fs.html#fs_fs_stat_path_options_callback
* @property {function} lstat - https://nodejs.org/api/fs.html#fs_fs_lstat_path_options_callback
* @property {function} [readlink] - https://nodejs.org/api/fs.html#fs_fs_readlink_path_options_callback
* @property {function} [symlink] - https://nodejs.org/api/fs.html#fs_fs_symlink_target_path_type_callback
* @property {function} [chmod] - https://nodejs.org/api/fs.html#fs_fs_chmod_path_mode_callback
*/
/**
* @typedef {Object} PromiseFsClient
* @property {Object} promises
* @property {function} promises.readFile - https://nodejs.org/api/fs.html#fs_fspromises_readfile_path_options
* @property {function} promises.writeFile - https://nodejs.org/api/fs.html#fs_fspromises_writefile_file_data_options
* @property {function} promises.unlink - https://nodejs.org/api/fs.html#fs_fspromises_unlink_path
* @property {function} promises.readdir - https://nodejs.org/api/fs.html#fs_fspromises_readdir_path_options
* @property {function} promises.mkdir - https://nodejs.org/api/fs.html#fs_fspromises_mkdir_path_options
* @property {function} promises.rmdir - https://nodejs.org/api/fs.html#fs_fspromises_rmdir_path
* @property {function} promises.stat - https://nodejs.org/api/fs.html#fs_fspromises_stat_path_options
* @property {function} promises.lstat - https://nodejs.org/api/fs.html#fs_fspromises_lstat_path_options
* @property {function} [promises.readlink] - https://nodejs.org/api/fs.html#fs_fspromises_readlink_path_options
* @property {function} [promises.symlink] - https://nodejs.org/api/fs.html#fs_fspromises_symlink_target_path_type
* @property {function} [promises.chmod] - https://nodejs.org/api/fs.html#fs_fspromises_chmod_path_mode
*/
/**
* @typedef {CallbackFsClient | PromiseFsClient} FsClient
*/
/**
* @callback MessageCallback
* @param {string} message
* @returns {void | Promise<void>}
*/
/**
* @typedef {Object} GitAuth
* @property {string} [username]
* @property {string} [password]
* @property {Object<string, string>} [headers]
* @property {boolean} [cancel] Tells git to throw a `UserCanceledError` (instead of an `HttpError`).
*/
/**
* @callback AuthCallback
* @param {string} url
* @param {GitAuth} auth Might have some values if the URL itself originally contained a username or password.
* @returns {GitAuth | void | Promise<GitAuth | void>}
*/
/**
* @callback AuthFailureCallback
* @param {string} url
* @param {GitAuth} auth The credentials that failed
* @returns {GitAuth | void | Promise<GitAuth | void>}
*/
/**
* @callback AuthSuccessCallback
* @param {string} url
* @param {GitAuth} auth
* @returns {void | Promise<void>}
*/
/**
* @typedef {Object} SignParams
* @property {string} payload - a plaintext message
* @property {string} secretKey - an 'ASCII armor' encoded PGP key (technically can actually contain _multiple_ keys)
*/
/**
* @callback SignCallback
* @param {SignParams} args
* @return {{signature: string} | Promise<{signature: string}>} - an 'ASCII armor' encoded "detached" signature
*/
/**
* @typedef {Object} MergeDriverParams
* @property {Array<string>} branches
* @property {Array<string>} contents
* @property {string} path
*/
/**
* @callback MergeDriverCallback
* @param {MergeDriverParams} args
* @return {{cleanMerge: boolean, mergedText: string} | Promise<{cleanMerge: boolean, mergedText: string}>}
*/
/**
* @callback WalkerMap
* @param {string} filename
* @param {WalkerEntry[]} entries
* @returns {Promise<any>}
*/
/**
* @callback WalkerReduce
* @param {any} parent
* @param {any[]} children
* @returns {Promise<any>}
*/
/**
* @callback WalkerIterateCallback
* @param {WalkerEntry[]} entries
* @returns {Promise<any[]>}
*/
/**
* @callback WalkerIterate
* @param {WalkerIterateCallback} walk
* @param {IterableIterator<WalkerEntry[]>} children
* @returns {Promise<any[]>}
*/
/**
* @typedef {Object} RefUpdateStatus
* @property {boolean} ok
* @property {string} error
*/
/**
* @typedef {Object} PushResult
* @property {boolean} ok
* @property {?string} error
* @property {Object<string, RefUpdateStatus>} refs
* @property {Object<string, string>} [headers]
*/
/**
* @typedef {0|1} HeadStatus
*/
/**
* @typedef {0|1|2} WorkdirStatus
*/
/**
* @typedef {0|1|2|3} StageStatus
*/
/**
* @typedef {[string, HeadStatus, WorkdirStatus, StageStatus]} StatusRow
*/
declare class BaseError extends Error {
constructor(message: any);
caller: string;
toJSON(): {
code: any;
data: any;
caller: string;
message: string;
stack: string | undefined;
};
fromJSON(json: any): BaseError;
get isIsomorphicGitError(): boolean;
}