Using Pulsar

Under Construction

This document is under construction, please check back soon for updates. Please see our socials and feel free to ask for assistance or inquire as to the status of this document.

Pulsar Packages

First we'll start with the Pulsar package system. As we mentioned previously, Pulsar 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 Pulsar by default. For example, the Welcome screen that you see when you first start Pulsar, 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 the Core.

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 LNX/WIN: Ctrl+, - MAC: Cmd+, 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://web.pulsar-edit.dev which is the official registry for Pulsar packages. Searching on the Settings View will go to the Pulsar 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 Pulsar, it will show up in the Settings View under the "Packages" tab, along with all the pre-installed packages that come with Pulsar. 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, Pulsar 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.

Pulsar Themes

You can also find and install new themes for Pulsar 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 pulsar-edit.dev, 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 ppm (Pulsar Package Manager). This is used by running pulsar -p <commmand> or pulsar --package <command>.

Tip

Check that you have ppm available by running the following command in your terminal:

$ pulsar -p help install

You should see a message print out with details about the pulsar -p install command.

If you do not, see the Installing Pulsar section for instructions on how to install the pulsar command for your system.

You can install packages by using the pulsar -p install command:

• pulsar -p install <package_name> to install the latest version.
• pulsar -p install <package_name>@<package_version> to install a specific version.

For example pulsar -p install minimap@4.40.0 installs the 4.40.0 release of the minimap package.

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

$ pulsar -p search linter
> Search Results For 'linter' (30)
> ├── linter A Base Linter with Cow Powers (9863242 downloads, 4757 stars)
> ├── linter-ui-default Default UI for the Linter package (7755748 downloads, 1201 stars)
> ├── linter-eslint Lint JavaScript on the fly, using ESLint (v7 or older) (2418043 downloads, 1660 stars)
> ├── linter-jshint Linter plugin for JavaScript, using jshint (1202044 downloads, 1271 stars)
> ├── linter-gcc Lint C and C++ source files using gcc / g++ (863989 downloads, 194 stars)
> ...
> ├── linter-shellcheck Lint Bash on the fly, using shellcheck (136938 downloads, 280 stars)
> └── linter-rust Lint Rust-files, using rustc and/or cargo (132550 downloads, 91 stars)

You can use pulsar -p view to see more information about a specific package.

$ pulsar -p view linter
> linter
> ├── 3.4.0
> ├── https://github.com/steelbrain/linter
> ├── A Base Linter with Cow Powers
> ├── 9863242 downloads
> └── 4757 stars
>
> Run `pulsar -p install linter` to install this package.

Using ppm to install from other sources

By default ppm will be using the Pulsar Package Repository. However you can also use it to install from other locations which can be useful if you are trying to install a package not published to the Pulsar Package Repository.

Github or Git Remotes

Pulsar can install from a GitHub repository or any valid git remote url. The -b option can then be used to specify a particular tag or branch.

Git remote
pulsar -p install <git_remote> [-b <branch_or_tag>]

GitHub
pulsar -p install <github_username>/<github_project> [-b <branch_or_tag>]

For example to install the Generic-LSP package from GitHub you could use either:

pulsar -p install https://github.com/mauricioszabo/generic-lsp/

or

pulsar -p install mauricioszabo/generic-lsp

This will use the current HEAD commit of the default branch. If you want to install a specific version from a branch or tag then use the -b option:

e.g. pulsar -p install https://github.com/mauricioszabo/generic-lsp/ -b v1.0.3

Moving in Pulsar

While it's pretty easy to move around Pulsar 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.

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

Pulsar 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 LNX: Edit > Keymap - MAC: Pulsar > Keymap - WIN: File > 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 LNX/WIN: Ctrl+Shift+E - MAC: Cmd+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 LNX/WIN: Ctrl+R - MAC: Cmd+R. This opens a list of all symbols in the current file, which you can fuzzy filter similarly to LNX/WIN: Ctrl+T - MAC: Cmd+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, LNX/MAC: ~/.ctags - WIN: %USERPROFILE%\.ctags. An example can be found here.

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

Bookmarks

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

If you press LNX/WIN: Alt+Ctrl+F2 - MAC Cmd+F2, Pulsar 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, Pulsar 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.

Pulsar Selections

Text selections in Pulsar 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.

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.

Pulsar 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 LNX/WIN: Ctrl+Shift+Q - MAC: Alt+Cmd+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.

Multiple Cursors and Selections

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

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 package or command - for example, changing case and moving or duplicating lines.

You can also use the mouse to select text with the LNX/WIN: Ctrl - MAC: Cmd key pressed down to select multiple regions of your text simultaneously.

Return to a single cursor with Esc or by clicking anywhere in the file to position a cursor there as normal.

Whitespace

Pulsar 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 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 Pulsar, 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.

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

Brackets

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

