Chapter 2 : Using Atom

STOP

This is being kept for archival purposes only from the original Atom documentation. As this may no longer be relevant to Pulsar, you use this at your own risk. Current Pulsar documentation for this section is found at the documentation home.

Using Atom

Now that we've covered the very basics of Atom, we are ready to see how to really start getting the most out of using it. In this chapter we'll look at how to find and install new packages in order to add new functionality, how to find and install new themes, how to work with and manipulate text in a more advanced way, how to customize the editor in any way you wish, how to work with Git for version control and more.

At the end of this chapter, you should have a customized environment that you're comfortable in and you should be able to change, create and move through your text like a master.

Atom Packages

First we'll start with the Atom package system. As we mentioned previously, Atom itself is a very basic core of functionality that ships with a number of useful packages that add new features like the Tree View and the Settings View.

In fact, there are more than 80 packages that comprise all of the functionality that is available in Atom by default. For example, the Welcome screen that you see when you first start Atom, the spell checker, the themes and the Fuzzy Finder are all packages that are separately maintained and all use the same APIs that you have access to, as we'll see in great detail in Hacking Atom.

This means that packages can be incredibly powerful and can change everything from the very look and feel of the entire interface to the basic operation of even core functionality.

In order to install a new package, you can use the Install tab in the now familiar Settings View. Open up the Settings View using Cmd+,Ctrl+,, click on the "Install" tab and type your search query into the box under Install Packages.

The packages listed here have been published to https://atom.io/packages which is the official registry for Atom packages. Searching on the Settings View will go to the Atom package registry and pull in anything that matches your search terms.

All of the packages will come up with an "Install" button. Clicking that will download the package and install it. Your editor will now have the functionality that the package provides.

Package Settings

Once a package is installed in Atom, it will show up in the Settings View under the "Packages" tab, along with all the preinstalled packages that come with Atom. To filter the list in order to find one, you can type into search box directly under the "Installed Packages" heading.

Clicking on the "Settings" button for a package will give you the settings screen for that package specifically. Here you have the option of changing some of the default variables for the package, seeing what all the command keybindings are, disabling the package temporarily, looking at the source code, seeing the current version of the package, reporting issues and uninstalling the package.

If a new version of any of your packages is released, Atom will automatically detect it and you can upgrade the package from either this screen or from the "Updates" tab. This helps you easily keep all your installed packages up to date.

Atom Themes

You can also find and install new themes for Atom from the Settings View. These can be either UI themes or syntax themes and you can search for them from the "Install" tab, just like searching for new packages. Make sure to press the "Themes" toggle next to the search box.

Clicking on the theme title will take you to a profile page for the theme on atom.io, which often has a screenshot of the theme. This way you can see what it looks like before installing it.

Clicking on "Install" will install the theme and make it available in the Theme dropdowns as we saw in Changing the Theme.

Command Line

You can also install packages or themes from the command line using apm.

Tip

Check that you have apm installed by running the following command in your terminal:

$ apm help install

You should see a message print out with details about the apm install command.

If you do not, see the Installing Atom section for instructions on how to install the atom and apm commands for your system.

You can also install packages by using the apm install command:

• apm install <package_name> to install the latest version.
• apm install <package_name>@<package_version> to install a specific version.

For example apm install emmet@0.1.5 installs the 0.1.5 release of the Emmet package.

You can also use apm to find new packages to install. If you run apm search, you can search the package registry for a search term.

$ apm search coffee
> Search Results For 'coffee' (29)
> ├── build-coffee Atom Build provider for coffee, compiles CoffeeScript (1160 downloads, 2 stars)
> ├── scallahan-coffee-syntax A coffee inspired theme from the guys over at S.CALLAHAN (183 downloads, 0 stars)
> ├── coffee-paste Copy/Paste As : Js ➤ Coffee / Coffee ➤ Js (902 downloads, 4 stars)
> ├── atom-coffee-repl Coffee REPL for Atom Editor (894 downloads, 2 stars)
> ├── coffee-navigator Code navigation panel for Coffee Script (3493 downloads, 22 stars)
> ...
> ├── language-iced-coffeescript Iced coffeescript for atom (202 downloads, 1 star)
> └── slontech-syntax Dark theme for web developers ( HTML, CSS/LESS, PHP, MYSQL, javascript, AJAX, coffee, JSON ) (2018 downloads, 3 stars)

You can use apm view to see more information about a specific package.

$ apm view build-coffee
> build-coffee
> ├── 0.6.4
> ├── https://github.com/idleberg/atom-build-coffee
> ├── Atom Build provider for coffee, compiles CoffeeScript
> ├── 1152 downloads
> └── 2 stars
>
> Run `apm install build-coffee` to install this package.

Moving in Atom

While it's pretty easy to move around Atom by clicking with the mouse or using the arrow keys, there are some keybindings that may help you keep your hands on the keyboard and navigate around a little faster.

• Alt+Left or Alt+BCtrl+Left - Move to the beginning of word
• Alt+Right or Alt+FCtrl+Right - Move to the end of word
• Cmd+Left or Ctrl+AHome - Move to the first character of the current line
• Cmd+Right or Ctrl+EEnd - Move to the end of the line
• Cmd+UpCtrl+Home - Move to the top of the file
• Cmd+DownCtrl+End - Move to the bottom of the file

You can also move directly to a specific line (and column) number with Ctrl+G. This will bring up a dialog that asks which line you would like to jump to. You can also use the row:column syntax to jump to a character in that line as well.

Additional Movement and Selection Commands

Atom also has a few movement and selection commands that don't have keybindings by default. You can access these commands from the Command Palette, but if you find yourself using commands that don't have a keybinding often, have no fear! You can easily add an entry to your keymap.cson to create a key combination. You can open keymap.cson file in an editor from the Atom > KeymapFile > KeymapEdit > Keymap menu.

