Skip to content

Commit a03c42b

Browse files
syndbgsyndbg
committed
Re-structure README.md to be easier to read
* Extract "how it works" to HOW_IT_WORKS.md * Extract "advanced config" to ADVANCED_CONFIGURATION.md * Extract "installation" to INSTALL.md * Move Homebrew installation instructions from "advanced config" to INSTALL.md
1 parent a563758 commit a03c42b

File tree

5 files changed

+241
-265
lines changed

5 files changed

+241
-265
lines changed

‎ADVANCED_CONFIGURATION.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Advanced Configuration
2+
3+
For hobbyists this might be interesting.
4+
5+
`goenv init` is the only command that crosses the line of loading
6+
extra commands into your shell. Coming from rvm, some of you might be
7+
opposed to this idea. Here's what `goenv init` actually does:
8+
9+
1. **Sets up your shims path.** This is the only requirement for goenv to
10+
function properly. You can do this by hand by prepending
11+
`~/.goenv/shims` to your `$PATH`.
12+
13+
2. **Installs autocompletion.** This is entirely optional but pretty
14+
useful. Sourcing `~/.goenv/completions/goenv.bash` will set that
15+
up. There is also a `~/.goenv/completions/goenv.zsh` for Zsh
16+
users.
17+
18+
3. **Rehashes shims.** From time to time you'll need to rebuild your
19+
shim files. Doing this on init makes sure everything is up to
20+
date. You can always run `goenv rehash` manually.
21+
22+
4. **Installs the sh dispatcher.** This bit is also optional, but allows
23+
goenv and plugins to change variables in your current shell, making
24+
commands like `goenv shell` possible. The sh dispatcher doesn't do
25+
anything crazy like override `cd` or hack your shell prompt, but if
26+
for some reason you need `goenv` to be a real script rather than a
27+
shell function, you can safely skip it.
28+
29+
To see exactly what happens under the hood for yourself, run `goenv init -`.

‎CHANGELOG.md

+2
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,8 @@ Introducing breaking changes under a feature flag can be ok in some cases where
118118
; Ref: https://github.com/syndbg/goenv/pull/62
119119
* Changed `goenv uninstall <version>`'s to fail regardless whether `--force` or `-f` is used when version is not installed. This also means that `before_uninstall` hooks won't be triggered.
120120
; Ref: https://github.com/syndbg/goenv/pull/62
121+
* Changed the `README.md` to be easier to navigate and read by extracting "how it works" to HOW_IT_WORKS.md, "advanced config" to ADVANCED_CONFIGURATION.md, "installation" to INSTALL.md, move Homebrew installation instructions from "advanced config" to INSTALL.md.
122+
; Ref: https://github.com/syndbg/goenv/pull/62
121123

122124
### Removed
123125

