Getting Started

Under Construction

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

This section is all about how to start using Pulsar, such as how to install it and how to use it for basic text editing.

Why Pulsar?

There are a lot of text editors out there; why should you spend your time learning about and using Pulsar? 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 Pulsar to build Pulsar, what began as an experiment has gradually matured into a tool we can't live without. On the surface, Pulsar 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 Pulsar

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 sub-processes was a non-starter.

For this reason, we didn't build Pulsar as a traditional web application. Instead, Pulsar is a specialized variant of Chromium designed to be a text editor rather than a web browser. Every Pulsar 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 Pulsar, 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 Pulsar 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 Pulsar as a great replacement for Atom but we can't do it without your support going forward, since we know that we can't achieve our vision for Pulsar 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 Pulsar editor is free and open source and available under our Organizational repositories.

Installing Pulsar

To get started with Pulsar, we'll need to get it on your system. This section will go over installing Pulsar on your system, as well as the basics of how to build it from source.

Installing Pulsar should be fairly simple. Generally, you can go to pulsar-edit.dev and you should see a download button.

Simply select your operating system (if not opened automatically) and architecture (where necessary) and choose the type of download you require.

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 Pulsar

You should consider updating Pulsar periodically for the latest improvements to the software. Additionally, When Pulsar receives hotfixes for security vulnerabilities you will want to update your version of Pulsar as soon as possible.

Currently Pulsar does not support automatic updates. What this means is that new versions will have to be obtained via the Pulsar Downloads here on our website. This is something on our roadmap to change as soon as possible.

If you have installed Pulsar via a package manager then you should use the instructions provided by that package manager for updating your installation.

Portable Mode

Pulsar stores configuration and state in a .pulsar directory usually located in your home directory (%userprofile% on Windows). You can however run Pulsar in portable mode where both the app and the configuration are stored together such as on a removable storage device.

To setup Pulsar in portable mode download the relevant package and extract it to your removable storage.

Portable Notes

• The .pulsar directory must be writeable
• You can move an existing .pulsar directory to your portable device
• Pulsar can also store its Electron user data in your .pulsar directory - just create a subdirectory called electronUserData inside .pulsar
• Alternatively you can set the ATOM_HOME environment 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 Pulsar from Source

The Hacking the Core section of the launch 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:

$ pulsar -p config set strict-ssl false

Using a Proxy?

If you are using a HTTP(S) proxy you can configure ppm to use it by running:

$ pulsar -p config set https-proxy <YOUR_PROXY_ADDRESS>

You can run pulsar -p config get https-proxy to verify it has been set correctly.

Pulsar Basics

Now that Pulsar is installed on your system, let's fire it up, configure it and get acquainted with the editor.

When you launch Pulsar for the first time, you should get a screen that looks like this:

This is the Pulsar 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 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 Pulsar, 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 LNX: Ctrl+Shift+P - MAC: Cmd+Shift+P - WIN: Ctrl+Shift+P to demonstrate how to run a command and tabbed sections where necessary where instructions for different platforms may differ.

If you have customized your Pulsar 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 Pulsar. Instead of clicking around all the application menus to look for something, you can press LNX/WIN: Ctrl+Shift+P - MAC: Cmd+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 key strokes 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

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

To open the Settings View, you can:

• Use the LNX: Edit > Preferences - MAC: Pulsar > Preferences - WIN: File > Settings menu item in the menu bar
• Search for settings-view:open in the Command Palette
• Use the LNX/WIN: Ctrl+, - MAC: Cmd+, keybinding.

Changing the Theme

The Settings View also lets you change the themes for Pulsar. Pulsar ships with 4 different UI themes, dark and light variants of the Pulsar 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 the Pulsar Package Repository 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 Pulsar. You can do it by choosing File > Open from the menu bar or by pressing

LNX/WIN: Ctrl+O - MAC: Cmd+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 Pulsar is from the command line using the pulsar command.

Note

Install Shell Commands on macOS

The Pulsar menu has an item named "Install Shell Commands" which installs the pulsar and ppm commands if Pulsar wasn't able to install them itself on a macOS system.

On Linux commands are installed automatically as a part of Pulsar's installation process. Windows requires the path to be exposed manually by the user at this time.

You can run the pulsar command with one or more file paths to open up those files in Pulsar.

$ pulsar --help
> Pulsar Editor v1.100.0

> Usage: pulsar [options] [path ...]

> One or more paths to files or folders may be specified. If there is an
> existing Pulsar 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 pulsar [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$'
getting-started/sections/pulsar-basics.md:130:##### Opening a File

and then jump to the beginning of that line by appending a colon and the line number to the file path:

$ pulsar getting-started/sections/pulsar-basics.md:130

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'
getting-started/sections/pulsar-basics.md.md:150:722
$ pulsar getting-started/sections/pulsar-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 Pulsar Package Repository. There are a lot of packages that emulate popular styles.

Opening Directories

You can open any number of directories from the command line by passing their paths to the pulsar command line tool. For example, you could run the command pulsar ./hopes ./dreams to open both the hopes and the dreams directories at the same time.

When you open Pulsar 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.

Note

Pulsar Packages

Like many parts of Pulsar, the Tree View is not built directly into the editor, but is its own standalone package that is shipped with Pulsar by default. Packages that are bundled with Pulsar are referred to as Core packages. Ones that aren't bundled with Pulsar are referred to as Community packages.

You can find the source code to the Tree View on GitHub at https://github.com/pulsar-edit/tree-view.

This is one of the interesting things about Pulsar. 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 Pulsar, you can easily find and open any file within that project.

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.

Tip

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:

1. Lowercase the first word
2. Capitalize the first letter in all other words
3. Remove the spaces

So "Ignored Names" becomes "ignoredNames".

Summary

You should now have a basic understanding of what Pulsar 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.