For example, the command editor:move-to-beginning-of-screen-line is available in the command palette, but it's not bound to any key combination. To create a key combination you need to add an entry in your keymap.cson file. For editor:select-to-previous-word-boundary, you can add the following to your keymap.cson:

This will bind the command editor:select-to-previous-word-boundary to Cmd+Shift+ECtrl+Shift+E. For more information on customizing your keybindings, see Customizing Keybindings.

Here's a list of Movement and Selection Commands that do not have a keyboard shortcut by default:

Navigating by Symbols

You can also jump around a little more informatively with the Symbols View. To jump to a symbol such as a method definition, press Cmd+RCtrl+R. This opens a list of all symbols in the current file, which you can fuzzy filter similarly to Cmd+TCtrl+T. You can also search for symbols across your project but it requires a tags file.

You can generate a tags file by using the ctags utility. Once it is installed, you can use it to generate a tags file by running a command to generate it. See the ctags documentation for details.

You can customize how tags are generated by creating your own .ctags file in your home directory, ~/.ctags%USERPROFILE%\.ctags. An example can be found here.

The symbols navigation functionality is implemented in the symbols-view package.

Bookmarks

Atom also has a great way to bookmark specific lines in your project so you can jump back to them quickly.

If you press Cmd+F2Alt+Ctrl+F2Ctrl+Shift+F2, Atom will toggle a "bookmark" on the current line. You can set these throughout your project and use them to quickly find and jump to important lines of your project. A small bookmark symbol is added to the line gutter, like on line 22 of the image below.

If you hit F2, Atom will jump to the next bookmark in the file you currently have focused. If you use Shift+F2 it will cycle backwards through them instead.

You can also see a list of all your project's current bookmarks and quickly filter them and jump to any of them by hitting Ctrl+F2.


The bookmarks functionality is implemented in the bookmarks package.

Atom Selections

Text selections in Atom support a number of actions, such as scoping deletion, indentation and search actions, and marking text for actions such as quoting and bracketing.

Selections mirror many of the movement commands. They're actually exactly the same keybindings as the movement commands, but with a Shift key added in.

• Shift+Up or Ctrl+Shift+P - Select up
• Shift+Down or Ctrl+Shift+N - Select down
• Shift+Left or Ctrl+Shift+B - Select previous character
• Shift+Right or Ctrl+Shift+F - Select next character
• Alt+Shift+LeftCtrl+Shift+Left or Alt+Shift+B - Select to beginning of word
• Alt+Shift+RightCtrl+Shift+Right or Alt+Shift+F - Select to end of word
• Cmd+Shift+RightShift+End or Ctrl+Shift+E - Select to end of line
• Cmd+Shift+LeftShift+Home or Ctrl+Shift+A - Select to first character of line
• Cmd+Shift+UpCtrl+Shift+Home - Select to top of file
• Cmd+Shift+DownCtrl+Shift+End - Select to bottom of file

In addition to the cursor movement selection commands, there are also a few commands that help with selecting specific areas of content.

• Cmd+ACtrl+A - Select the entire contents of the file
• Cmd+LCtrl+L - Select the entire line

Editing and Deleting Text

So far we've looked at a number of ways to move around and select regions of a file, so now let's actually change some of that text. Obviously you can type in order to insert characters, but there are also a number of ways to delete and manipulate text that could come in handy.

Basic Manipulation

There are a handful of cool keybindings for basic text manipulation that might come in handy. These range from moving around lines of text and duplicating lines to changing the case.

• Cmd+JCtrl+J - Join the next line to the end of the current line
• Cmd+Ctrl+Up/DownCtrl+Up/Down - Move the current line up or down
• Cmd+Shift+DCtrl+Shift+D - Duplicate the current line
• Cmd+K Cmd+UCtrl+K Ctrl+U - Upper case the current word
• Cmd+K Cmd+LCtrl+K Ctrl+L - Lower case the current word

Atom also has built in functionality to re-flow a paragraph to hard-wrap at a given maximum line length. You can format the current selection to have lines no longer than 80 (or whatever number editor.preferredLineLength is set to) characters using Alt+Cmd+QAlt+Ctrl+Q. If nothing is selected, the current paragraph will be reflowed.

Deleting and Cutting

You can also delete or cut text out of your buffer with some shortcuts. Be ruthless.

• Ctrl+Shift+K - Delete current line
• Alt+Backspace or Alt+HCtrl+Backspace - Delete to beginning of word
• Alt+Delete or Alt+DCtrl+Delete - Delete to end of word

Multiple Cursors and Selections

One of the cool things that Atom can do out of the box is support multiple cursors. This can be incredibly helpful in manipulating long lists of text.

• Cmd+ClickCtrl+Click - Add a new cursor at the clicked location
• Ctrl+Shift+Up/DownAlt+Ctrl+Up/DownAlt+Shift+Up/Down - Add another cursor above/below the current cursor
• Cmd+DCtrl+D - Select the next word in the document that is the same as the currently selected word
• Cmd+Ctrl+GAlt+F3 - Select all words in the document that are the same as the currently selected word

Using these commands you can place cursors in multiple places in your document and effectively execute the same commands in multiple places at once.

This can be incredibly helpful in doing many type of repetitive tasks such as renaming variables or changing the format of some text. You can use this with almost any plugin or command - for example, changing case and moving or duplicating lines.

You can also use the mouse to select text with the CmdCtrl key pressed down to select multiple regions of your text simultaneously.

Whitespace

Atom comes with several commands to help you manage the whitespace in your document. One very useful pair of commands converts leading spaces into tabs and converts leading tabs into spaces. If you're working with a document that has mixed whitespace, these commands are great for helping to normalize the file. There are no keybindings for the whitespace commands, so you will have to search your command palette for "Convert Spaces to Tabs" (or vice versa) to run one of these commands.