‎HOW_IT_WORKS.md

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# How It Works
2+
3+
At a high level, goenv intercepts Go commands using shim
4+
executables injected into your `PATH`, determines which Go version
5+
has been specified by your application, and passes your commands along
6+
to the correct Go installation.
7+
8+
## Understanding PATH
9+
10+
When you run all the variety of Go commands using `go`, your operating system
11+
searches through a list of directories to find an executable file with
12+
that name. This list of directories lives in an environment variable
13+
called `PATH`, with each directory in the list separated by a colon:
14+
15+
/usr/local/bin:/usr/bin:/bin
16+
17+
Directories in `PATH` are searched from left to right, so a matching
18+
executable in a directory at the beginning of the list takes
19+
precedence over another one at the end. In this example, the
20+
`/usr/local/bin` directory will be searched first, then `/usr/bin`,
21+
then `/bin`.
22+
23+
## Understanding Shims
24+
25+
goenv works by inserting a directory of _shims_ at the front of your
26+
`PATH`:
27+
28+
~/.goenv/shims:/usr/local/bin:/usr/bin:/bin
29+
30+
Through a process called _rehashing_, goenv maintains shims in that
31+
directory to match every `go` command across every installed version
32+
of Go.
33+
34+
Shims are lightweight executables that simply pass your command along
35+
to goenv. So with goenv installed, when you run `go` your
36+
operating system will do the following:
37+
38+
* Search your `PATH` for an executable file named `go`
39+
* Find the goenv shim named `go` at the beginning of your `PATH`
40+
* Run the shim named `go`, which in turn passes the command along to
41+
goenv
42+
43+
## Choosing the Go Version
44+
45+
When you execute a shim, goenv determines which Go version to use by
46+
reading it from the following sources, in this order:
47+
48+
1. The `GOENV_VERSION` environment variable (if specified). You can use
49+
the [`goenv shell`](https://github.com/syndbg/goenv/blob/master/COMMANDS.md#goenv-shell) command to set this environment
50+
variable in your current shell session.
51+
52+
2. The application-specific `.go-version` file in the current
53+
directory (if present). You can modify the current directory's
54+
`.go-version` file with the [`goenv local`](https://github.com/syndbg/goenv/blob/master/COMMANDS.md#goenv-local)
55+
command.
56+
57+
3. The first `.go-version` file found (if any) by searching each parent
58+
directory, until reaching the root of your filesystem.
59+
60+
4. The global `~/.goenv/version` file. You can modify this file using
61+
the [`goenv global`](https://github.com/syndbg/goenv/blob/master/COMMANDS.md#goenv-global) command. If the global version
62+
file is not present, goenv assumes you want to use the "system"
63+
Go. (In other words, whatever version would run if goenv isn't present in
64+
`PATH`.)
65+
66+
**NOTE:** You can activate multiple versions at the same time, including multiple
67+
versions of Go simultaneously or per project.
68+
69+
## Locating the Go Installation
70+
71+
Once goenv has determined which version of Go your application has
72+
specified, it passes the command along to the corresponding Go
73+
installation.
74+
75+
Each Go version is installed into its own directory under
76+
`~/.goenv/versions`.
77+
78+
For example, you might have these versions installed:
79+
80+
* `~/.goenv/versions/1.6.1/`
81+
* `~/.goenv/versions/1.6.2/`
82+
83+
As far as goenv is concerned, version names are simply the directories in
84+
`~/.goenv/versions`.
85+

‎INSTALL.md

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Installation
2+
3+
## Basic GitHub Checkout
4+
5+
This will get you going with the latest version of goenv and make it
6+
easy to fork and contribute any changes back upstream.
7+
8+
1. **Check out goenv where you want it installed.**
9+
A good place to choose is `$HOME/.goenv` (but you can install it somewhere else).
10+
11+
$ git clone https://github.com/syndbg/goenv.git ~/.goenv
12+
13+
14+
2. **Define environment variable `GOENV_ROOT`** to point to the path where
15+
goenv repo is cloned and add `$GOENV_ROOT/bin` to your `$PATH` for access
16+
to the `goenv` command-line utility.
17+
18+
$ echo 'export GOENV_ROOT="$HOME/.goenv"' >> ~/.bash_profile
19+
$ echo 'export PATH="$GOENV_ROOT/bin:$PATH"' >> ~/.bash_profile
20+
21+
**Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`.
22+
**Ubuntu note**: Modify your `~/.bashrc` file instead of `~/.bash_profile`.
23+
24+
3. **Add `goenv init` to your shell** to enable shims and autocompletion.
25+
Please make sure `eval "$(goenv init -)"` is placed toward the end of the shell
26+
configuration file since it manipulates `PATH` during the initialization.
27+
28+
$ echo 'eval "$(goenv init -)"' >> ~/.bash_profile
29+
30+
**Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`.
31+
**Ubuntu note**: Modify your `~/.bashrc` file instead of `~/.bash_profile`.
32+
33+
**General warning**: There are some systems where the `BASH_ENV` variable is configured
34+
to point to `.bashrc`. On such systems you should almost certainly put the abovementioned line
35+
`eval "$(goenv init -)` into `.bash_profile`, and **not** into `.bashrc`. Otherwise you
36+
may observe strange behaviour, such as `goenv` getting into an infinite loop.
37+
See pyenv's issue [#264](https://github.com/yyuu/pyenv/issues/264) for details.
38+
39+
4. **Restart your shell so the path changes take effect.**
40+
You can now begin using goenv.
41+
42+
$ exec $SHELL
43+
44+
5. **Install Go versions into `$GOENV_ROOT/versions`.**
45+
For example, to download and install Go 1.6.2, run:
46+
47+
$ goenv install 1.6.2
48+
49+
**NOTE:** It downloads and places the prebuilt Go binaries provided by Google.
50+
51+
## Homebrew on Mac OS X
52+
53+
You can also install goenv using the [Homebrew](http://brew.sh)
54+
package manager for Mac OS X.
55+
56+
$ brew update
57+
$ brew install goenv
58+
59+
To upgrade goenv in the future, use `upgrade` instead of `install`.
60+
61+
After installation, you'll need to add `eval "$(goenv init -)"` to your profile (as stated in the caveats displayed by Homebrew — to display them again, use `brew info goenv`). You only need to add that to your profile once.
62+
63+
Then follow the rest of the post-installation steps under "Basic GitHub Checkout" above, starting with #4 ("restart your shell so the path changes take effect").
64+
65+
## Upgrading
66+
67+
If you've installed goenv using the instructions above, you can
68+
upgrade your installation at any time using git.
69+
70+
To upgrade to the latest development version of goenv, use `git pull`:
71+
72+
$ cd ~/.goenv
73+
$ git pull
74+
75+
To upgrade to a specific release of goenv, check out the corresponding tag:
76+
77+
$ cd ~/.goenv
78+
$ git fetch
79+
$ git tag
80+
v20160417
81+
$ git checkout v20160417
82+
83+
## Uninstalling goenv
84+
85+
The simplicity of goenv makes it easy to temporarily disable it, or
86+
uninstall from the system.
87+
88+
1. To **disable** goenv managing your Go versions, simply remove the
89+
`goenv init` line from your shell startup configuration. This will
90+
remove goenv shims directory from PATH, and future invocations like
91+
`goenv` will execute the system Go version, as before goenv.
92+
93+
`goenv` will still be accessible on the command line, but your Go
94+
apps won't be affected by version switching.
95+
96+
2. To completely **uninstall** goenv, perform step (1) and then remove
97+
its root directory. This will **delete all Go versions** that were
98+
installed under `` `goenv root`/versions/ `` directory:
99+
100+
rm -rf `goenv root`
101+
102+
If you've installed goenv using a package manager, as a final step
103+
perform the goenv package removal. For instance, for Homebrew:
104+
105+
brew uninstall goenv
106+
107+
## Uninstalling Go Versions
108+
109+
As time goes on, you will accumulate Go versions in your
110+
`~/.goenv/versions` directory.
111+
112+
To remove old Go versions, `goenv uninstall` command to automate
113+
the removal process.
114+
115+
Alternatively, simply `rm -rf` the directory of the version you want
116+
to remove. You can find the directory of a particular Go version
117+
with the `goenv prefix` command, e.g. `goenv prefix 1.6.2`.

0 commit comments

Comments
 (0)