• Packages
  • Themes
  • Documentation
  • Blog
  • Discuss
Sign in
Whoops, there was an error
v1.34.0
v1.33.1
v1.33.0
v1.32.2
v1.32.1
v1.32.0
v1.31.2
v1.31.1
v1.31.0
v1.30.0
v1.29.0
v1.28.2
v1.28.1
v1.28.0
untagged-688de6479cca05b51c00
untagged-2abd5a23b4430027c837
v1.27.2
v1.27.1
v1.27.0
v1.26.1
v1.26.0
v1.25.1
v1.25.0
v1.24.1
v1.24.0
v1.23.3
v1.23.2
v1.23.1
v1.23.0
v1.22.1
v1.22.0
v1.21.2
v1.21.1
v1.21.0
v1.20.1
v1.20.0
v1.19.7
v1.19.6
v1.19.5
v1.19.4
v1.19.3
v1.19.2
v1.19.1
v1.19.0
v1.18.0
v1.17.2
v1.17.1
v1.17.0
v1.16.0
v1.15.0
v1.14.4
v1.14.3
v1.14.2
v1.14.1
v1.14.0
v1.13.1
v1.13.0
v1.12.9
v1.12.8
v1.12.7
v1.12.6
v1.12.5
v1.12.4
v1.12.3
v1.12.2
v1.12.1
v1.12.0
v1.11.2
v1.11.1
v1.11.0
v1.10.2
v1.10.1
v1.10.0
v1.9.9
v1.9.8
v1.9.7
v1.9.6
v1.9.5
v1.9.4
v1.9.3
v1.9.2
v1.9.1
v1.9.0
v1.8.0
v1.7.4
v1.7.3
v1.7.2
v1.7.1
v1.7.0
v1.6.2
v1.6.1
v1.6.0
v1.5.4
v1.5.3
v1.5.2
v1.5.1
v1.5.0
v1.4.3
v1.4.2
v1.4.1
v1.4.0
v1.3.3
v1.3.2
v1.3.1
v1.3.0
v1.2.4
v1.2.3
v1.2.2
v1.2.1
v1.2.0
v1.1.0
v1.0.19
v1.0.18
v1.0.17
v1.0.16
v1.0.15
v1.0.14
v1.0.13
v1.0.12
v1.0.11
v1.0.10
v1.0.9
v1.0.8
v1.0.7
v1.0.6
v1.0.5
v1.0.4
v1.0.3
v1.0.2
v1.0.1
v1.0.0
v0.211.0
v0.210.0
v0.209.0
v0.208.0
v0.207.0
v0.206.0
v0.205.0
v0.204.0
v0.203.0
v0.202.0
v0.201.0
v0.200.0
v0.199.0
v0.198.0
v0.197.0
v0.196.0
v0.195.0
v0.194.0
v0.193.0
v0.192.0
v0.191.0
v0.190.0
v0.189.0
v0.188.0
v0.187.0
Loading…

Essential Classes

  • AtomEnvironment
  • Color
  • CommandRegistry
  • CompositeDisposable
  • Config
  • Decoration
  • DisplayMarker
  • DisplayMarkerLayer
  • Disposable
  • Emitter
  • LayerDecoration
  • MarkerLayer
  • Notification
  • NotificationManager
  • Point
  • Range
  • TextEditor
  • TooltipManager
  • ViewRegistry
  • Workspace

Extended Classes

  • BufferedNodeProcess
  • BufferedProcess
  • Clipboard
  • ContextMenuManager
  • Cursor
  • DeserializerManager
  • Directory
  • Dock
  • File
  • GitRepository
  • Grammar
  • GrammarRegistry
  • Gutter
  • HistoryManager
  • KeymapManager
  • MenuManager
  • Package
  • PackageManager
  • Pane
  • Panel
  • Project
  • ScopeDescriptor
  • Selection
  • StyleManager
  • Task
  • TextBuffer
  • ThemeManager

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 = 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'

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(event)

Function

event

Object

.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 .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 {::getPathStatus(path)} 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 ::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.

::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.

  • Terms of Use
  • Privacy
  • Code of Conduct
  • Releases
  • FAQ
  • Contact
with by