The whitespace commands are implemented in the atom/whitespace package. The settings for the whitespace commands are managed on the page for the whitespace package.

Note

The "Remove Trailing Whitespace" option is on by default. This means that every time you save any file opened in Atom, it will strip all trailing whitespace from the file. If you want to disable this, go to the whitespace package in your settings panel and uncheck that option.

Atom will also by default ensure that your file has a trailing newline. You can also disable this option on that screen.

Brackets

Atom ships with intelligent and easy to use bracket handling.

It will by default highlight [], (), and {} style brackets when your cursor is over them. It will also highlight matching XML and HTML tags.

Atom will also automatically autocomplete [], (), and {}, "", '', “”, ‘’, «», ‹›, and backticks when you type the leading one. If you have a selection and you type any of these opening brackets or quotes, Atom will enclose the selection with the opening and closing brackets or quotes.

There are a few other interesting bracket related commands that you can use.

• Ctrl+M - Jump to the bracket matching the one adjacent to the cursor. It jumps to the nearest enclosing bracket when there's no adjacent bracket.
• Cmd+Ctrl+MAlt+Ctrl+, - Select all the text inside the current brackets
• Alt+Cmd+.Alt+Ctrl+. - Close the current XML/HTML tag

The brackets functionality is implemented in the bracket-matcher package. Like all of these packages, to change defaults related to bracket handling, or to disable it entirely, you can navigate to this package in the Settings view.

Encoding

Atom also ships with some basic file encoding support should you find yourself working with non-UTF-8 encoded files, or should you wish to create one.

• Ctrl+Shift+UAlt+U - Toggle menu to change file encoding

If you pull up the file encoding dialog, you can choose an alternate file encoding to save your file in.

When you open a file, Atom will try to auto-detect the encoding. If Atom can't identify the encoding, the encoding will default to UTF-8, which is also the default encoding for new files.

If you pull up the encoding menu and change the active encoding to something else, the file will be written out in that encoding the next time you save the file.

The encoding selector is implemented in the encoding-selector package.

Find and Replace

Finding and replacing text in your file or project is quick and easy in Atom.

• Cmd+FCtrl+F - Search within a buffer
• Cmd+Shift+FCtrl+Shift+F - Search the entire project

If you launch either of those commands, you'll be greeted with the Find and Replace panel at the bottom of your screen.

To search within your current file you can press Cmd+FCtrl+F, type in a search string and press Enter (or Cmd+GF3 or the "Find Next" button) multiple times to cycle through all the matches in that file. Alt+Enter will find all occurences of the search string. The Find and Replace panel also contains buttons for toggling case sensitivity, performing regular expression matching, scoping the search to selections, and performing whole word search.

If you type a string in the replacement text box, you can replace matches with a different string. For example, if you wanted to replace every instance of the string "Scott" with the string "Dragon", you would enter those values in the two text boxes and press the "Replace All" button to perform the replacements.

Note

Note: Atom uses JavaScript regular expressions to perform regular expression searches.

When doing a regular expression search, the replacement syntax to refer back to search groups is $1, $2, … $&. Refer to JavaScript's guide to regular expressions to learn more about regular expression syntax you can use in Atom.

You can also find and replace throughout your entire project if you invoke the panel with Cmd+Shift+FCtrl+Shift+F.

This is a great way to find out where in your project a function is called, an anchor is linked to or a specific misspelling is located. Click on the matching line to jump to that location in that file.

You can limit a search to a subset of the files in your project by entering a glob pattern into the "File/Directory pattern" text box. For example, the pattern src/*.js would restrict the search to JavaScript files in the src directory. The "globstar" pattern (**) can be used to match arbitrarily many subdirectories. For example, docs/**/*.md will match docs/a/foo.md, docs/a/b/foo.md, etc. You can enter multiple glob patterns separated by commas, which is useful for searching in multiple file types or subdirectories.

When you have multiple project folders open, this feature can also be used to search in only one of those folders. For example, if you had the folders /path1/folder1 and /path2/folder2 open, you could enter a pattern starting with folder1 to search only in the first folder.

Press Esc while focused on the Find and Replace panel to clear the pane from your workspace.

The Find and Replace functionality is implemented in the find-and-replace package and uses the scandal Node module to do the actual searching.

Snippets

Snippets are an incredibly powerful way to quickly generate commonly needed code syntax from a shortcut.

The idea is that you can type something like habtm and then press the Tab key and it will expand into has_and_belongs_to_many.

Many Core and Community packages come bundled with their own snippets that are specific to it. For example, the language-html package that provides support for HTML syntax highlighting and grammar comes with dozens of snippets to create many of the various HTML tags you might want to use. If you create a new HTML file in Atom, you can type html and then press Tab and it will expand to:

<!DOCTYPE html>
<html lang="en" dir="ltr">
	<head>
		<meta charset="utf-8" />
		<title></title>
	</head>
	<body></body>
</html>

It will also position the cursor in the lang attribute value so you can edit it if necessary. Many snippets have multiple focus points that you can move through with the Tab key as well - for instance, in the case of this HTML snippet, after the cursor is placed in the lang attribute value, you can continue pressing Tab and the cursor will move to the dir attribute value, then to the middle of the title tag, then finally to the middle of the body tag.

To see all the available snippets for the file type that you currently have open, choose "Snippets: Available" in the Command Palette.

You can also use fuzzy search to filter this list down by typing in the selection box. Selecting one of them will execute the snippet where your cursor is (or multiple cursors are).

Creating Your Own Snippets

So that's pretty cool, but what if there is something the language package didn't include or something that is custom to the code you write? Luckily it's incredibly easy to add your own snippets.

