@pulsar-edit/git-utils

# Git Node module [![CI](https://github.com/atom/git-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/atom/git-utils/actions/workflows/ci.yml) Helpers for working with Git repositories built natively on top of [libgit2](http://libgit2.github.com). ## Installing ```sh npm install git-utils ``` ## Development * Clone the repository * Run `npm run prepare` to get the submodule * Run `npm install` * Run `npm test` to 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 ```coffeescript 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` - `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. ### 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.