GitRepository

Description

Represents the underlying git operations performed by Atom.

This class shouldn't be instantiated directly but instead by accessing the atom.project global and calling getRepositories(). Note that this will only be available when the project is backed by a Git repository.

This class handles submodules automatically by taking a path argument to many of the methods. This path argument will determine which underlying repository is used.

For a repository with submodules this would have the following outcome:

repo = atom.project.getRepositories()[0]
repo.getShortHead() # 'master'
repo.getShortHead('vendor/path/to/a/submodule') # 'dead1234'

Examples

Logging the URL of the origin remote

git = atom.project.getRepositories()[0]
console.log git.getOriginURL()

Requiring in packages

{GitRepository} = require 'atom'

API documentation

Construction and Destruction

.open(path, options)

Creates a new GitRepository instance.

Argument	Description
`path`	The String path to the Git repository to open.
`options`	An optional Object with the following keys:
`refreshOnWindowFocus`	A Boolean, `true` to refresh the index and statuses when the window is focused.

Return values

Returns a GitRepository instance or null if the repository could not be opened.

::destroy()

Destroy this GitRepository object.

This destroys any tasks and subscriptions and releases the underlying libgit2 repository handle. This method is idempotent.

::isDestroyed()

Return values

Returns a Boolean indicating if this repository has been destroyed.

::onDidDestroy(callback)

Invoke the given callback when this GitRepository's destroy() method is invoked.

Argument	Description
`callback`	Function

Return values

Returns a Disposable on which .dispose() can be called to unsubscribe.

Event Subscription

::onDidChangeStatus(callback)

Invoke the given callback when a specific file's status has changed. When a file is updated, reloaded, etc, and the status changes, this will be fired.

Argument	Description
`callback`	Function
`event`	Object
`path`	String the old parameters the decoration used to have
`pathStatus`	Number representing the status. This value can be passed to GitRepository::isStatusModified or GitRepository::isStatusNew to get more information.

Return values

Returns a Disposable on which .dispose() can be called to unsubscribe.

::onDidChangeStatuses(callback)

Invoke the given callback when a multiple files' statuses have changed. For example, on window focus, the status of all the paths in the repo is checked. If any of them have changed, this will be fired. Call GitRepository::getPathStatus to get the status for your path of choice.

Argument	Description
`callback`	Function

Return values

Returns a Disposable on which .dispose() can be called to unsubscribe.

Repository Details

::getType()

A String indicating the type of version control system used by this repository.

Return values

Returns "git".

::getPath()

Return values

Returns the String path of the repository.

::getWorkingDirectory()

Return values

Returns the String working directory path of the repository.

::isProjectAtRoot()

Return values

Returns true if at the root, false if in a subfolder of the repository.

::relativize()

Makes a path relative to the repository's working directory.

::hasBranch()

Return values

Returns true if the given branch exists.

::getShortHead(path)

Retrieves a shortened version of the HEAD reference value.

This removes the leading segments of refs/heads, refs/tags, or refs/remotes. It also shortens the SHA-1 of a detached HEAD to 7 characters.

Argument	Description
`path`	An optional String path in the repository to get this information for, only needed if the repository contains submodules.

Return values

Returns a String.

::isSubmodule(path)

Is the given path a submodule in the repository?

Argument	Description
`path`	The String path to check.

Return values

Returns a Boolean.

::getAheadBehindCount(reference, path)

Argument	Description
`reference`	The String branch reference name.
`path`	The String path in the repository to get this information for, only needed if the repository contains submodules.

Return values

Returns the number of commits behind the current branch is from the its upstream remote branch.

::getCachedUpstreamAheadBehindCount(path)

Get the cached ahead/behind commit counts for the current branch's upstream branch.

Argument	Description
`path`	An optional String path in the repository to get this information for, only needed if the repository has submodules.

Return values

Returns an Object with the following keys:
- ahead The Number of commits ahead.
- behind The Number of commits behind.

::getConfigValue(key, path)