There is a text file in your ~/.atom%USERPROFILE%\.atom directory called snippets.cson that contains all your custom snippets that are loaded when you launch Atom. You can also easily open up that file by selecting the Atom > SnippetsEdit > SnippetsFile > Snippets menu.

Snippet Format

So let's look at how to write a snippet. The basic snippet format looks like this:

'.source.js':
  'console.log':
    'prefix': 'log'
    'body': 'console.log(${1:"crash"});$2'

The leftmost keys are the selectors where these snippets should be active. The easiest way to determine what this should be is to go to the language package of the language you want to add a snippet for and look for the "Scope" string.

For example, if we wanted to add a snippet that would work for Java files, we would look up the language-java package in our Settings view and we can see the Scope is source.java. Then the top level snippet key would be that prepended by a period (like a CSS class selector would do).

The next level of keys are the snippet names. These are used for describing the snippet in a more readable way in the snippet menu. You can name them whatever you want.

Under each snippet name is a prefix that should trigger the snippet and a body to insert when the snippet is triggered.

Each $ followed by a number is a tab stop. Tab stops are cycled through by pressing Tab once a snippet has been triggered.

Tab stops with the same number will create multiple cursors.

The above example adds a log snippet to JavaScript files that would expand to:

console.log("crash");

The string "crash" would be initially selected and pressing tab again would place the cursor after the ;

Warning

Snippet keys, unlike CSS selectors, can only be repeated once per level. If there are duplicate keys at the same level, then only the last one will be read. See Configuring with CSON for more information.

Multi-line Snippet Body

