README.md (7027B)
1 This is go-mode, the Emacs mode for editing Go code. 2 3 It is a complete rewrite of the go-mode that shipped with Go 1.0.3 and 4 before, and was part of Go 1.1 until Go 1.3. Beginning with Go 1.4, 5 editor integration will not be part of the Go distribution anymore, 6 making this repository the canonical place for go-mode. 7 8 9 # Features 10 11 In addition to normal features, such as fontification and indentation, 12 and close integration with familiar Emacs functionality (for example 13 syntax-based navigation like `beginning-of-defun`), go-mode comes with 14 the following extra features to provide an improved experience: 15 16 - Integration with `gofmt` by providing a command of the same name, 17 and `gofmt-before-save`, which can be used in a hook to format Go 18 buffers before saving them. 19 - Setting the `gofmt-command` variable also allows using 20 `goimports`. 21 - Setting the `gofmt-args` variable with a list of arguments allows 22 using e.g. `gofmt -s`. 23 - Integration with `godoc` via the functions `godoc` and 24 `godoc-at-point`. 25 - Integration with the Playground 26 - `go-play-buffer` and `go-play-region` to send code to the 27 Playground 28 - `go-download-play` to download a Playground entry into a new 29 buffer 30 - Managing imports 31 - A function for jumping to the file's imports (`go-goto-imports` - 32 `C-c C-f i`) 33 - A function for adding imports, including tab completion 34 (`go-import-add`, bound to `C-c C-a`) 35 - A function for removing or commenting unused imports 36 (`go-remove-unused-imports`) 37 - It is recommended that you use `goimports` or the 38 `organize-imports` feature of `gopls` to manage 39 adding/removing/organizing imports automatically. 40 - Integration with godef 41 - `godef-describe` (`C-c C-d`) to describe expressions 42 - `godef-jump` (`C-c C-j`) and `godef-jump-other-window` (`C-x 4 C-c 43 C-j`) to jump to declarations 44 - This requires you to install godef via `go get 45 github.com/rogpeppe/godef`. 46 - Basic support for imenu (functions and variables) 47 - Built-in support for displaying code coverage as calculated by `go 48 test` (`go-coverage`) 49 - Several functions for jumping to and manipulating the individual 50 parts of function signatures. These functions support anonymous 51 functions, but are smart enough to skip them when required (e.g. 52 when jumping to a method receiver or docstring.) 53 - Jump to the argument list (`go-goto-arguments` - `C-c C-f a`) 54 - Jump to the docstring, create it if it does not exist yet 55 (`go-goto-docstring` - `C-c C-f d`). 56 - Jump to the function keyword (`go-goto-function` - `C-c C-f f`) 57 - Jump to the function name (`go-goto-function-name` - `C-c C-f n`) 58 - Jump to the return values (`go-goto-return-values` - `C-c C-f r`) 59 - Jump to the method receiver, adding a pair of parentheses if no 60 method receiver exists (`go-goto-method-receiver` - `C-c C-f m`). 61 62 All of these functions accept a prefix argument (`C-u`), causing 63 them to skip anonymous functions. 64 - GOPATH detection – the function `go-guess-gopath` will guess a 65 suitable value for GOPATH, based on gb or wgo projects, Godeps and 66 src folders for plain GOPATH workspaces. The command 67 `go-set-project` uses the return value of `go-guess-gopath` to set 68 the GOPATH environment variable. 69 70 You can either call `go-set-project` manually, or integrate it with 71 Projectile's project switching hooks, or any other means of 72 switching projects you may employ. 73 74 # Installation 75 76 ## MELPA 77 78 The recommended way of installing go-mode is via 79 [ELPA](http://www.emacswiki.org/emacs/ELPA), the Emacs package 80 manager, and the 81 [MELPA Stable repository](http://emacsredux.com/blog/2014/05/16/melpa-stable/), which provides 82 an up-to-date version of go-mode. 83 84 If you're not familiar with ELPA yet, consider reading 85 [this guide](http://ergoemacs.org/emacs/emacs_package_system.html). 86 87 ## Manual 88 89 90 91 To install go-mode manually, check out the `go-mode.el` repository in 92 a directory of your choice, add it to your load path and configure 93 Emacs to automatically load it when opening a `.go` file: 94 95 (add-to-list 'load-path "/place/where/you/put/it/") 96 (autoload 'go-mode "go-mode" nil t) 97 (add-to-list 'auto-mode-alist '("\\.go\\'" . go-mode)) 98 99 Either evaluate the statements with `C-x C-e`, or restart Emacs. 100 101 # Other extensions 102 103 There are several third party extensions that can enhance the Go 104 experience in Emacs. 105 106 ## Gopls integration 107 108 [Gopls](https://github.com/golang/tools/blob/master/gopls/README.md) 109 is the official language server protocol (lsp) implementation provided 110 by the Go team. It is intended to replace the existing third party 111 tools for code formatting (gofmt), automatic imports (goimports), code 112 navigation (godef/guru), type and function descriptions (godoc/godef), 113 error checking, auto completion (gocode), variable and type renaming 114 (rename), and more. Once gopls is stable the older tools will no 115 longer be supported. 116 117 Gopls is a supported backend for 118 [lsp-mode](https://github.com/emacs-lsp/lsp-mode). It will be used 119 automatically by lsp-mode if `gopls` is found in your PATH. You can 120 install gopls via: `go get golang.org/x/tools/gopls@latest`. To enable 121 lsp-mode for go buffers: 122 123 (add-hook 'go-mode-hook 'lsp-deferred) 124 125 126 ## Syntax/error checking 127 128 There are two ways of using flymake with Go: 129 130 1. [goflymake](https://github.com/dougm/goflymake), which internally 131 uses `go build` to capture all errors that a regular compilation would 132 also produce 133 2. [flymake-go](http://marmalade-repo.org/packages/flymake-go) for a 134 more lightweight solution that only uses `gofmt` and as such is only 135 able to catch syntax errors. Unlike goflymake, however, it does not 136 require an additional executable. 137 138 Additionally, there is 139 [flycheck](https://github.com/flycheck/flycheck), a modern replacement 140 for flymake, which comes with built-in support for Go. In addition to 141 using `go build` or `gofmt`, it also has support for `go vet`, 142 `golint` and `errcheck`. 143 144 ## Auto completion 145 146 For auto completion, take a look at 147 [gocode](https://github.com/nsf/gocode). 148 149 ## eldoc 150 151 https://github.com/syohex/emacs-go-eldoc provides eldoc functionality 152 for go-mode. 153 154 ## Snippets 155 156 I maintain a set of YASnippet snippets for go-mode at 157 https://github.com/dominikh/yasnippet-go 158 159 ## Integration with errcheck 160 161 https://github.com/dominikh/go-errcheck.el provides integration with 162 [errcheck](https://github.com/kisielk/errcheck). 163 164 # Stability 165 166 go-mode.el has regular, tagged releases and is part of the MELPA 167 Stable repository. These tagged releases are intended to provide a 168 stable experience. APIs added in tagged releases will usually not be 169 removed or changed in future releases. 170 171 Changes made on the master branch, which is tracked by the normal 172 MELPA repository, however, are under active development. New APIs are 173 experimental and may be changed or removed before the next release. 174 Furthermore, there is a higher chance for bugs. 175 176 If you want a stable experience, use MELPA Stable. If you want cutting 177 edge features, or "beta-test" future releases, use MELPA or the master 178 branch.