A short introduction to margo
Posted 2018/09/30 19:00

Given the present absence of proper documentation, this post aims to be a short, but hopefully adequate introduction to margo and its relation to GoSublime.

The gist of it is that GoSublime is moving towards being only a UI that talks to the margo.sublime process — communicating all the editor actions like view updated, view saved, show auto-completions, etc. and rendering the result in the editor.

Configuring margo/GoSublime

To configure margo, you edit the package called margo located at $SublimeTextPackages/User/GoSublime/src/margo.
If you press ctrl+.,ctrl+x or super+.,super+x on Mac, GoSublime will open it for you.
If the package doesn't exist, it will be created using the extension example as base.

If you read that file, you will see a call to m.Use(...) with a list of objects. These objects are called reducers and they provide all the functionality available in GoSublime. e.g. code fmt'ting when you save a .go file or press ctrl+.,ctrl+f.

For the most part this is also how you configure GoSublime now — just edit that file and save it. After you save a file in the margo package (by default, margo.go), margo will recompile itself and restart.
You can press ctrl+.,ctrl+x to open the margo package.

Most of the old settings in the GoSublime settings file are now ignored, and will be removed in the ftuure. If you read the extension example, the replacement reducers are marked with comments starting with // gs:.

gofmt/goimports

To get code fmt for .go files, you need to use either the golang.GoFmt reducer or the golang.GoImports reducer. You can see them listed, but commented out here — you will need to un-comment one of them and save the file.

Installing margo/GoSublime

If you don't currently have GoSublime installed from the development branch, see /b/migrate for instructions on how to install it. The current master branch is not supported.

Useful keybindings

• ctrl+.,ctrl+x — Open the margo pbackage. Save the file to have margo automatically re-compile and restart itself.
• ctrl+.,ctrl+e — Show a list of all known linter errors in the current file and all other views. A summary of them as well as the error for the current line is shown in the status bar.
• ctrl+9 — Access the 9o command prompt. It's not a terminal, but it can run and show the output of most commands. The go command has support for linting.
• ctrl+.,ctrl+c — Access contextual user commands like go install
• ctrl+.,ctrl+t — Access test-specific user commands
• ctrl+.,ctrl+r — For command packages, run the command. For normal packages, run its tests. This key binding calls the 9o command go.replay which automatically cancels any existing invocation of the command so it can be used for running and restarting servers, etc. go.play is the same as go.replay except it does not cancel the existing invocation. Arguments passed to these commands are passed directly to the command that is run.
• ctrl+.,ctrl+d — Show all top-level declarations in the current .go file.
  • + marks exported identifiers
  • - marks un-exported identifiers
  • ~ marks identifiers in _test.go files
• ctrl+.,ctrl+l — Show all top-level declarations in the current Go package
• ctrl+.,ctrl+a — Show a list of all packages and allow browsing their top-level declarations
• ctrl+.,ctrl+o — Show a list of all packages and allow browsing their files
• ctrl+.,ctrl+m — Browse the files in the current directory and its sub-directories, recursively
• ctrl+.,ctrl+n — Create a new .go file and show some suggestions for initial content.
• ctrl+.,ctrl+g — Go to the definition of the identifier under the cursor. You can also hold ctrl+shift and left-click on an identifier.
• ctrl+.,ctrl+f — Format the current file without saving it.
• ctrl+.,ctrl+p — Add/remove packages in the current .go file.
• ctrl+.,ctrl+i — After adding a package, pressing this key binding will take you to the import that was added so you can rename it e.g. by naming it _ to import it for its side-effects.
• ctrl+.,ctrl+. — Open the command palette and show all GoSublime: commands