Helpers for working with Git repositories built natively on top of libgit2.
npm install git-utils
- Clone the repository
- Run
npm run prepare
to get the submodule - Run
npm install
- Run
npm test
to run the specs
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.
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.
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.
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.
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.
Get the config value of the given key.
key
- The string key to retrieve the value for.
Returns the configuration value, may be null
.
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.
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.
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.
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.
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.
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
-true
to ignore changes in whitespace at the end of lines. (ignoreEolWhitespace also works.)ignoreSpaceChange
-true
to 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
-true
to ignore whitespace when comparing lines. This ignores differences even if one line has whitespace where the other line has none.useIndex
-true
to 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.
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.
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.
Get the path of the repository.
Returns the string absolute path of the opened repository.
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.
Get the target of the given reference.
ref
- The string reference.
Returns the string target of the given reference.
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.
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.
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.
Get the working directory of the repository.
Returns the string absolute path to the repository's working directory.
Get the ignored status of a given path.
path
- The string repository-relative path.
Returns true
if the path is ignored, false
otherwise.
Get the modified status of a given path.
path
- The string repository-relative path.
Returns true
if the path is modified, false
otherwise.
Get the new status of a given path.
path
- The string repository-relative path.
Returns true
if the path is new, false
otherwise.
Get the deleted status of a given path.
path
- The string repository-relative path.
Returns true
if the path is deleted, false
otherwise.
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.
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.
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.
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.
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.
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.
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.
Reread the index to update any values that have changed since the last time the index was read.
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.
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.
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.
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.
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.