Pulsar will also automatically autocomplete [], (), and {}, "", '', “”, ‘’, «», ‹›, and `` when you type the leading one. If you have a selection and you type any of these opening brackets or quotes, Pulsar 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.

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

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

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, Pulsar will try to auto-detect the encoding. If Pulsar 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 Pulsar.

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 LNX/WIN: Ctrl+F - MAC: Cmd+F, type in a search string and press LNX/WIN/MAC: Enter or LNX/WIN: F3 - MAC: Cmd+G or the "Find Next" button) multiple times to cycle through all the matches in that file. Alt+Enter will find all occurrences 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 "Atom" with the string "Pulsar", you would enter those values in the two text boxes and press the "Replace All" button to perform the replacements.

Note

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

You can also find and replace throughout your entire project if you invoke the panel with LNX/WIN: Ctrl+Shift+F - MAC: Cmd+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 Pulsar, 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 LNX/MAC: ~/.pulsar - WIN: %USERPROFILE%\.pulsar directory called snippets.cson that contains all your custom snippets that are loaded when you launch Pulsar. You can also easily open up that file by selecting the LNX: Edit > Snippets - MAC: Pulsar > Snippets - WIN: File > 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, Pulsar 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, Pulsar 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.

Panes

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.

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 Pulsar 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, Pulsar 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 Pulsar 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 Pulsar

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

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

Checkout HEAD revision

The LNX/WIN: Alt+Ctrl+Z - MAC: Alt+Cmd+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 LNX/WIN: Ctrl+Z - MAC: Cmd+Z afterwards to restore the previous contents.

Git status list

Pulsar ships with the fuzzy-finder package which provides LNX/WIN: Ctrl+T - MAC: Cmd+T to quickly open files in the project and LNX/WIN: Ctrl+B - MAC: Cmd+B to jump to any open editor. The package also provides LNX/WIN: Ctrl+Shift+B - MAC: Cmd+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

Pulsar 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 Pulsar to be your Git commit editor with the following command:

$ git config --global core.editor "pulsar --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 Pulsar 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+GUp 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 Pulsar.

• 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 Pulsar 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 LNX/WIN: Ctrl+/ - MAC: Cmd-/ key to toggle from hunk mode to line mode, then press LNX/WIN: Ctrl-Enter - MAC: Cmd-Enter to stage just a single line.

Use the LNX/WIN: Cmd-Left - MAC: Ctrl-Left or LNX/WIN: Ctrl-Right - MAC: Cmd-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 Pulsar

Though it is probably most common to use Pulsar to write software code, Pulsar 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 Pulsar 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), Pulsar 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 LNX/WIN: Ctrl+Shift+; - MAC: Cmd+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 Pulsar 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. Pulsar 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 LNX: Ctrl+Ins - WIN: Ctrl+C - MAC: Cmd+C 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 Pulsar, 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. Pulsar is amazingly flexible, so let's go over some of the simpler flexes it can do.

Configuring with CSON

All of Pulsar'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 Pulsar'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 LNX/MAC: ~/.pulsar - WIN: %USERPROFILE%\.pulsar directory. You can open this file in an editor from the LNX: Edit > Stylesheet - MAC: Pulsar > Stylesheet - WIN: File > 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 LNX/WIN: Ctrl+Shift+I - MAC: Alt+Cmd+I, which will bring up the Chromium Developer Tools panel.

With the Developer Tools, you can inspect all the elements in Pulsar. 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

Pulsar keymaps work similarly to stylesheets. Just as stylesheets use selectors to apply styles to elements, Pulsar keymaps use selectors to associate key combinations with events in specific contexts. Here's a small example, excerpted from Pulsar'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 Pulsar is started. It will always be loaded last, giving you the chance to override bindings that are defined by Pulsar's core keymaps or third-party packages. You can open this file in an editor from the LNX: Edit > Keymap - MAC: Pulsar > Keymap - WIN: File > Keymap menu.

You can see all the keybindings that are currently configured in your installation of Pulsar 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 LNX/WIN: Ctrl+. - MAC: Cmd+. key combination. It will show you what keys Pulsar saw you press and what command Pulsar executed because of that combination.

Global Configuration Settings

Pulsar loads configuration settings from the config.cson file in your LNX/MAC: ~/.pulsar - WIN: %USERPROFILE%\.pulsar 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 LNX: Edit > Config - MAC: Pulsar > Config - WIN: File > 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 Pulsar
  • 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 Pulsar 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 Pulsar 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 LNX/WIN: Ctrl+Shift+P - MAC: Cmd+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:

• LNX/WIN: Choose "Editor: Log Cursor Scope" in the Command Palette
• MAC: Press Alt+Cmd+P 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 Pulsar 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 Pulsar 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 Pulsar Home directory will, by default, be called .pulsar 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 Pulsar 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 Pulsar 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 Pulsar settings.

Taking your customization with you with Portable Mode

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

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

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

Moving to Portable Mode

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

$ pulsar --portable

Executing pulsar with the --portable option will take the .pulsar directory you have in the default location (~/.pulsar) 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 a Pulsar master user. You should be able to navigate and manipulate your text and files like a wizard. You should also be able to customize Pulsar backwards and forwards to make it look and act just how you want it to.

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