X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=README.md;h=f753d4aebac2885b8f16d97f2cc8efdf8f3a4fda;hb=cf98b7f8245e4ca28518d31147e347d35607d5d4;hp=f04cb656842ce56bbfe377f707b45ac200c0a09e;hpb=a732d03b4d9ce6b4d8592fdf680fd84791a689de;p=micro.git diff --git a/README.md b/README.md index f04cb656..f753d4ae 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ -# [![micro logo](./assets/logo.png)](https://micro-editor.github.io) +micro logo [![Build Status](https://travis-ci.org/zyedidia/micro.svg?branch=master)](https://travis-ci.org/zyedidia/micro) [![Go Report Card](https://goreportcard.com/badge/github.com/zyedidia/micro)](https://goreportcard.com/report/github.com/zyedidia/micro) -[![Join the chat at https://gitter.im/zyedidia/micro](https://badges.gitter.im/zyedidia/micro.svg)](https://gitter.im/zyedidia/micro?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +[![Release](https://img.shields.io/github/release/zyedidia/micro.svg?label=Release)](https://github.com/zyedidia/micro/releases) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/zyedidia/micro/blob/master/LICENSE) -[![Snap Status](https://build.snapcraft.io/badge/zyedidia/micro.svg)](https://build.snapcraft.io/user/zyedidia/micro) +[![Join the chat at https://gitter.im/zyedidia/micro](https://badges.gitter.im/zyedidia/micro.svg)](https://gitter.im/zyedidia/micro?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +[![Snap Status](https://snapcraft.io/micro/badge.svg)](https://snapcraft.io/micro) **micro** is a terminal-based text editor that aims to be easy to use and intuitive, while also taking advantage of the capabilities -of modern terminals. It comes as a single, batteries-included, static binary with no dependencies; you can download and use it right away. +of modern terminals. It comes as a single, batteries-included, static binary with no dependencies; you can download and use it right now! As its name indicates, micro aims to be somewhat of a successor to the nano editor by being easy to install and use. It strives to be enjoyable as a full-time editor for people who prefer to work in a terminal, or those who regularly edit files over SSH. @@ -16,29 +17,34 @@ Here is a picture of micro editing its source code. ![Screenshot](./assets/micro-solarized.png) -To see more screenshots of micro, showcasing all of the default color schemes, see [here](http://zbyedidia.webfactional.com/micro/screenshots.html). +To see more screenshots of micro, showcasing some of the default color schemes, see [here](https://micro-editor.github.io). + +You can also check out the website for Micro at https://micro-editor.github.io. ## Table of Contents - [Features](#features) - [Installation](#installation) - - [Prebuilt binaries](#prebuilt-binaries) + - [Prebuilt binaries](#pre-built-binaries) - [Package Managers](#package-managers) - [Building from source](#building-from-source) + - [Fully static binary](#fully-static-binary) - [macOS terminal](#macos-terminal) - [Linux clipboard support](#linux-clipboard-support) - [Colors and syntax highlighting](#colors-and-syntax-highlighting) - - [Plan9, Cygwin](#plan9-cygwin) + - [Cygwin, Mingw, Plan9](#cygwin-mingw-plan9) - [Usage](#usage) - [Documentation and Help](#documentation-and-help) - [Contributing](#contributing) +- - - + ## Features - Easy to use and install. - No dependencies or external files are needed — just the binary you can download further down the page. - Multiple cursors. -- Common keybindings (Ctrl+S, Ctrl+C, Ctrl+V, Ctrl+Z, …). +- Common keybindings (Ctrl-s, Ctrl-c, Ctrl-v, Ctrl-z, …). - Keybindings can be rebound to your liking. - Sane defaults. - You shouldn't have to configure much out of the box (and it is extremely easy to configure). @@ -47,148 +53,187 @@ To see more screenshots of micro, showcasing all of the default color schemes, s - Extremely good mouse support. - This means mouse dragging to create a selection, double click to select by word, and triple click to select by line. - Cross-platform (it should work on all the platforms Go runs on). - - Note that while Windows is supported, there are still some bugs that need to be worked out. + - Note that while Windows is supported Mingw/Cygwin is not (see below). - Plugin system (plugins are written in Lua). - - micro has a built-in plugin manager to automatically install, remove, and update all your plugins. + - micro has a built-in plugin manager to automatically install, remove, and update plugins. +- Built-in diff gutter. +- Simple autocompletion. - Persistent undo. -- Automatic linting and error notifications -- Syntax highlighting for over [90 languages](runtime/syntax). +- Automatic linting and error notifications. +- Syntax highlighting for over [130 languages](runtime/syntax). - Color scheme support. - By default, micro comes with 16, 256, and true color themes. - True color support (set the `MICRO_TRUECOLOR` environment variable to 1 to enable it). -- Snippets. - - The snippet plugin can be installed with `> plugin install snippets`. - Copy and paste with the system clipboard. - Small and simple. - Easily configurable. - Macros. - Common editor features such as undo/redo, line numbers, Unicode support, soft wrapping, … -Although not yet implemented, I hope to add more features such as autocompletion ([#174](https://github.com/zyedidia/micro/issues/174)) or a tree view ([#249](https://github.com/zyedidia/micro/issues/249)) in the future. - ## Installation To install micro, you can download a [prebuilt binary](https://github.com/zyedidia/micro/releases), or you can build it from source. If you want more information about ways to install micro, see this [wiki page](https://github.com/zyedidia/micro/wiki/Installing-Micro). -### Prebuilt binaries - -All you need to install micro is one file, the binary itself. It's as simple as that! +Use `micro -version` to get the version information after installing. It is only guaranteed that you are installing the most recent +stable version if you install from the prebuilt binaries, Homebrew, or Snap. -Download the binary from the [releases](https://github.com/zyedidia/micro/releases) page. +A desktop entry file and man page can be found in the [assets/packaging](https://github.com/zyedidia/micro/tree/master/assets/packaging) directory. -On that page you'll see the nightly release, which contains binaries for micro which are built every night, -and you'll see all the stable releases with the corresponding binaries. +### Pre-built binaries -If you'd like to see more information after installing micro, run `micro -version`. +Pre-built binaries are distributed with [releases](https://github.com/zyedidia/micro/releases). -### Installation script +To uninstall micro, simply remove the binary, and the configuration directory at `~/.config/micro`. -There is a script which can install micro for you by downloading the latest prebuilt binary. You can find it at . - -Then you can easily install micro: +#### Quick-install script ```bash curl https://getmic.ro | bash ``` -The script will install the micro binary to the current directory. See its [GitHub repository](https://github.com/benweissmann/getmic.ro) for more information. +The script will place the micro binary in the current directory. From there, you can move it to a directory on your path of your choosing (e.g. `sudo mv micro /usr/bin`). See its [GitHub repository](https://github.com/benweissmann/getmic.ro) for more information. -### Package managers +#### Eget -You can install micro using Homebrew on Mac: +With [Eget](https://github.com/zyedidia/eget) installed, you can easily get a pre-built binary: ``` -brew install micro +eget zyedidia/micro ``` -On Windows, you can install micro through [Chocolatey](https://chocolatey.org/) or [Scoop](https://github.com/lukesampson/scoop): +Use `--tag VERSION` to download a specific tagged version. ``` -choco install micro +eget --tag nightly zyedidia/micro # download the nightly version (compiled every day at midnight UTC) +eget --tag v2.0.8 zyedidia/micro # download version 2.0.8 rather than the latest release ``` -or +You can install `micro` by adding `--to /usr/local/bin` to the `eget` command, or move the binary manually to a directory on your `$PATH` after the download completes. + +See [Eget](https://github.com/zyedidia/eget) for more information. + +### Package managers + +You can install micro using Homebrew on Mac: ``` -scoop install micro +brew install micro ``` +**Note for Mac:** All micro keybindings use the control or alt (option) key, not the command +key. By default, macOS terminals do not forward alt key events. To fix this, please see +the section on [macOS terminals](https://github.com/zyedidia/micro#macos-terminal) further below. + On Linux, you can install micro through [snap](https://snapcraft.io/docs/core/install) ``` snap install micro --classic ``` -On OpenBSD, micro is available in the ports tree. It is also available as a binary package. +Micro is also available through other package managers on Linux such dnf, AUR, Nix, and package managers +for other operating systems. These packages are not guaranteed to be up-to-date. -``` -pkg_add -v micro -``` + + +* Linux: Available in distro-specific package managers. + * `dnf install micro` (Fedora). + * `pacman -S micro` (Arch Linux). + * `eopkg install micro` (Solus). + * See [wiki](https://github.com/zyedidia/micro/wiki/Installing-Micro) for details about CRUX, Termux. +* Windows: [Chocolatey](https://chocolatey.org) and [Scoop](https://github.com/lukesampson/scoop). + * `choco install micro`. + * `scoop install micro`. +* OpenBSD: Available in the ports tree and also available as a binary package. + * `pkd_add -v micro`. +* NetBSD, macOS, Linux, Illumos, etc. with [pkgsrc](http://www.pkgsrc.org/)-current: + * `pkg_add micro` +* macOS with [MacPorts](https://www.macports.org): + * `sudo port install micro` + +**Note for Linux desktop environments:** + +For interfacing with the local system clipboard, the following tools need to be installed: +* For X11 `xclip` or `xsel` +* For [Wayland](https://wayland.freedesktop.org/) `wl-clipboard` + +Without these tools installed, micro will use an internal clipboard for copy and paste, but it won't be accessible to external applications. ### Building from source If your operating system does not have a binary release, but does run Go, you can build from source. -Make sure that you have Go version 1.5 or greater; Go 1.4 will only work if your version supports cgo. +Make sure that you have Go version 1.16 or greater and Go modules are enabled. ``` -go get -d github.com/zyedidia/micro/cmd/micro -cd $GOPATH/src/github.com/zyedidia/micro -make install +git clone https://github.com/zyedidia/micro +cd micro +make build +sudo mv micro /usr/local/bin # optional ``` -The binary will then be installed to `$GOPATH/bin` (or your `$GOBIN`). +The binary will be placed in the current directory and can be moved to +anywhere you like (for example `/usr/local/bin`). -Please make sure that when you are working with micro's code, you are working on your `GOPATH`. +The command `make install` will install the binary to `$GOPATH/bin` or `$GOBIN`. -You can install directly with `go get` (`go get -u github.com/zyedidia/micro/cmd/micro`) but this is not recommended because it doesn't build micro with version information which is useful for the plugin manager. +You can install directly with `go get` (`go get github.com/zyedidia/micro/cmd/micro`) but this isn't +recommended because it doesn't build micro with version information (necessary for the plugin manager), +and doesn't disable debug mode. -### macOS terminal +### Fully static binary -If you are using macOS, you should consider using [iTerm2](http://iterm2.com/) instead of the default terminal (Terminal.app). The iTerm2 terminal has much better mouse support as well as better handling of key events. For best keybinding behavior, choose `xterm defaults` under `Preferences->Profiles->Keys->Load Preset`. The newest versions also support true color. +By default, the micro binary will dynamically link with core system libraries (this is generally +recommended for security and portability). However, there is a fully static prebuilt binary that +is provided for amd64 as `linux-static.tar.gz`, and to build a fully static binary from source, run -### Linux clipboard support +``` +CGO_ENABLED=0 make build +``` -On Linux, clipboard support requires the `xclip` or `xsel` commands to be installed. +### macOS terminal -For Ubuntu: +If you are using macOS, you should consider using [iTerm2](http://iterm2.com/) instead of the default terminal (Terminal.app). The iTerm2 terminal has much better mouse support as well as better handling of key events. For best keybinding behavior, choose `xterm defaults` under `Preferences->Profiles->Keys->Presets...`, and select `Esc+` for `Left Option Key` in the same menu. The newest versions also support true color. -```sh -sudo apt-get install xclip -``` - -If you don't have `xclip` or `xsel`, micro will use an internal clipboard for copy and paste, but it won't work with external applications. +If you still insist on using the default Mac terminal, be sure to set `Use Option key as Meta key` under +`Preferences->Profiles->Keyboard` to use option as alt. ### Colors and syntax highlighting If you open micro and it doesn't seem like syntax highlighting is working, this is probably because you are using a terminal which does not support 256 color mode. Try changing the color scheme to `simple` -by pressing Ctrl+E in micro and typing `set colorscheme simple`. +by pressing Ctrl-e in micro and typing `set colorscheme simple`. If you are using the default Ubuntu terminal, to enable 256 make sure your `TERM` variable is set to `xterm-256color`. Many of the Windows terminals don't support more than 16 colors, which means that micro's default color scheme won't look very good. You can either set -the color scheme to `simple`, or download a better terminal emulator, like -mintty. +the color scheme to `simple`, or download and configure a better terminal emulator +than the Windows default. + +### Cygwin, Mingw, Plan9 + +Cygwin, Mingw, and Plan9 are unfortunately not officially supported. In Cygwin and Mingw, micro will often work when run using +the `winpty` utility: -### Plan9, Cygwin +``` +winpty micro.exe ... +``` -Please note that micro uses the amazing [tcell library](https://github.com/gdamore/tcell), but this +Micro uses the amazing [tcell library](https://github.com/gdamore/tcell), but this means that micro is restricted to the platforms tcell supports. As a result, micro does not support -Plan9, and Cygwin (although this may change in the future). micro also doesn't support NaCl (which is deprecated anyway). +Plan9, and Cygwin (although this may change in the future). Micro also doesn't support NaCl (which is deprecated anyway). ## Usage -Once you have built the editor, simply start it by running `micro path/to/file.txt` or simply `micro` to open an empty buffer. +Once you have built the editor, start it by running `micro path/to/file.txt` or `micro` to open an empty buffer. micro also supports creating buffers from `stdin`: ```sh -ifconfig | micro +ip a | micro ``` You can move the cursor around with the arrow keys and mouse. @@ -199,7 +244,7 @@ click to enable line selection. ## Documentation and Help -micro has a built-in help system which you can access by pressing Ctrl+E and typing `help`. Additionally, you can +micro has a built-in help system which you can access by pressing Ctrl-e and typing `help`. Additionally, you can view the help files here: - [main help](https://github.com/zyedidia/micro/tree/master/runtime/help/help.md) @@ -212,6 +257,8 @@ view the help files here: I also recommend reading the [tutorial](https://github.com/zyedidia/micro/tree/master/runtime/help/tutorial.md) for a brief introduction to the more powerful configuration features micro offers. +There is also an unofficial Discord, which you can join at https://discord.gg/nhWR6armnR. + ## Contributing If you find any bugs, please report them! I am also happy to accept pull requests from anyone. @@ -219,4 +266,6 @@ If you find any bugs, please report them! I am also happy to accept pull request You can use the [GitHub issue tracker](https://github.com/zyedidia/micro/issues) to report bugs, ask questions, or suggest new features. -For a more informal setting to discuss the editor, you can join the [Gitter chat](https://gitter.im/zyedidia/micro). +For a more informal setting to discuss the editor, you can join the [Gitter chat](https://gitter.im/zyedidia/micro) or the [Discord](https://discord.gg/nhWR6armnR). You can also use the [Discussions](https://github.com/zyedidia/micro/discussions) section on Github for a forum-like setting or for Q&A. + +Sometimes I am unresponsive, and I apologize! If that happens, please ping me.