git-utils v2.2.0
Lightweight git
automation for JavascriptAll methods return a promise.
You can use
git-utils/lib/commit
-style imports to avoid loading the entire library.Branches
Commits
Files
Remotes
Status
Tags
Versions
API Reference
addBranch(repo: string, branch: string): Promise<void>
Create a new branch based off the current branch.Back to top
deleteBranch(repo: string, branch: string, opts?: Object): Promise<void>
Delete the given branch.Options:
remote?: string
remoteOnly?: boolean
The
remote
option lets you delete both the local and remote branches of the same name.The
remoteOnly
option lets you delete the remote branch only. By default, both the local and remote tags are deleted.Back to top
getBranch(repo: string)
Get the current branch name.Back to top
getBranches(repo: string, opts?: Object): Promise<mixed>
Get an array of local/remote branch names.Options:
raw?: boolean
remote?: string
The
raw
option changes the return value to the stdout of the git branch
command.The
remote
option lets you inspect the branches of a remote repository.Back to top
hasBranch(repo: string, branch: string, opts?: Object): Promise<boolean>
Check if a local/remote branch name exists.Options:
remote?: boolean
The
remote
option lets you check a remote repository for a specific branch name.Back to top
mergeBranch(repo: string, opts: Object): Promise<void>
Merge a branch into another.Options:
ours?: string
theirs: string
strategy?: string
The
ours
option lets you choose the local destination branch. Defaults to the current branch.The
theirs
option lets you choose the local branch being merged. This is required.The
strategy
option lets you auto-resolve any merge conflicts. If defined, it must be "ours"
or "theirs"
.Back to top
pushBranch(repo: string, opts?: Object): Promise<void>
Push the current branch to a remote repository.Options:
force?: boolean
remote?: string
branch?: string
keyPath?: string
upstream?: boolean
listener?: (stderr?: string, stdout?: string) => void
The
force
option overwrites the remote branch instead of trying to cleanly append to its commit history.The
remote
option lets you choose which remote repository is pushed to. Defaults to origin
.The
branch
option lets you choose which remote branch is pushed to. Defaults to the name of the current local branch.The
keyPath
option is the file path to an SSH key. This is used to define the GIT_SSH_COMMAND
environment variable.The
upstream
option sets the upstream branch of the current local branch to the branch
option.The
listener
option is called as output is piped from the git push
command.Back to top
resetBranch(repo: string, commit?: string, opts?: Object): Promise<void>
Set the HEAD commit of the current branch.The
commit
argument defaults to "HEAD"
. If null, the entire commit history is thrown out for the current branch.Options:
mode?: string
The
mode
option must be "soft"
, "hard"
, "mixed"
, "merge"
, or "keep"
. Defaults to "mixed"
.The
"soft"
mode preserves the changes between the given commit
and the previous HEAD commit. Any staged changes are kept staged.The
"hard"
mode erases all changes between the given commit
and the previous HEAD commit.The
"mixed"
mode preserves the changes between the given commit
and the previous HEAD commit. Any staged changes are unstaged.The other modes are described in the
git
manual. Run man git-reset
in the terminal.Back to top
setBranch(repo: string, branch: string, opts?: Object): Promise<string>
Checkout the given branch
name.Resolves with the current branch name. May not be the given
branch
name depending on which options are used.If the given
branch
exists, the current branch must have no changes.If the given
branch
does not exist, it's created with the commit history (and any uncommitted changes) of the current branch.Options:
force?: boolean
ifExists?: boolean
mustExist?: boolean
The
force
option lets you erase any uncommitted changes before switching branches.The
ifExists
option avoids creating a new branch if the given branch
does not exist.The
mustExist
option will throw an error if the given branch
does not exist.Back to top
clone(repo: string, src: string, opts?: Object): Promise<void>
Clone a local/remote repository.The
src
argument can be a URL or an absolute path to a local directory.Options:
dest?: string
depth?: number
branch?: string
The
dest
option lets you choose the local path to the cloned repository.The
depth
option lets you create a shallow clone.The
branch
option lets you choose which branch to checkout.commit(repo: string, message: string): Promise<string>
Create a commit from the staged changes.The
message
can have any number of lines.Resolves with the commit SHA.
Back to top
getHead(repo: string, branch?: string, opts?: Object): Promise<mixed>
Resolves with the SHA of the HEAD commit.If no
branch
is given, use the current branch.Options:
remote?: string
message?: boolean
The
remote
option lets you inspect a remote repository.
When undefined, the local repository is used.The
message
option causes the resolved value to become
{id, message}
where id
is the SHA and message
is the commit message.Back to top
Back to top
pick(repo: string, commit: mixed, opts?: Object): Promise<void>
Perform a cherry-pick.The
commit
argument can be a SHA string or a {from, to}
object
where both from
and to
are SHA strings.Options:
strategy: string
The
strategy
option must be either "ours"
or "theirs"
. This option
is used to auto-resolve merge conflicts.Back to top
revertHead(repo: string): Promise<void>
Undo the last commit, but keep the changes in the staging area.Back to top
diff(repo: string, fromCommit: string, toCommit?: string): Promise<Array>
Get an array of {status: string, path: string}
objects for each file modified, added, or deleted by the inclusive range of given commits.The
toCommit
argument defaults to "HEAD"
.Back to top
popStash(repo: string): Promise<void>
Equivalent to git stash pop
.Back to top
pushStash(repo: string, opts?: Object): Promise<void>
Equivalent to git stash
.Options:
keepStaged?: boolean
keepUntracked?: boolean
The
keepStaged
option avoids stashing any staged changes.The
keepUntracked
option avoids stashing any untracked files.Back to top
removeFiles(repo: string, files: mixed, opts?: Object): Promise<void>
Remove files and stage them.The
files
argument must be a file path or an array of file paths.Options:
cached?: boolean
recursive?: boolean
The
cached
option lets you remove only the paths that have staged changes.The
recursive
option lets you remove directories.Back to top
renameFile(repo: string, oldName: string, newName: string): Promise<void>
Rename a file and stage it.The given filenames can be relative or absolute, but cannot exist outside the repository.
Back to top
revertFiles(repo: string, files: mixed, opts?: Object): Promise<string>
Revert files to a specific commit.Resolves with the stdout of the
git checkout
command.The
files
argument must be a file path or an array of file paths.Options:
commit?: string
dryRun?: boolean
The
commit
option lets you choose which commit to revert to. Defaults to "HEAD"
.The
dryRun
option avoids actually changing any files.Back to top
stageFiles(repo: string, files: mixed): Promise<void>
Stage the given file paths.The
files
argument must be a file path or an array of file paths.Back to top
unstageFiles(repo: string, files: mixed): Promise<void>
Unstage the given file paths.The
files
argument must be a file path or an array of file paths.Back to top
getRemotes(repo: string): Promise<Array>
Get the array of remote repositories, where each repository is an object like {push: string, fetch: string}
.Back to top
getStatus(repo: string, opts?: Object): Promise<mixed>
Get the status of the current branch.By default, the return value is an object like the following:
staged: Object
tracked: Object
untracked: Array
unmerged: Array
The
staged
object has an array for every status (eg: "M"
for modified, "A"
for added, etc). These arrays contain an object for every staged file with that status.The
tracked
object has identical structure to the staged
object, except it contains objects for tracked files (excluding staged files).The
untracked
and unmerged
arrays also contain file objects.Options:
raw?: boolean
remote?: boolean
The
raw
option changes the return value to the stdout of the git status
command. It does nothing when the remote
option is true.The
remote
option changes the return value to {branch: string, ahead: number, behind: number}
based on the upstream branch.Back to top
isClean(repo: string): Promise<boolean>
Resolves to true if the repository has no uncommitted changes.Back to top
isStaged(repo: string): Promise<boolean>
Resolves to true if the repository has staged changes.Back to top
addTag(repo: string, tag: string, opts?: Object): Promise<void>
Create a tag for the current HEAD commit.Options:
force?: boolean
The
force
option lets you overwrite an existing tag with the same name.Back to top
deleteTag(repo: string, tag: string, opts?: Object): Promise<void>
Delete a local/remote tag.Options:
remote?: string
remoteOnly?: boolean
The
remote
option lets you delete the given tag
from a remote repository.The
remoteOnly
option lets you delete the remote tag only. By default, both the local and remote tags are deleted.Back to top
getTags(repo: string, opts?: Object): Promise<Array>
Get an array of local/remote tag names.Options:
remote?: string
commits?: boolean
The
remote
option lets you fetch tags from a remote repository.The
commits
option changes the return value to an array of {tag: string, commit: string}
objects.Back to top
pushTag(repo: string, tag: string, opts?: Object): Promise<void>
Push a local tag to a remote repository.Options:
force?: boolean
remote?: string
The
force
option lets you overwrite an existing remote tag of the same name.The
remote
option lets you choose the remote repository to push to. Defaults to "origin"
.Back to top
pushTags(repo: string, opts?: Object): Promise<void>
Push all local tags to a remote repository.Options:
force?: boolean
remote?: string
The
force
option lets you overwrite any existing remote tags that clash with one of the local tags.The
remote
option lets you choose the remote repository to push to. Defaults to "origin"
.Back to top
getVersions(repo: string, opts?: Object): Promise<Array>
Get the sorted array of tags that use semantic versioning.Options:
remote?: string
The
remote
option lets you fetch tags that use semantic versioning from a remote repository.Back to top