@@ -13,7 +13,9 @@ documents that may become out-of-date, and when maintained properly, should
13
13
provide a cohesive and discoverable interface for common project tasks.
14
14
15
15
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
17
19
18
20
### Table of contents
19
21
@@ -22,34 +24,38 @@ lightning talk at Surge 2016](https://youtu.be/WX1vrLV9mFE?t=39m48s).
22
24
- [ How to use this framework] ( #how-to-use-this-framework )
23
25
- [ Feedback and contributions] ( #feedback-and-contributions )
24
26
- [ Installing Bash] ( #installing-bash )
25
- - [ Open Source] ( #open-source )
27
+ - [ Open Source] ( #open-source-license )
26
28
- [ Prior work] ( #prior-work )
27
29
28
30
### Introduction
29
31
#### What's a ` ./go ` script?
30
32
31
33
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
45
48
46
49
#### Is this related to the Go programming language?
47
50
48
51
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/
53
59
54
60
#### Why write a framework?
55
61
@@ -64,12 +70,13 @@ trying to avoid.
64
70
The ` ./go ` script framework makes it easy to provide a uniform and easy-to-use
65
71
project maintenance interface that fits your project perfectly regardless of the
66
72
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 ] ,
69
74
scripts using the framework will evolve and stay healthy along with the rest of
70
75
your project sources, which makes everyone working with the code less frustrated
71
76
and more productive all-around.
72
77
78
+ [ right-thing-easy ] : https://mike-bland.com/2016/06/16/making-the-right-thing-the-easy-thing.html
79
+
73
80
This framework accomplishes this by:
74
81
75
82
* 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
86
93
and sizes.
87
94
88
95
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
90
99
91
100
#### Why Bash?
92
101
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
97
107
98
108
#### Will this work on Windows?
99
109
100
110
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/
109
121
110
122
#### Why not use tool X instead?
111
123
112
124
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 ]
120
128
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/
122
143
123
144
The ` ./go ` script framework isn't intended to replace all those other tools and
124
145
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.
145
166
146
167
Even if ` ./go init ` tells the user "go to this website and install this other
147
168
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
152
174
153
175
#### Where can I run it?
154
176
155
177
The real question is: Where _ can't_ you run it?
156
178
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
162
185
163
186
#### Can I use it to write standalone programs that aren't project scripts?
164
187
@@ -183,19 +206,22 @@ tab-completion enabled by `./go env` and pattern-matching via `./go glob`, the
183
206
` ./go test ` command provides a convenient means of selecting subsets of test
184
207
cases while focusing on a particular piece of behavior. (See ` ./go help test ` .)
185
208
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
191
218
192
219
### Environment setup
193
220
194
221
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:
199
225
200
226
```
201
227
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.__
212
238
213
239
First you'll need a copy of this framework available in your project sources.
214
240
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)
218
248
219
249
``` bash
220
250
$ 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.
227
257
228
258
If you'd prefer to download a copy of the framework and check it into your
229
259
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
232
263
233
264
- https://github.com/mbland/go-script-bash/archive/v1.3.0.tar.gz
234
265
- https://github.com/mbland/go-script-bash/archive/v1.3.0.zip
235
266
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)
238
270
239
271
``` bash
240
272
$ 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.
445
477
#### ` kcov-ubuntu ` module for test coverage on Linux
446
478
447
479
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.
453
484
454
485
### Feedback and contributions
455
486
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
460
493
461
494
If you'd care to contribute to this project, be it code fixes, documentation
462
495
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
467
500
suitable version of Bash already installed and available. If not, use your
468
501
system's package manager to install it.
469
502
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] [ ]
472
504
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 ] .
475
506
476
507
#### Updating your ` PATH ` environment variable
477
508
@@ -528,12 +559,16 @@ installed on your system. `get git-repo` requires `git`, naturally.
528
559
529
560
### Open Source License
530
561
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/
535
568
536
569
### Prior work
537
570
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