GitRepository extended
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 = atomprojectgetRepositories0repogetShortHead # 'master'repogetShortHead'vendor/path/to/a/submodule' # 'dead1234'
Examples
Logging the URL of the origin remote
git = atomprojectgetRepositories0consolelog gitgetOriginURL
Requiring in packages
require 'atom'
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, |
| Return values |
|---|
Returns a GitRepository instance or |
::destroy()
Destroy this GitRepository object.
This destroys any tasks and subscriptions and releases the underlying libgit2 repository handle. This method is idempotent.
::onDidDestroy(callback)
Invoke the given callback when this GitRepository's destroy() method is invoked.
| Argument | Description |
|---|---|
callback() |
| Return values |
|---|
Returns a Disposable on which |
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(event) |
|
event |
|
.path |
String the old parameters the decoration used to have |
.pathStatus |
Number representing the status. This value can be passed to ::isStatusModified or ::isStatusNew to get more information. |
| Return values |
|---|
Returns a Disposable on which |
::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 {::getPathStatus(path)} to get the status for your path of choice.
| Argument | Description |
|---|---|
callback() |
| Return values |
|---|
Returns a Disposable on which |
Repository Details
::getType()
A String indicating the type of version control system used by this repository.
| Return values |
|---|
Returns |
::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. |
::getCachedUpstreamAheadBehindCount(path)
::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 |
::getReferences(path)
Reading Status
::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 ::isStatusModified or ::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 ::isStatusModified or ::isStatusNew to get more information. |
Retrieving Diffs
::getDiffStats(path)
::getLineDiffs(path, text)
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. |