You can also use CoffeeScript multi-line syntax using """ for larger templates:

'.source.js':
  'if, else if, else':
    'prefix': 'ieie'
    'body': """
      if (${1:true}) {
        $2
      } else if (${3:false}) {
        $4
      } else {
        $5
      }
    """

As you might expect, there is a snippet to create snippets. If you open up a snippets file and type snip and then press Tab, you will get the following text inserted:

'.source.js':
  'Snippet Name':
    'prefix': 'hello'
    'body': 'Hello World!'

💥 just fill that bad boy out and you have yourself a snippet. As soon as you save the file, Atom should reload the snippets and you will immediately be able to try it out.

Multiple Snippets per Source

You can see below the format for including multiple snippets for the same scope in your snippets.cson file. Just include the snippet name, prefix, and body keys for additional snippets inside the scope key:

'.source.gfm':
  'Hello World':
    'prefix': 'hewo'
    'body': 'Hello World!'

  'Github Hello':
    'prefix': 'gihe'
    'body': 'Octocat says Hi!'

  'Octocat Image Link':
    'prefix': 'octopic'
    'body': '![GitHub Octocat](https://assets-cdn.github.com/images/modules/logos_page/Octocat.png)'

Again, see Configuring with CSON for more information on CSON key structure and non-repeatability.

More Info

The snippets functionality is implemented in the snippets package.

For more examples, see the snippets in the language-html and language-javascript packages.

Autocomplete

If you're still looking to save some typing time, Atom also ships with simple autocompletion functionality.

The autocomplete system lets you view and insert possible completions in the editor using Tab or Enter.

By default, the autocomplete system will look through the current open file for strings that match what you're starting to type.

If you want more options, in the Settings panel for the autocomplete-plus package you can toggle a setting to make autocomplete-plus look for text in all your open buffers rather than just the current file.

The Autocomplete functionality is implemented in the autocomplete-plus package.

Folding

If you want to see an overview of the structure of the code file you're working on, folding can be a helpful tool. Folding hides blocks of code such as functions or looping blocks in order to simplify what is on your screen.

You can fold blocks of code by clicking the arrows that appear when you hover your mouse cursor over the gutter. You can also fold and unfold from the keyboard with the Alt+Cmd+[Alt+Ctrl+[ and Alt+Cmd+]Alt+Ctrl+] keybindings.

To fold everything, use Alt+Cmd+Shift+[Alt+Ctrl+Shift+[ and to unfold everything use Alt+Cmd+Shift+]Alt+Ctrl+Shift+]. You can also fold at a specific indentation level with Cmd+KCtrl+K Cmd+0-9Ctrl+0-9 where the number is the indentation depth.

Finally, you can fold arbitrary sections of your code or text by making a selection and then typing Alt+Cmd+Ctrl+FAlt+Ctrl+F or choosing "Fold Selection" in the Command Palette.

Panes

You can split any editor pane horizontally or vertically by using Cmd+KCtrl+K Up/Down/Left/Right where the direction key is the direction to split the pane. Once you have a split pane, you can switch between them with Cmd+KCtrl+K Cmd+Up/Down/Left/RightCtrl+Up/Down/Left/Right where the direction is the direction the focus should move to.

Each pane has its own "pane items", which are represented by tabs. You can move the files from pane to pane by dragging them with the mouse and dropping them in the pane you want that file to be in.

Tip

If you don't like using tabs, you don't have to. You can disable the tabs package and each pane will still support multiple pane items. You just won't have tabs to use to click between them.

To close a pane, you can close all pane items with Cmd+WCtrl+W. You can configure whether panes auto-close when empty in the Settings View with the "Remove Empty Panes" setting under Core Settings.

Pending Pane Items

"Pending Pane Items" were formerly referred to as "Preview Tabs"

When you open a new file by single-clicking in the Tree View, it will open in a new tab with an italic title. This indicates that the file is "pending". When a file is pending, it will be replaced by the next pending file that is opened. This allows you to click through a bunch of files to find something without having to go back and close them all.

You can confirm a pending file by doing any of the following:

• Double-clicking the tab of the file
• Double-clicking the file in the tree view
• Editing the contents of the file
• Saving the file

You can also open a file already confirmed by double-clicking it in the tree view instead of single-clicking it.

Disabling Pending Pane Items

If you would prefer to not have files open in pending form, you can disable this behavior by unchecking "Allow Pending Pane Items" in the Core Settings section of the Settings View. With pending pane items disabled, single-clicking a file in the Tree View will select the file but not open it. You will have to double-click the file to open it.

Grammar

The "grammar" of a file is what language Atom has associated with that file. Types of grammars would include "Java" or "GitHub-Flavored Markdown". We looked at this a bit when we created some snippets in Snippets.

When you load a file, Atom does a little work to try to figure out what type of file it is. Largely this is accomplished by looking at its file extension (.md is generally a Markdown file, etc), though sometimes it has to inspect the content a bit to figure it out.

When you open a file and Atom can't determine a grammar for the file, it will default to "Plain Text", which is the simplest one. If it does default to "Plain Text", picks the wrong grammar for the file, or if for any reason you wish to change the selected grammar, you can pull up the Grammar Selector with Ctrl+Shift+L.

When the grammar of a file is changed, Atom will remember that for the current session.

The Grammar Selector functionality is implemented in the grammar-selector package.

Version Control in Atom

Version control is an important aspect of any project and Atom comes with basic Git and GitHub integration built in.

In order to use version control in Atom, the project root needs to contain the Git repository.

Checkout HEAD revision

The Alt+Cmd+ZAlt+Ctrl+Z keybinding checks out the HEAD revision of the file in the editor.

This is a quick way to discard any saved and staged changes you've made and restore the file to the version in the HEAD commit. This is essentially the same as running git checkout HEAD -- <path> and git reset HEAD -- <path> from the command line for that path.

This command goes onto the undo stack so you can use Cmd+ZCtrl+Z afterwards to restore the previous contents.

Git status list

Atom ships with the fuzzy-finder package which provides Cmd+TCtrl+T to quickly open files in the project and Cmd+BCtrl+B to jump to any open editor. The package also provides Cmd+Shift+BCtrl+Shift+B which displays a list of all the untracked and modified files in the project. These will be the same files that you would see on the command line if you ran git status.

An icon will appear to the right of each file letting you know whether it is untracked or modified.

Commit editor

Atom can be used as your Git commit editor and ships with the language-git package which adds syntax highlighting to edited commit, merge, and rebase messages.

You can configure Atom to be your Git commit editor with the following command:

$ git config --global core.editor "atom --wait"

The language-git package will help remind you to be brief by colorizing the first lines of commit messages when they're longer than 50 or 65 characters.

Status bar icons

The status-bar package that ships with Atom includes several Git decorations that display on the right side of the status bar:

The currently checked out branch name is shown with the number of commits the branch is ahead of or behind its upstream branch. An icon is added if the file is untracked, modified, or ignored. The number of lines added and removed since the file was last committed will be displayed as well.

Line diffs

The included git-diff package colorizes the gutter next to lines that have been added, edited, or removed.

This package also adds Alt+G Down and Alt+G Up keybindings that allow you to move the cursor to the next or previous diff in the current editor.

Open on GitHub

If the project you're working on is on GitHub, there are also some very useful integrations you can use. Most of the commands will take the current file you're viewing and open a view of that file on GitHub - for instance, the blame or commit history of that file.

• Alt+G O - Open file on GitHub
• Alt+G B - Open Blame view of file on GitHub
• Alt+G H - Open History view of file on GitHub
• Alt+G C - Copy the URL of the current file on GitHub to the clipboard
• Alt+G R - Branch compare on GitHub

The branch comparison shows you the commits that are on the branch you're currently working on locally that are not on the mainline branch.

GitHub package

The github package brings Git and GitHub integration right inside Atom.

• Initialize
• Clone
• Branch
• Stage
• Discard
• Commit
• Amend and undo
• Publish and push
• Fetch and pull
• Resolve conflicts
• Create a Pull Request
• View Pull Requests
• Checkout a Pull Request
• Open any Issue or Pull Request
• View Pull Request review comments
• Navigate Pull Request review comments
• Respond to a Pull Request review comment

Most of the functionality lives within the Git and GitHub dock items.

There are different ways to access them, probably the most common way is through their keybindings:

• Open the Git panel: Ctrl+9
• Open the GitHub panel: Ctrl+8

Another way is from the menu: Packages -> GitHub -> Toggle Git Tab and Toggle GitHub Tab

Or you can also toggle the Git panel from the Status Bar by clicking on the changed files icon:

---

Initialize repositories

In case a project doesn't have a Git repository yet, you can create one from the Git panel.

Clone repositories

To clone a repository, open the GitHub panel while you have no project folders open in Atom and click "Clone an existing GitHub repository". In the dialog, paste the URL of a repository and click "Clone". The new project will be added to the Tree View.

Alternately, run the GitHub: Clone command to open the Clone dialog any time.

Branch

To open the branch tooltip, click the branch icon in the Status Bar. From there you can create or switch branches.

Stage

After making some changes, stage anything you want to be part of the next commit. Choose between staging...

• All changes: Click the "Stage All" button in the "Unstaged Changes" bar.
• Files: Double-click a file or select a file and press Enter.
• Hunk: Click on the "Stage Hunk" button or select a hunk and press Enter.
• Lines: Click on a line (or drag on multiple lines) to select, then click on the "Stage Selection" button. Or use the Cmd-/Cmd-/ key to toggle from hunk mode to line mode, then press Cmd-EnterCtrl-Enter to stage just a single line.

Use the Cmd-LeftCtrl-Left or Cmd-RightCtrl-Right arrow key to switch between file list and the diff view. Unstaging can be done in the same way.

Discard changes

If you no longer want to keep some changes, you can discard them. It's similar to staging, but accessible behind a context menu.

• All changes: Click the ... menu in the "Unstaged Changes" header and choose "Discard All Changes".
• Files: Right-click a file (or multiple) and choose "Discard Changes".
• Hunk: Click on the trash icon in the top bar of a hunk.
• Lines: Right-click on a line (or multiple) and choose "Discard Selection".

Commit Preview

To double check all changes that are going into your next commit, click the "See All Staged Changes" button above the commit message box. It lets you see all of your staged changes in a single pane. This "commit preview" can also serve as an inspiration for writing the commit message.

Commit

Once you've staged your changes, enter a commit message. Feel free to describe the commit in more detail after leaving an empty line. Finalize by clicking the Commit button. If you need more space, click the expand icon at the bottom right. It will open a commit editor in the center.

To add multiple co-authors to a commit, click the "👤➕" icon in the bottom left corner of the commit message editor. Now you can search by name, email or GitHub username to give credit to a co-author.

Amend and undo

In case you forgot to commit a change and would like to add it to your previous commit, right-click on the last commit, then choose "Amend" from the context menu.

If you want to edit the commit message of your last commit, or add/remove changes, click on the "Undo" button. It will roll back to the state just before you clicked on the commit button.

View commits

Once you've made some commits, click on a commit message in the recent commit list to see the full diff and commit message associated with each:

Publish and push

When you're ready to share your changes with your team members, click the Publish button in the Status Bar. It will push your local branch to the remote repository. After making more commits, you can Push them as well from the Status Bar.

Fetch and pull

From time to time it's a good idea to click on the Fetch button to see if any other team member pushed changes. If so, click on Pull to merge the changes into your local branch.

If you prefer to rebase when pulling, you can configure Git to make it the default behavior:

git config --global --bool pull.rebase true

Learn more about merge vs. rebase.

Resolve conflicts

Sometimes there can be conflicts when trying to merge. Files that have merge conflicts will show up in the "Merge Conflicts" list. Click on a file to open the editor. There you can resolve the conflict by picking a version or make further edits. Once done, stage the file and commit.

Create a Pull Request

When your changes are ready to be reviewed by your team members, open the "GitHub" panel Ctrl+8 and click on Open new pull request. It will open the browser where you can continue creating a pull request. If commits haven't been pushed or the branch isn't published yet, the GitHub package will do that automatically for you.

View Pull Requests

Once the pull request is created, it will appear under Current pull request at the top of the panel. Underneath is a list of Open pull requests. It lets you quickly find a pull request by avatar, title or PR number. It also lets you keep an eye on the CI status. Clicking on a pull request in the list opens a center pane with more details, the timeline and conversations.

Open any Issue or Pull Request

You can open issues or pull requests from any repo on GitHub. To do so, run the GitHub: Open Issue Or Pull Request command and paste the URL from an issue or pull request. Then press the Open Issue or Pull Request button and it will open a center pane. This lets you keep an issue or pull request as a reference, when working in another repo.

Checkout a Pull Request

To test a pull request locally, open it in the workspace center by clicking on the pull request in the "open pull requests" list from the GitHub tab, then click on the Checkout button. It will automatically create a local branch and pull all the changes. If you would like to contribute to that pull request, start making changes, commit and push. Your contribution is now part of that pull request.

View Pull Request review comments

To view review comments on a Pull Request, open the Reviews Tab from the See Reviews button from the footer of a Pull Request Pane. Alternatively, if the pull request has already been checked out, Reviews Tab can also be open from the same button on GitHub Tab.

Navigate Pull Request review comments

You can see all the review summaries and comments of a pull request in the Reviews Tab. The comment section has a progress bar to help you keep track of how close are you to finish addressing the Pull Request comments (i.e. marking all comment threads on a Pull Request as "resolved"). Comment threads are greyed out after they have been resolved.

After the pull request branch has been checked out, you can click Jump To File to open the commented on file and make changes as per the review comment right in the editor. If you would like to get the full context of the review comment, click Open Diff to open the diff view with line highlighting.

Conversely, in-editor comments are indicated by the comment icon in the gutter. Clicking the icon, either from within the editor or the diff view, will take you back to the Reviews Tab.

Respond to a Pull Request review comment

To respond to a Pull Request review comment, type your message and click Comment; a single line comment will be created in the same thread as the comment you responded to. After addressing a Pull Request review comment, click Resolve conversation to mark the whole thread as "resolved". The progress bar in the "Comments" section will update accordingly.

Writing in Atom

Though it is probably most common to use Atom to write software code, Atom can also be used to write prose quite effectively. Most often this is done in some sort of markup language such as Asciidoc or Markdown (in which this manual is written). Here we'll quickly cover a few of the tools Atom provides for helping you write prose.

In these docs, we'll concentrate on writing in Markdown; however, other prose markup languages like Asciidoc have packages that provide similar functionality.

Spell Checking

If you're working in text (which includes plain text files, GitHub markdown, and Git commit messages by default), Atom will automatically try to check your spelling.

Any misspelled words will be highlighted (by default with a dashed red line beneath the word), and you can pull up a menu of possible corrections by hitting Cmd+Shift+;Ctrl+Shift+; (or by choosing "Correct Spelling" from the right-click context menu or from the Command Palette).

To add more types of files to the list of what Atom will try to spell check, go to the Spell Check package settings in your Settings view and add any grammars you want to spell check.

The default grammars to spell check are text.plain, source.gfm, text.git-commit, source.asciidoc, source.rst, and text.restructuredtext but you can add other grammars if you wish to check those types of files too.

The spell checking is implemented in the spell-check package.

Previews

When writing prose in a markup language, it's often very useful to get an idea of what the content will look like when it's rendered. Atom ships with a package for previewing Markdown by default.

• Ctrl+Shift+M - Will toggle Preview mode for Markdown.

As you edit the text, the preview will also update automatically. This makes it fairly easy to check your syntax as you type.

You can also copy the rendered HTML from the preview pane into your system clipboard when the preview is focused and you press Cmd+CCtrl+CCtrl+Ins or if you right-click in the preview pane and choose "Copy as HTML".

Markdown preview is implemented in the markdown-preview package.

Snippets

There are also a number of great snippets available for writing Markdown quickly.

If you type img and hit tab you get a Markdown-formatted image embed code like ![](). If you type table and hit tab you get a nice example table to fill out.

| Header One | Header Two |
| :--------- | :--------- |
| Item One   | Item Two   |

Although there are only a handful of Markdown snippets (b for bold, i for italic, code for a code block, etc), they save you from having to look up the more obscure syntaxes. Again, you can easily see a list of all available snippets for the type of file you're currently in by choosing "Snippets: Available" in the Command Palette.

Basic Customization

Now that we are feeling comfortable with just about everything built into Atom, let's look at how to tweak it. Perhaps there is a keybinding that you use a lot but feels wrong or a color that isn't quite right for you. Atom is amazingly flexible, so let's go over some of the simpler flexes it can do.

Configuring with CSON

All of Atom's config files (with the exception of your style sheet and your Init Script) are written in CSON, short for CoffeeScript Object Notation. Just like its namesake JSON, JavaScript Object Notation, CSON is a text format for storing structured data in the form of simple objects made up of key-value pairs.

key:
  key: value
  key: value
  key: [value, value]

Objects are the backbone of any CSON file, and are delineated by indentation (as in the above example). A key's value can either be a String, a Number, an Object, a Boolean, null, or an Array of any of these data types.

Warning

Just like the more common JSON, CSON's keys can only be repeated once per object. If there are duplicate keys, then the last usage of that key overwrites all others, as if they weren't there. The same holds true for Atom's config files.

Don't do this:

# Only the second snippet will be loaded
'.source.js':
  'console.log':
    'prefix': 'log'
    'body': 'console.log(${1:"crash"});$2'
'.source.js':
  'console.error':
    'prefix': 'error'
    'body': 'console.error(${1:"crash"});$2'

Use this instead:

# Both snippets will be loaded
'.source.js':
  'console.log':
    'prefix': 'log'
    'body': 'console.log(${1:"crash"});$2'
  'console.error':
    'prefix': 'error'
    'body': 'console.error(${1:"crash"});$2'

Style Tweaks

If you want to apply quick-and-dirty personal styling changes without creating an entire theme that you intend to publish, you can add styles to the styles.less file in your ~/.atom%USERPROFILE%\.atom directory. You can open this file in an editor from the Atom > StylesheetFile > StylesheetEdit > Stylesheet menu.

For example, to change the colors of the Status Bar, you could add the following rule to your styles.less file:

.status-bar {
	color: white;
	background-color: black;
}

The easiest way to see what classes are available to style is to inspect the DOM manually via the Developer Tools. We'll go over the Developer Tools in great detail in the next chapter, but for now let's take a simple look. You can open the Developer Tools by pressing Alt+Cmd+ICtrl+Shift+I, which will bring up the Chromium Developer Tools panel.

With the Developer Tools, you can inspect all the elements in Atom. If you want to update the style of something, you can figure out what classes it has and add a Less rule to your stylesheet to modify it.

Tip

If you are unfamiliar with Less, it is a basic CSS preprocessor that makes some things in CSS a bit easier. You can learn more about it at lesscss.org.

If you prefer to use CSS instead, you can do that in the same styles.less file, since CSS is also valid in Less.

Customizing Keybindings

Atom keymaps work similarly to stylesheets. Just as stylesheets use selectors to apply styles to elements, Atom keymaps use selectors to associate key combinations with events in specific contexts. Here's a small example, excerpted from Atom's built-in keymap:

'atom-text-editor':
  'enter': 'editor:newline'

'atom-text-editor[mini] input':
  'enter': 'core:confirm'

This keymap defines the meaning of Enter in two different contexts. In a normal editor, pressing Enter triggers the editor:newline command, which causes the editor to insert a newline. But if the same keystroke occurs inside a select list's mini-editor, it instead triggers the core:confirm command based on the binding in the more-specific selector.

By default, keymap.cson is loaded when Atom is started. It will always be loaded last, giving you the chance to override bindings that are defined by Atom's core keymaps or third-party packages. You can open this file in an editor from the Atom > KeymapFile > KeymapEdit > Keymap menu.

You can see all the keybindings that are currently configured in your installation of Atom in the Keybindings tab in the Settings View.

If you run into problems with keybindings, the Keybinding Resolver is a huge help. It can be opened with the Cmd+.Ctrl+. key combination. It will show you what keys Atom saw you press and what command Atom executed because of that combination.

Global Configuration Settings

Atom loads configuration settings from the config.cson file in your ~/.atom%USERPROFILE%\.atom directory.

'*':
  'core':
    'excludeVcsIgnoredPaths': true
  'editor':
    'fontSize': 18

The configuration is grouped into global settings under the * key and language-specific settings under scope named keys like .python.source or .html.text. Underneath that, you'll find configuration settings grouped by package name or one of the two core namespaces: core or editor.

You can open this file in an editor from the Atom > ConfigFile > ConfigEdit > Config menu.

Configuration Key Reference

• core
  • customFileTypes: Associations of language scope to file extensions (see Customizing Language Recognition)
  • disabledPackages: An array of package names to disable
  • excludeVcsIgnoredPaths: Don't search within files specified by .gitignore
  • ignoredNames: File names to ignore across all of Atom
  • projectHome: The directory where projects are assumed to be located
  • themes: An array of theme names to load, in cascading order
• editor
  • autoIndent: Enable/disable basic auto-indent (defaults to true)
  • nonWordCharacters: A string of non-word characters to define word boundaries
  • fontSize: The editor font size
  • fontFamily: The editor font family
  • invisibles: A hash of characters Atom will use to render whitespace characters. Keys are whitespace character types, values are rendered characters (use value false to turn off individual whitespace character types)
    • tab: Hard tab characters
    • cr: Carriage return (for Microsoft-style line endings)
    • eol: \n characters
    • space: Leading and trailing space characters
  • lineHeight: Height of editor lines, as a multiplier of font size
  • preferredLineLength: Identifies the length of a line (defaults to 80)
  • showInvisibles: Whether to render placeholders for invisible characters (defaults to false)
  • showIndentGuide: Show/hide indent indicators within the editor
  • showLineNumbers: Show/hide line numbers within the gutter
  • softWrap: Enable/disable soft wrapping of text within the editor
  • softWrapAtPreferredLineLength: Enable/disable soft line wrapping at preferredLineLength
  • tabLength: Number of spaces within a tab (defaults to 2)
• fuzzyFinder
  • ignoredNames: Files to ignore only in the fuzzy-finder
• whitespace
  • ensureSingleTrailingNewline: Whether to reduce multiple newlines to one at the end of files
  • removeTrailingWhitespace: Enable/disable stripping of whitespace at the end of lines (defaults to true)
• wrap-guide
  • columns: Array of hashes with a pattern and column key to match the path of the current editor to a column position.

Language Specific Configuration Settings

You can also set several configuration settings differently for different file types. For example, you may want Atom to soft wrap markdown files, have two-space tabs for ruby files, and four-space tabs for python files.

There are several settings now scoped to an editor's language. Here is the current list:

editor.autoIndent
editor.autoIndentOnPaste
editor.invisibles
editor.nonWordCharacters
editor.preferredLineLength
editor.scrollPastEnd
editor.showIndentGuide
editor.showInvisibles
editor.softWrap
editor.softWrapAtPreferredLineLength
editor.softWrapHangingIndent
editor.tabLength

Language-specific Settings in the Settings View

You can edit these config settings in the Settings View on a per-language basis. Click on "Packages" tab in the navigation bar on the left, search for the language of your choice, select it, and edit away!

Language-specific Settings in your Config File

You can also edit the config.cson directly. To open your configuration file via the Command Palette, press Cmd+Shift+PCtrl+Shift+P type open config, and press Enter.

Global settings are under the * key, and each language can have its own top-level key. This key is the language's scope. Language-specific settings take precedence over anything set in the global section for that language only.

'*': # all languages unless overridden
  'editor':
    'softWrap': false
    'tabLength': 8

'.source.gfm': # markdown overrides
  'editor':
    'softWrap': true

'.source.ruby': # ruby overrides
  'editor':
    'tabLength': 2

'.source.python': # python overrides
  'editor':
    'tabLength': 4

Finding a Language's Scope Name

In order to write these overrides effectively, you'll need to know the scope name for the language. We've already done this for finding a scope for writing a snippet in Snippet Format, but we can quickly cover it again.

The scope name is shown in the settings view for each language. Click on "Packages" in the navigation on the left, search for the language of your choice, select it, and you should see the scope name under the language name heading:

Another way to find the scope for a specific language is to open a file of its kind and press Alt+Cmd+Pchoose "Editor: Log Cursor Scope" in the Command Palette to show all scopes for the current position of the cursor. The scope mentioned top most is always the language for this kind of file, the scopes following are specific to the cursor position:

These scopes can be especially useful to style the editor, since they can also be used as class names in your stylesheet.

Customizing Language Recognition

If you want Atom to always recognize certain file types as a specific grammar, you'll need to manually edit your config.cson file. You can open it using the Application: Open Your Config command from the Command Palette. For example, if you wanted to add the foo extension to the CoffeeScript language, you could add this to your configuration file under the *.core section:

'*':
  core:
    customFileTypes:
      'source.coffee': [
        'foo'
      ]

In the example above, source.coffee is the language's scope name (see Finding a Language's Scope Name for more information) and foo is the file extension to match without the period. Adding a period to the beginning of either of these will not work.

Controlling Where Customization is Stored to Simplify Your Workflow

The CSON configuration files for Atom are stored on disk on your machine. The location for this storage is customizable. The default is to use the home directory of the user executing the application. The Atom Home directory will, by default, be called .atom and will be located in the root of the home directory of the user.

Custom home location with an environment variable

An environment variable can be used to make Atom use a different location. This can be useful for several reasons. One of these may be that multiple user accounts on a machine want to use the same Atom Home. The environment variable used to specify an alternate location is called ATOM_HOME. If this environment variable exists, the location specified will be used to load and store Atom settings.

Taking your customization with you with Portable Mode

In addition to using the ATOM_HOME environment variable, Atom can also be set to use "Portable Mode".

Portable Mode is most useful for taking Atom with you, with all your custom setting and packages, from machine to machine. This may take the form of keeping Atom on a USB drive or a cloud storage platform that syncs folders to different machines, like Dropbox. Atom is in Portable Mode when there is a directory named .atom sibling to the directory in which the atom executable file lives. For example, the installed Atom directory can be placed into a Dropbox folder next to a .atom folder.

With such a setup, Atom will use the same Home directory with the same settings for any machine with this directory syncronized/plugged in.

Moving to Portable Mode

Atom provides a command-line parameter option for setting Portable Mode.

$ atom --portable

Executing atom with the --portable option will take the .atom directory you have in the default location (~/.atom) and copy the relevant contents for your configuration to a new home directory in the Portable Mode location. This enables easily moving from the default location to a portable operation without losing the customization you have already set up.

Summary

At this point you should be something of an Atom master user. You should be able to navigate and manipulate your text and files like a wizard. You should also be able to customize Atom backwards and forwards to make it look and act just how you want it to.

In the next chapter, we're going to kick it up a notch: we'll take a look at changing and adding new functionality to the core of Atom itself. We're going to start creating packages for Atom. If you can dream it, you can build it.