Skip to content

Commit afbe6d2

Browse files
committed
README: Change Markdown links to reference-style
Per: https://daringfireball.net/projects/markdown/syntax#link Makes the README much more readable as a plaintext document.
1 parent dd2b67b commit afbe6d2

File tree

1 file changed

+121
-86
lines changed

1 file changed

+121
-86
lines changed

README.md

Lines changed: 121 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,9 @@ documents that may become out-of-date, and when maintained properly, should
1313
provide a cohesive and discoverable interface for common project tasks.
1414

1515
For a five-minute overview of the framework, see [Mike Bland's go-script-bash
16-
lightning talk at Surge 2016](https://youtu.be/WX1vrLV9mFE?t=39m48s).
16+
lightning talk at Surge 2016][go-surge].
17+
18+
[go-surge]: https://youtu.be/WX1vrLV9mFE?t=39m48s
1719

1820
### Table of contents
1921

@@ -22,34 +24,38 @@ lightning talk at Surge 2016](https://youtu.be/WX1vrLV9mFE?t=39m48s).
2224
- [How to use this framework](#how-to-use-this-framework)
2325
- [Feedback and contributions](#feedback-and-contributions)
2426
- [Installing Bash](#installing-bash)
25-
- [Open Source](#open-source)
27+
- [Open Source](#open-source-license)
2628
- [Prior work](#prior-work)
2729

2830
### Introduction
2931
#### What's a `./go` script?
3032

3133
The `./go` script idea came from Pete Hodgson's blog posts [In Praise of the
32-
./go Script: Part
33-
I](https://www.thoughtworks.com/insights/blog/praise-go-script-part-i) and [Part
34-
II](https://www.thoughtworks.com/insights/blog/praise-go-script-part-ii). To
35-
paraphrase Pete's original idea, rather than dump project setup, development,
36-
testing, and installation/deployment commands into a `README` that tends to get
37-
stale, or rely on oral tradition to transmit project maintenance knowledge,
38-
automate these tasks by encapsulating them all inside a single script in the
39-
root directory of your project source tree, conventionally named "`go`". Then
40-
the interface to these tasks becomes something like `./go setup`, `./go test`,
41-
and `./go deploy`. Not only would this script save time for people already
42-
familiar with the project, but it smooths the learning curve, prevents common
43-
mistakes, and lowers friction for new contributors. This is as desirable a state
44-
for Open Source projects as it is for internal ones.
34+
./go Script: Part I][hodg-1] and [Part II][hodg-2]. To paraphrase Pete's
35+
original idea, rather than dump project setup, development, testing, and
36+
installation/deployment commands into a `README` that tends to get stale, or
37+
rely on oral tradition to transmit project maintenance knowledge, automate these
38+
tasks by encapsulating them all inside a single script in the root directory of
39+
your project source tree, conventionally named "`go`". Then the interface to
40+
these tasks becomes something like `./go setup`, `./go test`, and `./go deploy`.
41+
Not only would this script save time for people already familiar with the
42+
project, but it smooths the learning curve, prevents common mistakes, and lowers
43+
friction for new contributors. This is as desirable a state for Open Source
44+
projects as it is for internal ones.
45+
46+
[hodg-1]: https://www.thoughtworks.com/insights/blog/praise-go-script-part-i
47+
[hodg-2]: https://www.thoughtworks.com/insights/blog/praise-go-script-part-ii
4548

4649
#### Is this related to the Go programming language?
4750

4851
No. The `./go` script convention in general and this framework in particular are
49-
completely unrelated to the [Go programming language](https://golang.org). In
50-
fact, the actual `./go` script can be named anything. However, the [`go` command
51-
from the Go language distribution](https://golang.org/cmd/go/) encapsulates many
52-
common project functions in a similar fashion.
52+
completely unrelated to the [Go programming language][golang]. In fact, the
53+
actual `./go` script can be named anything. However, the [`go` command from the
54+
Go language distribution][golang-cmd] encapsulates many common project functions
55+
in a similar fashion.
56+
57+
[golang]: https://golang.org
58+
[golang-cmd]: https://golang.org/cmd/go/
5359

5460
#### Why write a framework?
5561

@@ -64,12 +70,13 @@ trying to avoid.
6470
The `./go` script framework makes it easy to provide a uniform and easy-to-use
6571
project maintenance interface that fits your project perfectly regardless of the
6672
mix of tools and languages, then it gets out of the way as fast as possible. The
67-
hope is that by [making the right thing the easy
68-
thing](https://mike-bland.com/2016/06/16/making-the-right-thing-the-easy-thing.html),
73+
hope is that by [making the right thing the easy thing][right-thing-easy],
6974
scripts using the framework will evolve and stay healthy along with the rest of
7075
your project sources, which makes everyone working with the code less frustrated
7176
and more productive all-around.
7277

78+
[right-thing-easy]: https://mike-bland.com/2016/06/16/making-the-right-thing-the-easy-thing.html
79+
7380
This framework accomplishes this by:
7481

7582
* encouraging modular, composable `./go` commands implemented as individual
@@ -86,39 +93,53 @@ Plus, its own tests serve as a model for testing command scripts of all shapes
8693
and sizes.
8794

8895
The inspiration for this model (and initial implementation hints) came from [Sam
89-
Stephenson's `rbenv` Ruby version manager](https://github.com/rbenv/rbenv).
96+
Stephenson's `rbenv` Ruby version manager][rbenv].
97+
98+
[rbenv]: https://github.com/rbenv/rbenv
9099

91100
#### Why Bash?
92101

93-
[It's the ultimate backstage
94-
pass!](http://www.imdb.com/title/tt0118971/quotes?item=qt1467557) It's the
95-
default shell for most mainstream UNIX-based operating systems, easily installed
96-
on other UNIX-based operating systems, and is readily available even on Windows.
102+
[It's the ultimate backstage pass!][backstage] It's the default shell for most
103+
mainstream UNIX-based operating systems, easily installed on other UNIX-based
104+
operating systems, and is readily available even on Windows.
105+
106+
[backstage]: http://www.imdb.com/title/tt0118971/quotes?item=qt1467557
97107

98108
#### Will this work on Windows?
99109

100110
Yes. It is an explicit goal to make it as easy to use the framework on Windows
101-
as possible. Since [Git for Windows](https://git-scm.com/downloads) in
102-
particular ships with Bash as part of its environment, and Bash is available
103-
within Windows 10 as part of the [Windows Subsystem for
104-
Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about) (Ubuntu on
105-
Windows), it's more likely than not that Bash is already available on a Windows
106-
developer's system. It's also available from the
107-
[MSYS2](https://msys2.github.io/) and [Cygwin](https://www.cygwin.com/)
108-
environments.
111+
as possible. Since [Git for Windows][git-win] in particular ships with Bash as
112+
part of its environment, and Bash is available within Windows 10 as part of the
113+
[Windows Subsystem for Linux][wsl] (Ubuntu on Windows), it's more likely than
114+
not that Bash is already available on a Windows developer's system. It's also
115+
available from the [MSYS2][] and [Cygwin][] environments.
116+
117+
[git-win]: https://git-scm.com/downloads
118+
[wsl]: https://msdn.microsoft.com/en-us/commandline/wsl/about
119+
[msys2]: https://msys2.github.io/
120+
[cygwin]: https://www.cygwin.com/
109121

110122
#### Why not use tool X instead?
111123

112124
Of course there are many common tools that may be used for managing project
113-
tasks. For example: [Make](https://www.gnu.org/software/make/manual/),
114-
[Rake](http://rake.rubyforge.org/), [npm](https://docs.npmjs.com/),
115-
[Gulp](http://gulpjs.com/), [Grunt](http://gruntjs.com/),
116-
[Bazel](https://www.bazel.io/), and the Go programming language's `go` tool.
117-
There are certainly more powerful scripting languages:
118-
[Perl](https://www.perl.org/), [Python](https://www.python.org/),
119-
[Ruby](https://www.ruby-lang.org/en/), and even [Node.js](https://nodejs.org/)
125+
tasks. For example: [Make][], [Rake][], [npm][], [Gulp][], [Grunt][], [Bazel][],
126+
and the Go programming language's `go` tool. There are certainly more powerful
127+
scripting languages: [Perl][], [Python][], [Ruby][], and even [Node.js][nodejs]
120128
is a possibility. There are even more powerful shells, such as the
121-
[Z-Shell](https://www.zsh.org/) and the [fish shell](https://fishshell.com/).
129+
[Z-Shell][zsh] and the [fish shell][fish].
130+
131+
[make]: https://www.gnu.org/software/make/manual/
132+
[rake]: http://rake.rubyforge.org/
133+
[npm]: https://docs.npmjs.com/
134+
[gulp]: http://gulpjs.com/
135+
[grunt]: http://gruntjs.com
136+
[bazel]: https://www.bazel.io/
137+
[perl]: https://www.perl.org/
138+
[python]: https://www.python.org/
139+
[ruby]: https://www.ruby-lang.org/en/
140+
[nodejs]: https://nodejs.org/
141+
[zsh]: https://www.zsh.org/
142+
[fish]: https://fishshell.com/
122143

123144
The `./go` script framework isn't intended to replace all those other tools and
124145
languages, but to make it easier to use each of them for what they're good for.
@@ -145,20 +166,22 @@ before being able to do anything.
145166

146167
Even if `./go init` tells the user "go to this website and install this other
147168
thing", that's still an immediate, tactile experience that triggers a reward
148-
response and invites further exploration. (Think of
149-
[Zork](https://en.wikipedia.org/wiki/Zork) and the first ["open
150-
mailbox"](http://steel.lcc.gatech.edu/~marleigh/zork/transcript.html)
151-
command.)
169+
response and invites further exploration. (Think of [Zork][] and the first
170+
["open mailbox"][zork-open] command.)
171+
172+
[zork]: https://en.wikipedia.org/wiki/Zork
173+
[zork-open]: http://steel.lcc.gatech.edu/~marleigh/zork/transcript.html
152174

153175
#### Where can I run it?
154176

155177
The real question is: Where _can't_ you run it?
156178

157-
The core framework is written 100% in
158-
[Bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29) and it's been tested
159-
under Bash 3.2, 4.2, 4.3, and 4.4 across OS X, Ubuntu Linux, Arch Linux, Alpine
160-
Linux, FreeBSD 9.3, FreeBSD 10.3, and Windows 10 (using all the environments
161-
described in the "Will this work on Windows?" section above).
179+
The core framework is written 100% in [Bash][bash-wikipedia] and it's been
180+
tested under Bash 3.2, 4.2, 4.3, and 4.4 across OS X, Ubuntu Linux, Arch Linux,
181+
Alpine Linux, FreeBSD 9.3, FreeBSD 10.3, and Windows 10 (using all the
182+
environments described in the "Will this work on Windows?" section above).
183+
184+
[bash-wikipedia]: https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29
162185

163186
#### Can I use it to write standalone programs that aren't project scripts?
164187

@@ -183,19 +206,22 @@ tab-completion enabled by `./go env` and pattern-matching via `./go glob`, the
183206
`./go test` command provides a convenient means of selecting subsets of test
184207
cases while focusing on a particular piece of behavior. (See `./go help test`.)
185208

186-
The tests are written using [Sam Stephenson's Bash Automated Testing System
187-
(BATS)](https://github.com/sstephenson/bats). Code coverage comes from [Simon
188-
Kagstrom's `kcov` code coverage tool](https://github.com/SimonKagstrom/kcov),
189-
which not only provides code coverage for Bash scripts (!!!) but can push the
190-
results to Coveralls!
209+
The tests are written using [mbland/bats, an optimized version of Sam
210+
Stephenson's Bash Automated Testing System (BATS)][mbland/bats]. Code coverage
211+
comes from [Simon Kagstrom's `kcov` code coverage tool][kcov], which not only
212+
provides code coverage for Bash scripts (!!!) but can push the results to
213+
[Coveralls][cover-gos]!
214+
215+
[mbland/bats]: https://github.com/mbland/bats
216+
[kcov]: https://github.com/SimonKagstrom/kcov
217+
[cover-gos]: https://coveralls.io/github/mbland/go-script-bash
191218

192219
### Environment setup
193220

194221
To run a `./go` script that uses this module, or to add it to your own project,
195-
you must have [Bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29)
196-
version 3.2 or greater installed on your system. Run `bash --version` to make
197-
sure Bash is in your `PATH` and is a compatible version. You should see output
198-
like this:
222+
you must have [Bash][bash-wikipedia] version 3.2 or greater installed on your
223+
system. Run `bash --version` to make sure Bash is in your `PATH` and is a
224+
compatible version. You should see output like this:
199225

200226
```
201227
GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin15)
@@ -212,9 +238,13 @@ scripts can be in any other interpreted language installed on the host system.__
212238

213239
First you'll need a copy of this framework available in your project sources.
214240
The most expedient way to bootstrap your program is to use the [`go-template`
215-
file](https://github.com/mbland/go-script-bash/blob/master/go-template) as a
216-
starting point (replacing `curl` with `wget`, `fetch`, or whichever tool you
217-
prefer):
241+
file][go-template] as a starting point (replacing [curl][] with [wget][],
242+
[fetch][], or whichever tool you prefer):
243+
244+
[go-template]: https://github.com/mbland/go-script-bash/blob/master/go-template
245+
[curl]: https://curl.haxx.se/
246+
[wget]: https://www.gnu.org/software/wget/
247+
[fetch]: https://www.freebsd.org/cgi/man.cgi?fetch(1)
218248

219249
```bash
220250
$ curl https://raw.githubusercontent.com/mbland/go-script-bash/master/go-template >./go
@@ -227,14 +257,16 @@ it into your project repository. See the `go-template` comments for details.
227257

228258
If you'd prefer to download a copy of the framework and check it into your
229259
sources, versioned archives are available from the [go-script-bash Releases
230-
page](https://github.com/mbland/go-script-bash/releases). The archives for the
231-
current release are:
260+
page][go-rel]. The archives for the current release are:
261+
262+
[go-rel]: https://github.com/mbland/go-script-bash/releases
232263

233264
- https://github.com/mbland/go-script-bash/archive/v1.3.0.tar.gz
234265
- https://github.com/mbland/go-script-bash/archive/v1.3.0.zip
235266

236-
You can also add this repository to your project as a [`Git
237-
submodule`](https://git-scm.com/book/en/v2/Git-Tools-Submodules):
267+
You can also add this repository to your project as a [Git submodule][git-sub]:
268+
269+
[git-sub]: (https://git-scm.com/book/en/v2/Git-Tools-Submodules)
238270

239271
```bash
240272
$ git submodule add https://github.com/mbland/go-script-bash <target-dir>
@@ -445,18 +477,19 @@ Read the comments from each file for more information.
445477
#### `kcov-ubuntu` module for test coverage on Linux
446478

447479
The `kcov-ubuntu` module provides the `run_kcov` function that will download and
448-
compile [kcov](https://github.com/SimonKagstrom/kcov), then run `kcov` with the
449-
original `./go` command line arguments to collect test coverage. Only available
450-
on Ubuntu Linux for now, hence the name. Run `./go modules --help kcov-ubuntu`
451-
for more information and see `scripts/test` for an example of how it may be
452-
used.
480+
compile [kcov][], then run `kcov` with the original `./go` command line
481+
arguments to collect test coverage. Only available on Ubuntu Linux for now,
482+
hence the name. Run `./go modules --help kcov-ubuntu` for more information and
483+
see `scripts/test` for an example of how it may be used.
453484

454485
### Feedback and contributions
455486

456-
Feel free to [comment on or file a new GitHub
457-
issue](https://github.com/mbland/go-script-bash/issues) or otherwise ping
458-
[@mbland](https://github.com/mbland) with any questions or comments you may
459-
have, especially if the current documentation hasn't addressed your needs.
487+
Feel free to [comment on or file a new GitHub issue][issues] or otherwise ping
488+
[@mbland][] with any questions or comments you may have, especially if the
489+
current documentation hasn't addressed your needs.
490+
491+
[issues]: https://github.com/mbland/go-script-bash/issues
492+
[@mbland]: https://github.com/mbland
460493

461494
If you'd care to contribute to this project, be it code fixes, documentation
462495
updates, or new features, please read the [CONTRIBUTING](CONTRIBUTING.md) file.
@@ -467,11 +500,9 @@ If you're using a flavor of UNIX (e.g. Linux, OS X), you likely already have a
467500
suitable version of Bash already installed and available. If not, use your
468501
system's package manager to install it.
469502

470-
On Windows, the [Git for Windows](https://git-scm.com/downloads),
471-
[MSYS2](https://msys2.github.io/) and [Cygwin](https://www.cygwin.com/)
503+
On Windows, the [Git for Windows][git-win], [MSYS2][] and [Cygwin][]
472504
distributions all ship with a version of Bash. On Windows 10, you can also use
473-
the [Windows Subsystem for
474-
Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about).
505+
the [Windows Subsystem for Linux][wsl].
475506

476507
#### Updating your `PATH` environment variable
477508

@@ -528,12 +559,16 @@ installed on your system. `get git-repo` requires `git`, naturally.
528559

529560
### Open Source License
530561

531-
This software is made available as [Open Source
532-
software](https://opensource.org/osd-annotated) under the [ISC
533-
License](https://www.isc.org/downloads/software-support-policy/isc-license/).
534-
For the text of the license, see the [LICENSE](LICENSE.md) file.
562+
This software is made available as [Open Source software][oss-def] under the
563+
[ISC License][]. For the text of the license, see the [LICENSE](LICENSE.md)
564+
file.
565+
566+
[oss-def]: https://opensource.org/osd-annotated
567+
[isc license]: https://www.isc.org/downloads/software-support-policy/isc-license/
535568

536569
### Prior work
537570

538-
This is a Bash-based alternative to the
539-
[18F/go_script](https://github.com/18F/go_script) Ruby implementation.
571+
This is a Bash-based alternative to the [18F/go_script][go-old] Ruby
572+
implementation.
573+
574+
[go-old]: https://github.com/18F/go_script

0 commit comments

Comments
 (0)