@@ -13,7 +13,9 @@ documents that may become out-of-date, and when maintained properly, should
1313provide a cohesive and discoverable interface for common project tasks.
1414
1515For 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
3133The ` ./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
4851No. 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.
6470The ` ./go ` script framework makes it easy to provide a uniform and easy-to-use
6571project maintenance interface that fits your project perfectly regardless of the
6672mix 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 ] ,
6974scripts using the framework will evolve and stay healthy along with the rest of
7075your project sources, which makes everyone working with the code less frustrated
7176and 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+
7380This 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
8693and sizes.
8794
8895The 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
100110Yes. 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
112124Of 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 ]
120128is 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
123144The ` ./go ` script framework isn't intended to replace all those other tools and
124145languages, 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
146167Even if ` ./go init ` tells the user "go to this website and install this other
147168thing", 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
155177The 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
184207cases 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
194221To 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```
201227GNU 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
213239First you'll need a copy of this framework available in your project sources.
214240The 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
228258If you'd prefer to download a copy of the framework and check it into your
229259sources, 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
447479The ` 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
461494If you'd care to contribute to this project, be it code fixes, documentation
462495updates, 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
467500suitable version of Bash already installed and available. If not, use your
468501system'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] [ ]
472504distributions 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