Chapter 1 : Getting started
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.
Getting Started
This chapter is about getting started with Atom.
Why Atom?
There are a lot of text editors out there; why should you spend your time learning about and using Atom?
Editors like Sublime and TextMate offer convenience but only limited extensibility. On the other end of the spectrum, Emacs and Vim offer extreme flexibility, but they aren't very approachable and can only be customized with special-purpose scripting languages.
We think we can do better. Our goal is a zero-compromise combination of hackability and usability: an editor that will be welcoming to an elementary school student on their first day learning to code, but also a tool they won't outgrow as they develop into seasoned hackers.
As we've used Atom to build Atom, what began as an experiment has gradually matured into a tool we can't live without. On the surface, Atom is the modern desktop text editor you've come to expect. Pop the hood, however, and you'll discover a system begging to be hacked on.
The Nucleus of Atom
The web is not without its faults, but two decades of development has forged it into an incredibly malleable and powerful platform. So when we set out to write a text editor that we ourselves would want to extend, web technology was the obvious choice. But first, we had to free it from its chains.
The Native Web
Web browsers are great for browsing web pages, but writing code is a specialized activity that warrants dedicated tools. More importantly, the browser severely restricts access to the local system for security reasons, and for us, a text editor that couldn't write files or run local subprocesses was a non-starter.
For this reason, we didn't build Atom as a traditional web application. Instead, Atom is a specialized variant of Chromium designed to be a text editor rather than a web browser. Every Atom window is essentially a locally-rendered web page.
All the APIs available to a typical Node.js application are also available to the code running in each window's JavaScript context. This hybrid provides a unique client-side development experience.
Since everything is local, you don't have to worry about asset pipelines, script concatenation, and asynchronous module definitions. If you want to load some code, just require it at the top of your file. Node's module system makes it easy to break the system down into lots of small, focused packages.
JavaScript, Meet C++
Interacting with native code is also really simple. For example, we wrote a wrapper around the Oniguruma regular expression engine for our TextMate grammar support. In a browser, that would have required adventures with NaCl or Esprima. Node integration made it easy.
In addition to the Node APIs, we also expose APIs for native dialogs, adding application and context menu items, manipulating the window dimensions, etc.
Web Tech: The Fun Parts
Another great benefit, that comes with writing code for Atom, is the guarantee that it's running on the newest version of Chromium. That means we can ignore issues like browser compatibility and polyfills. We can use all the web's shiny features of tomorrow, today.
For example, the layout of our workspace and panes is based on flexbox. It's an emerging standard and has gone through a lot of change since we started using it, but none of that mattered as long as it worked.
With the entire industry pushing web technology forward, we're confident that we're building Atom on fertile ground. Native UI technologies come and go, but the web is a standard that becomes more capable and ubiquitous with every passing year. We're excited to dig deeper into its toolbox.
An Open-Source Text Editor
We see Atom as a perfect complement to GitHub's primary mission of building better software by working together. Atom is a long-term investment, and GitHub will continue to support its development with a dedicated team going forward. But we also know that we can't achieve our vision for Atom alone. As Emacs and Vim have demonstrated over the past three decades, if you want to build a thriving, long-lasting community around a text editor, it has to be open source.
The entire Atom editor is free and open source and is available under the https://github.com/atom organization.
Installing Atom
To get started with Atom, we'll need to get it on your system. This section will go over installing Atom on your system, as well as the basics of how to build it from source.
Installing Atom should be fairly simple. Generally, you can go to https://atom.io and you should see a download button as shown here:
The button or buttons should be specific to your platform and the download package should be easily installable. However, let's go over them here in a bit of detail.
Updating Atom
You should consider updating Atom periodically for the latest improvements to the software. Additionally, When Atom receives hotfixes for security vulnerabilities you will want to update your version of Atom as soon as possible.
Portable Mode
Atom stores configuration and state in a .atom directory usually located in your home directory (%userprofile% on Windows). You can however run Atom in portable mode where both the app and the configuration are stored together such as on a removable storage device.
To setup Atom in portable mode download the zip/tar.gz package for your system and extract it to your removable storage.
Portable Notes
- The
.atomdirectory must be writeable - You can move an existing
.atomdirectory to your portable device - Atom can also store its Electron user data in your
.atomdirectory - just create a subdirectory calledelectronUserDatainside.atom - Alternatively you can set the
ATOM_HOMEenvironment variable to point wherever you want (you can write a .sh or .cmd script to temporarily set it and launch it from that) - Portable mode installations will not automatically update
Building Atom from Source
The Hacking on Atom Core section of the flight manual covers instructions on how to clone and build the source code if you prefer that option.
Proxy and Firewall Settings
Behind a Firewall?
If you are behind a firewall and seeing SSL errors when installing packages you can disable strict SSL by running:
$ apm config set strict-ssl false
Using a Proxy?
If you are using a HTTP(S) proxy you can configure apm to use it by running:
$ apm config set https-proxy <em>YOUR_PROXY_ADDRESS</em>
You can run apm config get https-proxy to verify it has been set correctly.
Atom Basics
Now that Atom is installed on your system, let's fire it up, configure it and get acquainted with the editor.
When you launch Atom for the first time, you should get a screen that looks like this:
This is the Atom welcome screen and gives you a pretty good starting point for how to get started with the editor.
Terminology
You can find definitions for all of the various terms that we use throughout the manual in our Glossary.
Command Palette
In that welcome screen, we are introduced to probably the most important command in Atom, the Command Palette. If you press Cmd+Shift+PCtrl+Shift+P while focused in an editor pane, the command palette will pop up.
Note:
Throughout the book, we will use shortcut keybindings like Cmd+Shift+PCtrl+Shift+P to demonstrate how to run a command. These are the default keybindings for the platform that we detected you running.
If you want to see a different platform than the one we detected, you may choose a different one by using the platform selector near the top of the page:
If the Platform Selector is not present, then the current page doesn't have any platform-specific content.
If you have customized your Atom keymap, you can always see the keybinding you have mapped in the Command Palette or the Keybindings tab in the Settings View.
This search-driven menu can do just about any major task that is possible in Atom. Instead of clicking around all the application menus to look for something, you can press Cmd+Shift+PCtrl+Shift+P and search for the command.
Not only can you see and quickly search through thousands of possible commands, but you can also see if there is a keybinding associated with it. This is great because it means you can guess your way to doing interesting things while also learning the shortcut keystrokes for doing it.
For the rest of the book, we will try to be clear as to the text you can search for in the Command Palette in addition to the keybinding for different commands.
Settings and Preferences
Atom has a number of settings and preferences you can modify in the Settings View.
This includes things like changing the theme, specifying how to handle wrapping, font settings, tab size, scroll speed and much more. You can also use this screen to install new packages and themes, which we'll cover in Atom Packages.
To open the Settings View, you can: ::: tabs Settings View
- Use the Edit > Preferences menu item in the menu bar
- Use the Atom > Preferences menu item in the menu bar
- Use the File > Settings menu item in the menu bar
:::
- Search for
settings-view:openin the Command Palette - Use the Cmd+, or Ctrl+, keybinding
Changing the Theme
The Settings View also lets you change the themes for Atom. Atom ships with 4 different UI themes, dark and light variants of the Atom and One theme, as well as 8 different syntax themes. You can modify the active theme by clicking on the Themes tab in the sidebar of the Settings View, or you can install new themes by clicking the Install tab.
The UI themes control the style of UI elements like the tabs and the tree view, while the syntax themes control the syntax highlighting of text you load into the editor. To change the syntax or UI theme, simply pick something different in the appropriate dropdown list.
There are also dozens of themes on https://atom.io that you can choose from if you want something different. We will cover customizing a theme in Style Tweaks and creating your own theme in Creating a Theme.
Soft Wrap
You can use the Settings View to specify your whitespace and wrapping preferences.
Enabling "Soft Tabs" will insert spaces instead of actual tab characters when you press the Tab key and the "Tab Length" setting specifies how many spaces to insert when you do so, or how many spaces are used to represent a tab if "Soft Tabs" is disabled.
The "Soft Wrap" option will wrap lines that are too long to fit in your current window. If soft wrapping is disabled, the lines will simply run off the side of the screen and you will have to scroll the window to see the rest of the content. If "Soft Wrap At Preferred Line Length" is toggled, the lines will wrap at 80 characters instead of the end of the screen. You can also change the default line length to a value other than 80 on this screen.
In Basic Customization we will see how to set different wrap preferences for different types of files (for example, if you want to wrap Markdown files but not other files).
Opening, Modifying, and Saving Files
Now that your editor is looking and acting how you want, let's start opening up and editing files. This is a text editor after all, right?
Opening a File
There are several ways to open a file in Atom. You can do it by choosing File > Open from the menu bar or by pressing Cmd+O Ctrl+O to choose a file from the standard dialog.
This is useful for opening a file that is not contained in the project you're currently in (more on that next), or if you're starting from a new window for some reason.
Another way to open a file in Atom is from the command line using the atom command. The Atom menu bar has a command named "Install Shell Commands" which installs the atom and apm commands if Atom wasn't able to install them itself .The atom and apm commands are installed automatically as a part of Atom's installation process.
You can run the atom command with one or more file paths to open up those files in Atom.
$ atom --help
> Atom Editor v1.8.0
> Usage: atom [options] [path ...]
> One or more paths to files or folders may be specified. If there is an
> existing Atom window that contains all of the given folders, the paths
> will be opened in that window. Otherwise, they will be opened in a new
> window.
> ...
This is a great tool if you're used to the terminal or you work from the terminal a lot. Just fire off atom [files] and you're ready to start editing. You can even open a file at a certain line (and optionally column) so the cursor will be positioned exactly where you want. For example, you may search some keyword in a repository to find the line you want to edit:
$ git grep -n 'Opening a File$'
content/getting-started/sections/atom-basics.md:84:##### Opening a File
and then jump to the beginning of that line by appending a colon and the line number to the file path:
$ atom content/getting-started/sections/atom-basics.md:84
Sometimes you may want the cursor to jump to the exact column position of the searched keyword. Just append another colon plus the column number:
$ git grep -n --column 'Windows Explorer'
content/getting-started/sections/atom-basics.md:150:722
$ atom content/getting-started/sections/atom-basics.md:150:722
Editing and Saving a File
Editing a file is pretty straightforward. You can click around and scroll with your mouse and type to change the content. There is no special editing mode or key commands. If you prefer editors with modes or more complex key commands, you should take a look at the Atom package list. There are a lot of packages that emulate popular styles.
To save a file you can choose File > Save from the menu bar or Cmd+SCtrl+S to save the file. If you choose File > Save As or press Cmd+Shift+SCtrl+Shift+S then you can save the current content in your editor under a different file name. Finally, you can choose File > Save All or press Alt+Cmd+S to save all the open files in Atom.
Opening Directories
Atom doesn't just work with single files though; you will most likely spend most of your time working on projects with multiple files. To open a directory, choose the menu item File > OpenFile > Open Folder and select a directory from the dialog. You can also add more than one directory to your current Atom window, by choosing File > Add Project Folder from the menu bar or pressing Cmd+Shift+OCtrl+Shift+A.
You can open any number of directories from the command line by passing their paths to the atom command line tool. For example, you could run the command atom ./hopes ./dreams to open both the hopes and the dreams directories at the same time.
When you open Atom with one or more directories, you will automatically get a Tree View on the side of your window.
The Tree View allows you to explore and modify the file and directory structure of your project. You can open, rename, delete and create new files from this view.
You can also hide and show it with Cmd+\Ctrl+\ or the tree-view: toggle command from the Command Palette, and Ctrl+0 Alt+\ will focus it. When the Tree view has focus you can press A, M, or Delete to add, move or delete files and folders. You can also right-click on a file or folder in the Tree view to see many of the various options, including all of these plus showing the file in FinderWindows Exploreryour native filesystem or copying the file path to the clipboard.
Note
Atom Packages
Like many parts of Atom, the Tree View is not built directly into the editor, but is its own standalone package that is shipped with Atom by default. Packages that are bundled with Atom are referred to as Core packages. Ones that aren't bundled with Atom are referred to as Community packages.
You can find the source code to the Tree View on GitHub at https://github.com/atom/tree-view.
This is one of the interesting things about Atom. Many of its core features are actually just packages implemented the same way you would implement any other functionality. This means that if you don't like the Tree View for example, you could write your own implementation of that functionality and replace it entirely.
Opening a File in a Project
Once you have a project open in Atom, you can easily find and open any file within that project.
If you press Cmd+TCtrl+T or Cmd+PCtrl+P, the Fuzzy Finder will pop up. This will let you quickly search for any file in your project by typing parts of the path.
You can also search through only the files currently opened (rather than every file in your project) with Cmd+BCtrl+B. This searches through your "buffers" or open files. You can also limit this fuzzy search with Cmd+Shift+BCtrl+Shift+B, which searches only through the files which are new or have been modified since your last Git commit.
The fuzzy finder uses the core.ignoredNames, fuzzy-finder.ignoredNames and core.excludeVCSIgnoredPaths configuration settings to filter out files and folders that will not be shown. If you have a project with tons of files you don't want it to search through, you can add patterns or paths to either of these config settings or your standard .gitignore files. We'll learn more about config settings in Global Configuration Settings, but for now you can easily set these in the Settings View under Core Settings.
Both core.ignoredNames and fuzzy-finder.ignoredNames are interpreted as glob patterns as implemented by the minimatch Node module.
Tips
Configuration Setting Notation
Sometimes you'll see us refer to configuration settings all spelled out like "Ignored Names in Core Settings". Other times you'll see us use the shorthand name like core.ignoredNames. Both of these refer to the same thing. The shorthand is the package name, then a dot ., followed by the "camel-cased" name of the setting.
If you have a phrase you want to camel-case, follow these steps:
- Lowercase the first word
- Capitalize the first letter in all other words
- Remove the spaces
So "Ignored Names" becomes "ignoredNames".
Summary
You should now have a basic understanding of what Atom is and what you want to do with it. You should also have it installed on your system and be able to use it for the most basic text editing operations.
Now you're ready to start digging into the fun stuff.