Atom and all repositories under Atom will be archived on December 15, 2022. Learn more in our official announcement
Git Node module 
Helpers for working with Git repositories built natively on top of libgit2.
Installing
npm install git-utilsDevelopment
- Clone the repository
- Run
npm run prepareto get the submodule - Run
npm install - Run
npm testto run the specs
Docs
git.open(path, [search = true])
Open the repository at the given path. This will return null if the
repository at the given path does not exist or cannot be opened.
path - The path from which to try to open a repository
search - Set to false if we shouldn't search up in the directory tree
git = require 'git-utils'
repository = git.open('/Users/me/repos/node')The opened repository will have a submodules property that will be an object
of paths mapped to submodule {Repository} objects. The path keys will be
relative to the opened repository's working directory.
If search is set to true (the default), all paths up to the filesystem root will be recursively checked to try and find the root directory of a repository. If a search is false, traversing not be performed, and a repository will only be returned if the given path is the root of a repository.
Repository.checkoutHead(path)
Restore the contents of a path in the working directory and index to the
version at HEAD. Similar to running git reset HEAD -- <path> and then a
git checkout HEAD -- <path>.
path - The string repository-relative path to checkout.
Returns true if the checkout was successful, false otherwise.
Repository.checkoutReference(reference, [create])
Checks out a branch in your repository.
reference - The string reference to checkout
create - A Boolean value which, if true creates the new reference if it doesn't exist.
Returns true if the checkout was successful, false otherwise.
Repository.getAheadBehindCount(branch)
Get the number of commits the branch is ahead/behind the remote branch it
is tracking. Similar to the commit numbers reported by git status when a
remote tracking branch exists.
branch - The branch name to lookup ahead/behind counts for. (default: HEAD)
Returns an object with ahead and behind keys pointing to integer values
that will always be >= 0.
Repository.getCommitCount(fromCommit, toCommit)
Get the number of commits between fromCommit and toCommit.
fromCommit - The string commit SHA-1 to start the rev walk at.
toCommit - The string commit SHA-1 to end the rev walk at.
Returns the number of commits between the two, always >= 0.
Repository.getConfigValue(key)
Get the config value of the given key.
key - The string key to retrieve the value for.
Returns the configuration value, may be null.
Repository.setConfigValue(key, value)
Get the config value of the given key.
key - The string key to set in the config.
value - The string value to set in the config for the given key.
Returns true if setting the config value was successful, false otherwise.
Repository.getDiffStats(path)
Get the number of lines added and removed comparing the working directory contents of the given path to the HEAD version of the given path.
path - The string repository-relative path to diff.
Returns an object with added and deleted keys pointing to integer values
that always be >= 0.
Repository.getHeadBlob(path)
Get the blob contents of the given path at HEAD. Similar to
git show HEAD:<path>.
path - The string repository-relative path.
Returns the string contents of the HEAD version of the path.
Repository.getHead()
Get the reference or SHA-1 that HEAD points to such as refs/heads/master
or a full SHA-1 if the repository is in a detached HEAD state.
Returns the string reference name or SHA-1.
Repository.getIndexBlob(path)
Get the blob contents of the given path in the index. Similar to
git show :<path>.
path - The string repository-relative path.
Returns the string contents of the index version of the path.
Repository.getLineDiffs(path, text, [options])
Get the line diffs comparing the HEAD version of the given path and the given text.
path - The string repository-relative path.
text - The string text to diff the HEAD contents of the path against.
options - An optional object with the following keys:
ignoreSpaceAtEOL-trueto ignore changes in whitespace at the end of lines. (ignoreEolWhitespace also works.)ignoreSpaceChange-trueto ignore changes in amount of whitespace. This ignores whitespace at line end, and considers all other sequences of one or more whitespace characters to be equivalent.ignoreAllSpace-trueto ignore whitespace when comparing lines. This ignores differences even if one line has whitespace where the other line has none.useIndex-trueto compare against the index version instead of the HEAD version.
Returns an array of objects that have oldStart, oldLines, newStart, and
newLines keys pointing to integer values, may be null if the diff fails.
Repository.getLineDiffDetails(path, text, [options])
Get the line diff details comparing the HEAD version of the given path and the given text.
Takes the same arguments as getLineDiffs.
Returns an array of objects which represent an old or new line in a diff. Every
object has oldStart, oldLines, newStart, newLines, oldLineNumber and
newLineNumber keys pointing to integer values, and a line key pointing to the
respective line content. May be null if the diff fails.
Repository.getMergeBase(commit1, commit2)
Get the merge base of two commits.
commit1 - The string SHA-1 of the first commit.
commit2 - The string SHA-1 of the second commit.
Returns the string SHA-1 of the merge base of commit1 and commit2 or null
if there isn't one.
Repository.getPath()
Get the path of the repository.
Returns the string absolute path of the opened repository.
Repository.getReferences()
Gets all the local and remote references.
Returns an object with three keys: heads, remotes, and tags.
Each key can be an array of strings containing the reference names.
Repository.getReferenceTarget(ref)
Get the target of the given reference.
ref - The string reference.
Returns the string target of the given reference.
Repository.getShortHead()
Get a possibly shortened version of value returns by getHead(). This will
remove leading segments of refs/heads, refs/tags, or refs/remotes and will
also shorten the SHA-1 of a detached HEAD to 7 characters.
Returns a string shortened reference name or SHA-1.
Repository.getStatus([path])
Get the status of a single path or all paths in the repository. This will not include ignored paths.
path - An optional repository-relative path to limit the status reporting to.
Returns an integer status number if a path is specified and returns an object with path keys and integer status values if no path is specified.
Repository.getUpstreamBranch([branch])
Get the upstream branch of the given branch.
branch - The branch to find the upstream branch of (default: HEAD)
Returns the string upstream branch reference name.
Repository.getWorkingDirectory()
Get the working directory of the repository.
Returns the string absolute path to the repository's working directory.
Repository.isIgnored(path)
Get the ignored status of a given path.
path - The string repository-relative path.
Returns true if the path is ignored, false otherwise.
Repository.isPathModified(path)
Get the modified status of a given path.
path - The string repository-relative path.
Returns true if the path is modified, false otherwise.
Repository.isPathNew(path)
Get the new status of a given path.
path - The string repository-relative path.
Returns true if the path is new, false otherwise.
Repository.isPathDeleted(path)
Get the deleted status of a given path.
path - The string repository-relative path.
Returns true if the path is deleted, false otherwise.
Repository.isPathStaged(path)
Get the staged status of a given path.
path - The string repository-relative path.
Returns true if the path is staged in the index, false otherwise.
Repository.isStatusIgnored(status)
Check if a status value represents an ignored path.
status - The integer status value.
Returns true if the status is a ignored one, false otherwise.
Repository.isStatusModified(status)
Check if a status value represents a modified path.
status - The integer status value.
Returns true if the status is a modified one, false otherwise.
Repository.isStatusNew(status)
Check if a status value represents a new path.
status - The integer status value.
Returns true if the status is a new one, false otherwise.
Repository.isStatusDeleted(status)
Check if a status value represents a deleted path.
status - The integer status value.
Returns true if the status is a deleted one, false otherwise.
Repository.isStatusStaged(status)
Check if a status value represents a changed that is staged in the index.
status - The integer status value.
Returns true if the status is a staged one, false otherwise.
Repository.isSubmodule(path)
Check if the path is a submodule in the index.
path - The string repository-relative path.
Returns true if the path is a submodule, false otherwise.
Repository.refreshIndex()
Reread the index to update any values that have changed since the last time the index was read.
Repository.relativize(path)
Relativize the given path to the repository's working directory.
path - The string path to relativize.
Returns a repository-relative path if the given path is prefixed with the repository's working directory path.
Repository.isWorkingDirectory(path)
Is the given path the repository's working directory?
It is better to call this method than comparing a path directly against
the value of getWorkingDirectory() since this method handles slash
normalization on Windows, case insensitive filesystems, and symlinked
repositories.
path - The string path to check.
Returns true if the given path is the repository's working directory,
false otherwise.
Repository.release()
Release the repository and close all file handles it has open. No other methods
can be called on the Repository object once it has been released.
Repository.submoduleForPath(path)
Get the repository for the submodule that the path is located in.
path - The absolute or repository-relative string path.
Returns a Repository or null if the path isn't in a submodule.
Repository.add(path)
Stage the changes in path into the repository's index. Clear any conflict state
associated with path.
path - A repository-relative string path.
Raises an Error if the path isn't readable or if another exception occurs.