@cush/git-utils
v2.2.0
Published
Git automation for Javascript
Downloads
2
Readme
git-utils v2.2.0
Lightweight git
automation for Javascript
All methods return a promise.
You can use git-utils/lib/commit
-style imports to avoid loading the entire library.
Branches
- addBranch: Equivalent to
git checkout -b <branch>
- deleteBranch: Equivalent to
git branch -D <branch>
- getBranch: Get the current branch name
- getBranches: Get the list of branch names (local or remote)
- hasBranch: Returns true if the given branch name exists
- mergeBranch: Equivalent to
git merge
- pushBranch: Equivalent to
git push
- resetBranch: Equivalent to
git reset <commitish>
- setBranch: Change the current branch
Commits
- clone: Equivalent to
git clone
- commit: Equivalent to
git commit -m <message>
- getHead: Get the SHA of the HEAD commit
- pick: Equivalent to
git cherry-pick <commitish>
- revertHead: Undo the HEAD commit but keep its changes
Files
- diff: Equivalent to
git diff
- popStash: Equivalent to
git stash pop
- pushStash: Equivalent to
git stash
- removeFiles: Equivalent to
git rm
- renameFile: Equivalent to
git mv
- resetFiles: Equivalent to
git checkout <commitish> -- <paths>
- stageFiles: Equivalent to
git add
- unstageFiles: Equivalent to
git reset -- <paths>
Remotes
- getRemotes: Equivalent to
git remote
Status
- getStatus: Equivalent to
git status
- isClean: Returns true if the working tree has no changes
- isStaged: Returns true if staged changes exist
Tags
- addTag: Equivalent to
git tag <tag>
- deleteTag: Equivalent to
git tag -d <tag>
- getTags: Equivalent to
git tag
- pushTag: Equivalent to
git push <remote> <tag>
- pushTags: Equivalent to
git push --tags
Versions
- getVersions: Get a sorted array of valid versions
API Reference
addBranch(repo: string, branch: string): Promise<void>
Create a new branch based off the current branch.
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.
getBranch(repo: string)
Get the current branch name.
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.
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.
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"
.
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.
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.
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.
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.
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.
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.
revertHead(repo: string): Promise<void>
Undo the last commit, but keep the changes in the staging area.
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"
.
popStash(repo: string): Promise<void>
Equivalent to git stash pop
.
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.
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.
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.
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.
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.
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.
getRemotes(repo: string): Promise<Array>
Get the array of remote repositories, where each repository is an object like {push: string, fetch: string}
.
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.
isClean(repo: string): Promise<boolean>
Resolves to true if the repository has no uncommitted changes.
isStaged(repo: string): Promise<boolean>
Resolves to true if the repository has staged changes.
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.
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.
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.
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"
.
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"
.
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.