• Packages
  • Themes
  • Documentation
  • Blog
  • Discuss
Sign in
Whoops, there was an error
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
  • WorkspaceCenter

Extended Classes

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

Project extended

Represents a project that's opened in Atom.

An instance of this class is always available as the atom.project global.

Event Subscription

::onDidChangePaths(callback)

Invoke the given callback when the project paths change.

Argument Description
callback(projectPaths)

Function to be called after the project paths change.

projectPaths

An Array of String project paths.

Return values

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

::onDidAddBuffer(callback)

Invoke the given callback when a text buffer is added to the project.

Argument Description
callback(buffer)

Function to be called when a text buffer is added.

buffer

A TextBuffer item.

Return values

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

::observeBuffers(callback)

Invoke the given callback with all current and future text buffers in the project.

Argument Description
callback(buffer)

Function to be called with current and future text buffers.

buffer

A TextBuffer item.

Return values

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

::onDidChangeFiles(callback)

Invoke a callback when a filesystem change occurs within any open project path.

const disposable = atom.project.onDidChangeFiles(events => {
  for (const event of events) {
    // "created", "modified", "deleted", or "renamed" 
    console.log(`Event action: ${event.type}`)
 
    // absolute path to the filesystem entry that was touched 
    console.log(`Event path: ${event.path}`)
 
    if (event.type === 'renamed') {
      console.log(`.. renamed from: ${event.oldPath}`)
    }
  }
}
 
disposable.dispose()

To watch paths outside of open projects, use the watchPaths function instead; see PathWatcher.

When writing tests against functionality that uses this method, be sure to wait for the Promise returned by {getWatcherPromise()} before manipulating the filesystem to ensure that the watcher is receiving events.

Argument Description
callback(events)

Function to be called with batches of filesystem events reported by the operating system.

events

An Array of objects that describe a batch of filesystem events.

action

String describing the filesystem action that occurred. One of "created", "modified", "deleted", or "renamed".

path

String containing the absolute path to the filesystem entry that was acted upon.

oldPath

For rename events, String containing the filesystem entry's former absolute path.

Return values

Returns a Disposable to manage this event subscription.

Accessing the git repository

::getRepositories()

Get an Array of GitRepositorys associated with the project's directories.

This method will be removed in 2.0 because it does synchronous I/O. Prefer the following, which evaluates to a Promise that resolves to an Array of Repository objects:

Promise.all(atom.project.getDirectories().map(
    atom.project.repositoryForDirectory.bind(atom.project)))

::repositoryForDirectory(directory)

Get the repository for a given directory asynchronously.

Argument Description
directory

Directory for which to get a Repository.

Return values

Returns a Promise that resolves with either:

  • Repository if a repository can be created for the given directory
  • null if no repository can be created for the given directory.

Managing Paths

::getPaths()

Get an Array of Strings containing the paths of the project's directories.

::setPaths(projectPaths)

Set the paths of the project's directories.

Argument Description
projectPaths

Array of String paths.

::addPath(projectPath)

Add a path to the project's list of root paths

Argument Description
projectPath

String The path to the directory to add.

::getWatcherPromise(projectPath)

Access a Promise that resolves when the filesystem watcher associated with a project root directory is ready to begin receiving events.

This is especially useful in test cases, where it's important to know that the watcher is ready before manipulating the filesystem to produce events.

Argument Description
projectPath

String One of the project's root directories.

Return values

Returns a Promise that resolves with the PathWatcher associated with this project root once it has initialized and is ready to start sending events. The Promise will reject with an error instead if projectPath is not currently a root directory.

::removePath(projectPath)

remove a path from the project's list of root paths.

Argument Description
projectPath

String The path to remove.

::getDirectories()

Get an Array of Directorys associated with this project.

::relativizePath(fullPath)

Get the path to the project directory that contains the given path, and the relative path from that project directory to the given path.

Argument Description
fullPath

String An absolute path.

Return values

Returns an Array with two elements:

  • projectPath The String path to the project directory that contains the given path, or null if none is found.
  • relativePath String The relative path from the project directory to the given path.

::contains(pathToCheck)

Determines whether the given path (real or symbolic) is inside the project's directory.

This method does not actually check if the path exists, it just checks their locations relative to each other.

Basic operation

# Project's root directory is /foo/bar 
project.contains('/foo/bar/baz')        # => true 
project.contains('/usr/lib/baz')        # => false 

Existence of the path is not required

# Project's root directory is /foo/bar 
fs.existsSync('/foo/bar/baz')           # => false 
project.contains('/foo/bar/baz')        # => true 
Argument Description
pathToCheck

String path

Return values

Returns whether the path is inside the project's root directory.

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