Argument	Description
`key`	The String key for the configuration to lookup.
`path`	An optional String path in the repository to get this information for, only needed if the repository has submodules.

Return values

Returns the git configuration value specified by the key.

::getOriginURL(path)

Argument	Description
`path`	optional String path in the repository to get this information for, only needed if the repository has submodules.

Return values

Returns the origin url of the repository.

::getUpstreamBranch(path)

Argument	Description
`path`	An optional String path in the repo to get this information for, only needed if the repository contains submodules.

Return values

Returns the upstream branch for the current HEAD, or null if there is no upstream branch for the current HEAD.
Returns a String branch name such as refs/remotes/origin/master.

::getReferences(path)

Gets all the local and remote references.

Argument	Description
`path`	An optional String path in the repository to get this information for, only needed if the repository has submodules.

Return values

Returns an Object with the following keys:
- heads An Array of head reference names.
- remotes An Array of remote reference names.
- tags An Array of tag reference names.

::getReferenceTarget(reference, path)

Argument	Description
`reference`	The String reference to get the target of.
`path`	An optional String path in the repo to get the reference target for. Only needed if the repository contains submodules.

Return values

Returns the current String SHA for the given reference.

Reading Status

::isPathModified(path)

Argument	Description
`path`	The String path to check.

Return values

Returns true if the given path is modified.
Returns a Boolean that's true if the path is modified.

::isPathNew(path)

Argument	Description
`path`	The String path to check.

Return values

Returns true if the given path is new.
Returns a Boolean that's true if the path is new.

::isPathIgnored(path)

Is the given path ignored?

Argument	Description
`path`	The String path to check.

Return values

Returns a Boolean that's true if the path is ignored.

::getDirectoryStatus(path)

Get the status of a directory in the repository's working directory.

Argument	Description
`path`	The String path to check.

Return values

Returns a Number representing the status. This value can be passed to GitRepository::isStatusModified or GitRepository::isStatusNew to get more information.

::getPathStatus(path)

Get the status of a single path in the repository.

Argument	Description
`path`	A String repository-relative path.

Return values

Returns a Number representing the status. This value can be passed to GitRepository::isStatusModified or GitRepository::isStatusNew to get more information.

::getCachedPathStatus(path)

Get the cached status for the given path.

Argument	Description
`path`	A String path in the repository, relative or absolute.

Return values

Returns a status Number or null if the path is not in the cache.

::isStatusModified(status)

Argument	Description
`status`	A Number representing the status.

Return values

Returns true if the given status indicates modification.
Returns a Boolean that's true if the status indicates modification.

::isStatusNew(status)

Argument	Description
`status`	A Number representing the status.

Return values

Returns true if the given status indicates a new path.
Returns a Boolean that's true if the status indicates a new path.

Retrieving Diffs

::getDiffStats(path)

Retrieves the number of lines added and removed to a path.

This compares the working directory contents of the path to the HEAD version.

Argument	Description
`path`	The String path to check.

Return values

Returns an Object with the following keys:
- added The Number of added lines.
- deleted The Number of deleted lines.

::getLineDiffs(path, text)

Retrieves the line diffs comparing the HEAD version of the given path and the given text.

Argument	Description
`path`	The String path relative to the repository.
`text`	The String to compare against the `HEAD` contents

Return values

Returns an Array of hunk Objects with the following keys:
- oldStart The line Number of the old hunk.
- newStart The line Number of the new hunk.
- oldLines The Number of lines in the old hunk.
- newLines The Number of lines in the new hunk

Checking Out

::checkoutHead(path)

Restore the contents of a path in the working directory and index to the version at HEAD.

This is essentially the same as running:

  git reset HEAD -- <path>
  git checkout HEAD -- <path>

Argument	Description
`path`	The String path to checkout.

Return values

Returns a Boolean that's true if the method was successful.

::checkoutReference(reference, create)

Checks out a branch in your repository.

Argument	Description
`reference`	The String reference to checkout.
`create`	A Boolean value which, if true creates the new reference if it doesn't exist.

Return values

Returns a Boolean that's true if the method was successful.