Sometimes it's important to be able to pair-program remotely. If both participants are comfortable with vim and tmux, then you can use something like tmate along with any voice-chat solution and you're away (I like Luan's vim and tmux configs for this). However, not all remote pairs are comfortable with vim.
This is an emacs and tmux configuration which is designed to:
- be as accessible as possible to users of IDEs like goland,
- work properly in a terminal, so we can pair over ssh,
- not leave sensitive info (copies of emails, ssh keys, etc) on your local disk.
- (so that you can use this config on a shared pairing station about as safely as you'd use webmail, etc)
This is not what I'm currently using. I've found that these days:
- I'm doing less pairing and more soloing, and
- I'm working more on my own machine, where it's safe to store local copies of email and things
...so I've switched to a configuration that's more aimed at those needs.
If you trust my script, you can do:
curl https://raw.githubusercontent.com/totherme/pairing-emacs/master/scripts/install | bash
This essentially just does the manual steps described below.
You can now start emacs in its own window with emacs
or in the
terminal with emacs -nw
. If you're starting in the terminal for any
reason other than a remote pairing session over ssh, you should
probably look into TRAMP
and the
emacs-client. They
might do what you want with less friction.
The first time you start emacs after installing this config, emacs will download some plugins for doing golang editing and so on. This will slow down your initial startup, and will display a whole bunch of compilation output. Subsequent startups will be faster.
You'll need git and a recent version of emacs. To take advantage of the golang IDE-like features you'll need go. It's recommended that you use this config with tmate for remote pairing.
# backup your existing emacs config
mv ~/.emacs.d ~/.emacs.d.backup
# get this emacs config
git clone https://github.com/totherme/pairing-emacs ~/.emacs.d
...and optionally
# get the golang tools that make this kind of thing possible
go get -u golang.org/x/tools/cmd/goimports \
github.com/rogpeppe/godef \
github.com/nsf/gocode \
github.com/dougm/goflymake
# use our tmux config
mv ~/.tmux.conf ~/.tmux.conf.backup
ln -s ~/.emacs.d/tmux.conf ~/.tmux.conf
If you don't yet know how to save a file in emacs, see Learning more about emacs below.
If you want to dive in and see all the things that are bundled and enabled here, take a look at the basic editing features, git features, and programming features enabled in our config directory. Some highlights are listed below.
- Line numbers. Every file you open will have line numbers displayed
on the left hand side. This can be useful when remote pairing so you
can talk about your code with a common reference point. If you don't
like it, switch it off with
M-x global-linum-mode
. - Tree-based undo/redo. You can "undo" with
C-/
andC-_
. For "redo" you can useC-?
andM-_
. Note thatC-?
won't work at the terminal, because on terminalsC-?
is equivalent toDEL
. If having a "redo" button in emacs doesn't surpise you then this is only of historical interest. You can read what the old world used to look like here. - You can naviate your entire undo
history, including branches
that you previously edited over the top of, using
C-x u
. - The mouse should work. Even at the terminal. Try clicking to move the cursor, or highlighting text, or activating a menu at the top of the screen.
- When editing go code, you can use
Control-Click
to introspect (usinggodef
) the thing you clicked. - There are browser-like "back" and "forward" buttons. You can use
C-x <left>
andC-x <right>
, and in the GUI they're also available in the toolbar. - Autocompletion is available for everything.
- It pops up by default for programming languages, but not for plain text.
- If you want to summon it explicitly, hit
C-c C-n
orC-c M-n
. - If you're mid-autocomplete, and want to read the docs for the
thing you're about to complete to, hit
<F1>
orC-h
- If you're mid-autocomplete, and want to read the definition of the
thing you're about to complete to, hit
C-w
- You can start a shell in emacs. Hit
C-x M-m
- There's a GUI for doing git operations. Start
it with
C-x g
- This gui has been tweaked to try to detect whether you want to use
git-duet or not. It should work right out of the box, whether
you're using git-duet or not. You can force it either way by
customizing
the
git-duet-enabled
variable. You can do this withM-x customize-variable
followed bygit-duet-enabled
. Whatever change you make will be saved for future sessions.
- This gui has been tweaked to try to detect whether you want to use
git-duet or not. It should work right out of the box, whether
you're using git-duet or not. You can force it either way by
customizing
the
- If you keep your github keys in lastpass, you can load them from within emacs.
- Avy mode. This is a way of quickly
moving the cursor around a file.
- If you quickly double-tap the
j
key, emacs will ask you for the first letter of a word. Once you've entered that letter, emacs will highlight all words beginning with that letter and ask which you want to jump to. - If you mash
j
andl
, emacs will prompt for which line you want to jump to. - If you mash
j
andw
, emacs will prompt for which internal window you want to jump to.
- If you quickly double-tap the
- Multiple-cursor
mode. If you
highlight the an instance of the word
foo
in your file, thenC->
will cause the next instance to also be highlighted, and so on. Similarly,C-<
will cause previous instances to be highlighted. Once you've highlighted all the things you want to edit, you can edit them as normal. HitC-g
to go back to just one cursor. Annoyingly, theC->
andC-<
shortcuts don't work at the terminal because the terminal doesn't distinguish betweenC-.
andC->
.
If you do M-x cua-mode
then the following windows-like keyboard
shortcuts will be enabled:
C-c
is "copy to clipboard"C-v
is "paste from clipboard"C-x
is "cut to clipboard"C-z
is "undo"- If you highlight some text and start typing, the highlighted text will be replaced with the new text that you're typing.
The tmux config included in this repository is intended to:
- Stay out of the way of the emacs shortcuts we'll need when remote pairing
- Be familiar to anyone who has experience using tmux
- Provide cool and useful features
For example, while the default (and hence very common) tmux prefix-key
is C-b
, our prefix key is C-q
. This is because C-b
is a
commonly used emacs shortcut for moving the cursor backwards, while
C-q
is an infrequently used emacs shortcut for inserting a literal
character (often a tab or control character). If you want to use this
functionality you should hit C-q C-q
, which will cause tmux to pass
a single C-q
through to emacs.
To learn more about tmux, try this free-to-read-online book. If you're used to a heavily customised tmux config, you may be interested in this list of default tmux keybindings.
<Prefix> \
is bound tosynchronize-panes
. This is useful when, for example, simultaneously managing/debugging multiple remote machines in a single cluster.
To use any of these plugins, you must install them. You can do this by
starting tmux, and hitting C-q I
. You only need to do this once --
they will be available in every tmux session on your machine
thereafter.
Features mostly provided by go-mode, which is well documented here.
- Every time you save, it will run goimports (which includes gofmt)
- Inteligent autocompletion should work as you expect. This is
provided by
company-go
and company-mode.
- It'll try to pop up when you want it, but if you want to summon it
explicitly, hit
C-c C-n
orC-c M-n
. - If you're mid-autocomplete, and want to read the docs for the
thing you're about to complete to, hit
<F1>
orC-h
- If you're mid-autocomplete, and want to read the definition of the
thing you're about to complete to, hit
C-w
- The type of whatever your cursor is over is displayed at the bottom of the screen.
- It'll try to pop up when you want it, but if you want to summon it
explicitly, hit
- Compile time errors will be highlighted in red, and underlined if your terminal supports that.
- Linter errors will be highlighted in yellow, and underlined if your terminal supports that.
- To read what error caused a given highlight, put your cursor over
the offending code, and hit
C-c C-e
. To dismiss the error, hitC-g
. - Introspection: to navigate to where something was declared or
defined, either control-click it, or put the cursor over it, and and
hit
M-.
- To run tests:
- in the current file, hit
C-x f
- in the current project, hit
C-x p
- for a coverage report, hit
C-x c
- for the current test, hit
C-x t
- to
go run
something, hitC-x x
- in the current file, hit
- There are a bunch of
snippets available for
golang
activate them by typing the abbreviation, and hitting
<TAB>
. - There are a bunch of other functions you can use with
M-x
:- ‘gofmt’
- ‘godoc’ and ‘godoc-at-point’
- ‘go-import-add’
- ‘go-remove-unused-imports’
- ‘go-goto-arguments’
- ‘go-goto-docstring’
- ‘go-goto-function’
- ‘go-goto-function-name’
- ‘go-goto-imports’
- ‘go-goto-return-values’
- ‘go-goto-method-receiver’
- ‘go-play-buffer’ and ‘go-play-region’
- ‘go-download-play’
- ‘godef-describe’ and ‘godef-jump’
- ‘go-coverage’
- ‘go-set-project’
- ‘go-reset-gopath’
- Holding
Control
and tappingg
means "STOP IT!". Anything that feels like you might hitEscape
orControl-c
in another context probably wants aControl-g
here. - The emacs help system is awesome. Hold
Control
, and taph
to activate it.- Emacs will then ask you what sort of help you want. To get help on
the things you can get help about, hit
?
.
- Emacs will then ask you what sort of help you want. To get help on
the things you can get help about, hit
C-x
means "hold control while you tap x"C-x C-c
means "hold control while you tap x, keep holding control while you tap c"C-x c
means "hold control while you tap x, then release control before tapping c"- Just as
C-
means the control key, soM-
means the alt key. The "M" stands for "meta". Back in the day, there were keyboards with an actual meta key in roughly the same place as modern alt keys.
- Open a file (or create a new file) is
C-x C-f
- Save is
C-x C-s
- You can switch between open files with
C-x b
- You can split the screen
- ...horizontally with
C-x 2
- ...vertically with
C-x 3
- you can close a split with
C-0
- you can close all splits except the current one with
C-1
- you can move from one split to another with
C-x o
- ...horizontally with
- Literally everything that you can do with any keystroke or mouse
gesture is a function which you can call directly by typing
M-x
and then the name of the function - Often the Control key does something a bit, and the Meta (alt) key
does it a lot. Sometimes sticking
C-x
on the front does it a LOT. For example:C-t
is transpose charactersM-t
is transpose wordsC-x t
is transpose lines
- Emacs is old, and lots of things have borrowed shortcuts from it
over the years. If you're a fast bash user, you can transfer some of
those skills:
C-b
andC-f
go backwards and forwardsC-p
andC-n
go to previous and next linesC-a
goes to the beginning of the lineC-e
goes to the end of the lineC-r
is "reverse search" -- searching backwards through things you typed above
Recall that C-h
activates the help system. There are many
sub-systems worth mentioning here:
C-h t
activates the emacs tutorial. It will interactively take you through learning emacs.C-h r
is for Reading the manual. This isn't a manpage, it's a whole book about emacs.- "I just did something, and something happened, and I don't know what
I did" -- we can figure it out with the help system
C-h l
will list the last 300 keystrokes you entered. Now you know what keys you pressed to do the thing you didC-h k <KEY>
will get help specifically on whatever happens when you press<KEY>
.- If one of the things you did was call a function with
M-x
, you can get help on a function withC-h f <function name>
- If you want to know what keyboard shortcuts are available right now,
hit
C-h b
The whole help system is full of hyperlinks. Click on things with your
mouse, or position the cursor over them and hit <ENTER>
. To go back
to where you came from, you can usually hit l
.