howzit 1.2.5
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.editorconfig +9 -0
- data/.gitignore +43 -0
- data/.rspec +2 -0
- data/.rubocop.yml +9 -0
- data/.travis.yml +7 -0
- data/.yardopts +6 -0
- data/CHANGELOG.md +10 -0
- data/Gemfile +4 -0
- data/Guardfile +23 -0
- data/LICENSE.txt +20 -0
- data/README.md +434 -0
- data/Rakefile +18 -0
- data/bin/howzit +6 -0
- data/fish/completions/bld.fish +1 -0
- data/fish/completions/fisher.fish +1 -0
- data/fish/completions/howzit.fish +3 -0
- data/fish/functions/bld.fish +11 -0
- data/howzit.gemspec +42 -0
- data/lib/.rubocop.yml +1 -0
- data/lib/howzit/buildnotes.rb +1146 -0
- data/lib/howzit/stringutils.rb +137 -0
- data/lib/howzit/version.rb +6 -0
- data/lib/howzit.rb +14 -0
- data/spec/.rubocop.yml +4 -0
- data/spec/ruby_gem_spec.rb +11 -0
- data/spec/spec_helper.rb +19 -0
- data/update_readmes.rb +13 -0
- metadata +305 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 5f2fa88b6f75dba8846894028f457fa1515d104bb41c77307bd0b22835afeed8
|
4
|
+
data.tar.gz: 64a7169ae4968d94f0193d784924a6a36bf36d3389cefdd8dc15a1d916292548
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 52e107f32837a775c115a9f2051a8347458e9194972f36fd1af42888e70d567ddc48bc51411335ad037d497c0d86abe38171f7b1064945c7b77671cb4a7a3afb
|
7
|
+
data.tar.gz: 9c67de8ad8748e365753194d59f4cbc1a73a590f0291289ab20e1558077114d531fe3b6b957d38204dfaace53e7d5e84a2c4743ee3ae33d4fa160828d97478fb
|
data/.editorconfig
ADDED
data/.gitignore
ADDED
@@ -0,0 +1,43 @@
|
|
1
|
+
# Parts of this file were adapted from
|
2
|
+
# GitHub’s collection of .gitignore file templates
|
3
|
+
# which are Copyright (c) 2016 GitHub, Inc.
|
4
|
+
# and released under the MIT License.
|
5
|
+
# For more details, visit the project page:
|
6
|
+
# https://github.com/github/gitignore
|
7
|
+
|
8
|
+
*.gem
|
9
|
+
*.rbc
|
10
|
+
/.config
|
11
|
+
/coverage/
|
12
|
+
/InstalledFiles
|
13
|
+
/pkg/
|
14
|
+
/spec/reports/
|
15
|
+
/spec/examples.txt
|
16
|
+
/test/tmp/
|
17
|
+
/test/version_tmp/
|
18
|
+
/tmp/
|
19
|
+
|
20
|
+
## Specific to RubyMotion:
|
21
|
+
.dat*
|
22
|
+
.repl_history
|
23
|
+
build/
|
24
|
+
|
25
|
+
## Documentation cache and generated files:
|
26
|
+
/.yardoc/
|
27
|
+
/_yardoc/
|
28
|
+
/doc/
|
29
|
+
/rdoc/
|
30
|
+
|
31
|
+
## Environment normalization:
|
32
|
+
/.bundle/
|
33
|
+
/vendor/bundle
|
34
|
+
/lib/bundler/man/
|
35
|
+
|
36
|
+
# for a library or gem, you might want to ignore these files since the code is
|
37
|
+
# intended to run in multiple environments; otherwise, check them in:
|
38
|
+
Gemfile.lock
|
39
|
+
.ruby-version
|
40
|
+
.ruby-gemset
|
41
|
+
|
42
|
+
# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
|
43
|
+
.rvmrc
|
data/.rspec
ADDED
data/.rubocop.yml
ADDED
data/.travis.yml
ADDED
data/.yardopts
ADDED
data/CHANGELOG.md
ADDED
@@ -0,0 +1,10 @@
|
|
1
|
+
# Change Log
|
2
|
+
|
3
|
+
All notable changes to this project will be documented in this file.
|
4
|
+
This project adheres to [Semantic Versioning](http://semver.org/).
|
5
|
+
This change log follows the conventions of
|
6
|
+
[keep a CHANGELOG](http://keepachangelog.com/).
|
7
|
+
|
8
|
+
## [Unreleased]
|
9
|
+
|
10
|
+
[Unreleased]: https://github.com/ttscoff/howzit/compare/v1.2.4...HEAD
|
data/Gemfile
ADDED
data/Guardfile
ADDED
@@ -0,0 +1,23 @@
|
|
1
|
+
scope groups: [:doc, :lint, :unit]
|
2
|
+
|
3
|
+
group :doc do
|
4
|
+
guard :yard do
|
5
|
+
watch(%r{^lib/(.+)\.rb$})
|
6
|
+
end
|
7
|
+
end
|
8
|
+
|
9
|
+
group :lint do
|
10
|
+
guard :rubocop do
|
11
|
+
watch(%r{.+\.rb$})
|
12
|
+
watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
|
13
|
+
end
|
14
|
+
end
|
15
|
+
|
16
|
+
group :unit do
|
17
|
+
guard :rspec, cmd: 'bundle exec rspec --color --format Fuubar' do
|
18
|
+
watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
|
19
|
+
watch(%r{^lib/howzit/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
|
20
|
+
watch(%r{^spec/.+_spec\.rb$})
|
21
|
+
watch('spec/spec_helper.rb') { 'spec' }
|
22
|
+
end
|
23
|
+
end
|
data/LICENSE.txt
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
The MIT License (MIT)
|
2
|
+
|
3
|
+
Copyright (c) 2022 Brett Terpstra
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
6
|
+
this software and associated documentation files (the "Software"), to deal in
|
7
|
+
the Software without restriction, including without limitation the rights to
|
8
|
+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
9
|
+
the Software, and to permit persons to whom the Software is furnished to do so,
|
10
|
+
subject to the following conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
13
|
+
copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
17
|
+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
18
|
+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
19
|
+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
20
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,434 @@
|
|
1
|
+
# Howzit
|
2
|
+
|
3
|
+
[![Gem](https://img.shields.io/gem/v/howzit.svg)](https://rubygems.org/gems/howzit)
|
4
|
+
[![GitHub license](https://img.shields.io/github/license/ttscoff/howzit.svg)](./LICENSE.txt)
|
5
|
+
[![Gemnasium](https://img.shields.io/gemnasium/ttscoff/howzit.svg)](https://gemnasium.com/ttscoff/howzit)
|
6
|
+
[![Travis](https://img.shields.io/travis/ttscoff/howzit.svg)](https://travis-ci.org/ttscoff/howzit)
|
7
|
+
[![Codecov](https://img.shields.io/codecov/c/github/ttscoff/howzit.svg)](https://codecov.io/github/ttscoff/howzit)
|
8
|
+
[![Code Climate](https://img.shields.io/codeclimate/github/ttscoff/howzit.svg)](https://codeclimate.com/github/ttscoff/howzit)
|
9
|
+
|
10
|
+
A command-line reference tool for tracking project build systems
|
11
|
+
|
12
|
+
Howzit is a tool that allows you to keep Markdown-formatted notes about a project's tools and procedures. It functions as an easy lookup for notes about a particular task, as well as a task runner to automatically execute appropriate commands.
|
13
|
+
|
14
|
+
<!--README-->
|
15
|
+
|
16
|
+
## Features
|
17
|
+
|
18
|
+
- Match topic titles with any portion of title
|
19
|
+
- Automatic pagination of output, with optional Markdown highlighting
|
20
|
+
- Use `@run()`, `@copy()`, and `@open()` to perform actions within a build notes file
|
21
|
+
- Use `@include()` to import another topic's tasks
|
22
|
+
- Use fenced code blocks to include/run embedded scripts
|
23
|
+
- Sets iTerm 2 marks on topic titles for navigation when paging is disabled
|
24
|
+
- Inside of git repositories, howzit will work from subdirectories, assuming build notes are in top level of repo
|
25
|
+
- Templates for easily including repeat tasks
|
26
|
+
- Grep topics for pattern and choose from matches
|
27
|
+
|
28
|
+
## Getting Started
|
29
|
+
|
30
|
+
Howzit is a simple, self-contained script (at least until I get stupid and make a gem out of it).
|
31
|
+
|
32
|
+
### Prerequisites
|
33
|
+
|
34
|
+
- Ruby 2.4+ (It probably works on older Rubys, but is untested prior to 2.4.1.)
|
35
|
+
- Optional: if [`bat`](https://github.com/sharkdp/bat) is available it will page with that
|
36
|
+
- Optional: [`mdless`](https://github.com/ttscoff/mdless) or [`mdcat`](https://github.com/lunaryorn/mdcat) for formatting output
|
37
|
+
|
38
|
+
### Installing
|
39
|
+
|
40
|
+
You can install `howzit` by running:
|
41
|
+
|
42
|
+
gem install howzit
|
43
|
+
|
44
|
+
## Anatomy of a Build Notes File
|
45
|
+
|
46
|
+
Howzit relies on there being a file in the current directory with a name that starts with "build" or "howzit" and an extension of `.md`, `.txt`, or `.markdown`, e.g. `buildnotes.md` or `howzit.txt`. This note contains topics such as "Build" and "Deploy" with brief notes about each topic in Markdown (or just plain text) format.
|
47
|
+
|
48
|
+
> Tip: Add "buildprivate.md" to your global gitignore (`git config --get core.excludesfile`). In a project where you don't want to share your build notes, just name the file "buildprivate.md" instead of "buildnotes.md" and it will automatically be ignored.
|
49
|
+
|
50
|
+
If there are files that match the "build*" pattern that should not be recognized as build notes by howzit, add them to `~/.config/howzit/ignore.yaml`. This file is a simple list of patterns that should be ignored when scanning for build note files. Use `(?:i)` at the beginning of a pattern to make it case insensitive.
|
51
|
+
|
52
|
+
The topics of the notes are delineated by Markdown headings, level 2 or higher, with the heading being the title of the topic. I split all of mine apart with h2s. For example, a short one from the little website I was working on yesterday:
|
53
|
+
|
54
|
+
## Build
|
55
|
+
|
56
|
+
gulp js: compiles and minifies all js to dist/js/main.min.js
|
57
|
+
|
58
|
+
gulp css: compass compile to dist/css/
|
59
|
+
|
60
|
+
gulp watch
|
61
|
+
|
62
|
+
gulp (default): [css,js]
|
63
|
+
|
64
|
+
## Deploy
|
65
|
+
|
66
|
+
gulp sync: rsync /dist/ to scoffb.local
|
67
|
+
|
68
|
+
## Package management
|
69
|
+
|
70
|
+
yarn
|
71
|
+
|
72
|
+
## Components
|
73
|
+
|
74
|
+
- UIKit
|
75
|
+
|
76
|
+
Howzit expects there to only be one header level used to split topics. Anything before the first header is ignored. If your topics use h2 (`##`), you can use a single h1 (`#`) line at the top to title the project.
|
77
|
+
|
78
|
+
### @Commands
|
79
|
+
|
80
|
+
You can include commands that can be executed by howzit. Commands start at the beginning of a line anywhere in a topic. Only one topic's commands can be run at once, but all commands in the topic will be executed when howzit is run with `-r`. Commands can include any of:
|
81
|
+
|
82
|
+
- `@run(COMMAND)`
|
83
|
+
|
84
|
+
The command in parenthesis will be executed as is from the current directory of the shell
|
85
|
+
- `@copy(TEXT)`
|
86
|
+
|
87
|
+
On macOS this will copy the text within the parenthesis to the clipboard. An easy way to offer a shortcut to a longer build command while still allowing it to be edited prior to execution.
|
88
|
+
- `@open(FILE|URL)`
|
89
|
+
|
90
|
+
Will open the file or URL using the default application for the filetype. On macOS this uses the `open` command, on Windows it uses `start`, and on Linux it uses `xdg-open`, which may require separate installation.
|
91
|
+
- `@include(TOPIC)`
|
92
|
+
|
93
|
+
Includes all tasks from another topic, matching the name (partial match allowed) and returning first match.
|
94
|
+
|
95
|
+
### Run blocks (embedded scripts)
|
96
|
+
|
97
|
+
For longer scripts you can write shell scripts and then call them with `@run(myscript.sh)`. For those in-between cases where you need a few commands but aren't motivated to create a separate file, you can use fenced code blocks with `run` as the language.
|
98
|
+
|
99
|
+
```run OPTIONAL TITLE
|
100
|
+
#!/bin/bash
|
101
|
+
# Commands...
|
102
|
+
```
|
103
|
+
|
104
|
+
The contents of the block will be written to a temporary file and executed with `/bin/sh -c`. This means that you need a hashbang at the beginning to tell the shell how to interpret the script. If no hashbang is given, the script will be executed as a `sh` script.
|
105
|
+
|
106
|
+
Example:
|
107
|
+
|
108
|
+
```run Just Testing
|
109
|
+
#!/bin/bash
|
110
|
+
echo "Just needed a few lines"
|
111
|
+
echo "To get through all these commands"
|
112
|
+
echo "Almost there!"
|
113
|
+
say "Phew, we did it."
|
114
|
+
```
|
115
|
+
|
116
|
+
Multiple blocks can be included in a topic. @commands take priority over code blocks and will be run first if they exist in the same topic.
|
117
|
+
|
118
|
+
### Variables
|
119
|
+
|
120
|
+
When running commands in a topic, you can use a double dash (`--`) in the command line (surrounded by spaces) and anything after it will be interpreted as shell arguments. These can be used in commands with `$` placeholders. `$1` represents the first argument, counting up from there. Use `$@` to pass all arguments as a shell-escaped string.
|
121
|
+
|
122
|
+
For example, the topic titled "Test" could contain an @run command with placeholders:
|
123
|
+
|
124
|
+
## Test
|
125
|
+
@run(./myscript.sh $@)
|
126
|
+
|
127
|
+
Then you would run it on the command line using:
|
128
|
+
|
129
|
+
howzit -r test -- -x "arg 1" arg2
|
130
|
+
|
131
|
+
This would execute the command as `./myscript.sh -x arg\ 1 arg2`.
|
132
|
+
|
133
|
+
Placeholders can be used in both commands and run blocks. If a placeholder doesn't have an argument supplied, it's not replaced (e.g. leaves `$2` in the command).
|
134
|
+
|
135
|
+
### Templates and metadata
|
136
|
+
|
137
|
+
You can create templates to reuse topics in multiple build note files. Create files using the same formatting as a build note in `~/.config/howzit/templates` with `.md` extensions. Name them the way you'll reference them:
|
138
|
+
|
139
|
+
~/.config/howzit/templates
|
140
|
+
- markdown.md
|
141
|
+
- ruby.md
|
142
|
+
- obj-c.md
|
143
|
+
|
144
|
+
> Use `howzit --templates` for a list of templates you've created, along with the topics they'll add when included. Just in case you make a bunch and can't remember what they're called or what they do. I was just planning ahead.
|
145
|
+
|
146
|
+
You can then include the topics from a template in any build note file using a `template:` key at the top of the file.
|
147
|
+
|
148
|
+
Howzit allows MultiMarkdown-style metadata at the top of a build notes file. These are key/value pairs separated by a colon:
|
149
|
+
|
150
|
+
template: markdown
|
151
|
+
key 1: value 1
|
152
|
+
key 2: value 2
|
153
|
+
|
154
|
+
The template key can include multiple template names separated by commas.
|
155
|
+
|
156
|
+
Additional metadata keys populate variables you can then use inside of your templates (and build notes), using `[%key]`. You can define a default value for a placeholder with `[%key:default]`.
|
157
|
+
|
158
|
+
For example, in the template `markdown.md` you could have:
|
159
|
+
|
160
|
+
### Spellcheck
|
161
|
+
|
162
|
+
Check spelling of all Markdown files in git repo.
|
163
|
+
|
164
|
+
```run
|
165
|
+
#!/bin/bash
|
166
|
+
for dir in [%dirs:.]; do
|
167
|
+
cd "$dir"
|
168
|
+
/Users/ttscoff/scripts/spellcheck.bash
|
169
|
+
cd -
|
170
|
+
done
|
171
|
+
```
|
172
|
+
|
173
|
+
Then, in a `buildnotes.md` file in your project, you could include at the top of the file:
|
174
|
+
|
175
|
+
template: markdown
|
176
|
+
dirs: . docs
|
177
|
+
|
178
|
+
# My Project...
|
179
|
+
|
180
|
+
If you only want to include certain topics from a template file, use the format `template_name[topic]` or include multiple topics separated by commas: `template_name[topic 1, topic 2]`. You can also use `*` as a wildcard, where `template_name[build*]` would include topics "Build" and "Build and Run".
|
181
|
+
|
182
|
+
If a topic in the current project's build note has an identical name to a template topic, the local topic takes precedence. This allows you to include a template but modify just a part of it by duplicating the topic title.
|
183
|
+
|
184
|
+
Templates can include other templates with a `template:` key at the top of the template.
|
185
|
+
|
186
|
+
You can define what metadata keys are required for the template using a `required:` key at the top of the template. For example, if the template `script.md` uses a placeholder `[%executable]` that can't have a default value as it's specific to each project, you can add:
|
187
|
+
|
188
|
+
required: executable
|
189
|
+
|
190
|
+
at the top of `project.md`. If the template is included in a build notes file and the `executable:` key is not defined, an error will be shown.
|
191
|
+
|
192
|
+
## Using howzit
|
193
|
+
|
194
|
+
Run `howzit` on its own to view the current folder's buildnotes.
|
195
|
+
|
196
|
+
Include a topic name to see just that topic, or no argument to display all.
|
197
|
+
|
198
|
+
howzit build
|
199
|
+
|
200
|
+
Use `-l` to list all topics.
|
201
|
+
|
202
|
+
howzit -l
|
203
|
+
|
204
|
+
Use `-r` to execute any @copy, @run, or @open commands in the given topic. Options can come after the topic argument, so to run the commands from the last topic you viewed, just hit the up arrow to load the previous command and add `-r`.
|
205
|
+
|
206
|
+
howzit build -r
|
207
|
+
|
208
|
+
Other options:
|
209
|
+
|
210
|
+
Usage: howzit [OPTIONS] [TOPIC]
|
211
|
+
|
212
|
+
Show build notes for the current project (buildnotes.md). Include a topic name to see just that topic, or no argument to display all.
|
213
|
+
|
214
|
+
Options:
|
215
|
+
-c, --create Create a skeleton build note in the current working directory
|
216
|
+
-e, --edit Edit buildnotes file in current working directory using editor.sh
|
217
|
+
--grep PATTERN Display sections matching a search pattern
|
218
|
+
-L, --list-completions List topics for completion
|
219
|
+
-l, --list List available topics
|
220
|
+
-m, --matching TYPE Topics matching type
|
221
|
+
(partial, exact, fuzzy, beginswith)
|
222
|
+
-R, --list-runnable List topics containing @ directives (verbose)
|
223
|
+
-r, --run Execute @run, @open, and/or @copy commands for given topic
|
224
|
+
-s, --select Select topic from menu
|
225
|
+
-T, --task-list List topics containing @ directives (completion-compatible)
|
226
|
+
-t, --title Output title with build notes
|
227
|
+
-q, --quiet Silence info message
|
228
|
+
--verbose Show all messages
|
229
|
+
-u, --upstream Traverse up parent directories for additional build notes
|
230
|
+
--show-code Display the content of fenced run blocks
|
231
|
+
-w, --wrap COLUMNS Wrap to specified width (default 80, 0 to disable)
|
232
|
+
--edit-config Edit configuration file using editor.sh
|
233
|
+
--title-only Output title only
|
234
|
+
--templates List available templates
|
235
|
+
--[no-]color Colorize output (default on)
|
236
|
+
--[no-]md-highlight Highlight Markdown syntax (default on), requires mdless or mdcat
|
237
|
+
--[no-]pager Paginate output (default on)
|
238
|
+
-h, --help Display this screen
|
239
|
+
-v, --version Display version number
|
240
|
+
|
241
|
+
|
242
|
+
## Configuration
|
243
|
+
|
244
|
+
Some of the command line options can be set as defaults. The first time you run `howzit`, a YAML file is written to `~/.config/howzit/howzit.yaml`. You can open it in your default editor automatically by running `howzit --edit-config`. It contains the available options:
|
245
|
+
|
246
|
+
---
|
247
|
+
:color: true
|
248
|
+
:highlight: true
|
249
|
+
:paginate: true
|
250
|
+
:wrap: 80
|
251
|
+
:output_title: false
|
252
|
+
:highlighter: auto
|
253
|
+
:pager: auto
|
254
|
+
:matching: partial
|
255
|
+
:include_upstream: false
|
256
|
+
:log_level: 1
|
257
|
+
|
258
|
+
If `:color:` is false, output will not be colored, and markdown highlighting will be bypassed.
|
259
|
+
|
260
|
+
If `:color:` is true and `:highlight:` is true, the `:highlighter:` option will be used to add Markdown highlighting.
|
261
|
+
|
262
|
+
If `:paginate:` is true, the `:pager:` option will be used to determine the tool used for pagination. If it's false and you're using iTerm, "marks" will be added to topic titles allowing keyboard navigation.
|
263
|
+
|
264
|
+
`:highlighter:` and `:pager:` can be set to `auto` (default) or a command of your choice for markdown highlighting and pagination.
|
265
|
+
|
266
|
+
`:matching:` can be "partial", "beginswith", "fuzzy" or "exact" (see below).
|
267
|
+
|
268
|
+
If `:include_upstream:` is true, build note files in parent directories will be included in addition to the current directory. Priority goes from current directory to root in descending order, so the current directory is top priority, and a build notes file in / is the lowest. Higher priority topics will not be overwritten by a duplicate topic from a lower priority note.
|
269
|
+
|
270
|
+
Set `:log_level:` to 0 for debug messages, or 3 to suppress superfluous info messages.
|
271
|
+
|
272
|
+
### Matching
|
273
|
+
|
274
|
+
All matching is case insensitive. This setting can be overridden by the `--matching TYPE` flag on the command line.
|
275
|
+
|
276
|
+
- `:matching: partial`
|
277
|
+
|
278
|
+
Partial is the default, search matches any part of the topic title.
|
279
|
+
|
280
|
+
_Example:_ `howzit other` matches 'An<mark>other</mark> Topic'.
|
281
|
+
|
282
|
+
- `:matching: beginswith`
|
283
|
+
|
284
|
+
Matches from the start of the title.
|
285
|
+
|
286
|
+
_Example:_ `howzit another` matches '<mark>Another</mark> Topic', but neither 'other' or 'topic' will.
|
287
|
+
|
288
|
+
- `:matching: fuzzy`
|
289
|
+
|
290
|
+
Matches anything containing the search characters in order, no matter what comes between them.
|
291
|
+
|
292
|
+
_Example:_ `howzit asct` matches '<mark>A</mark>nother <mark>S</mark>e<mark>c</mark><mark>t</mark>ion'
|
293
|
+
|
294
|
+
- `:matching: exact`
|
295
|
+
|
296
|
+
Case insensitive but must match the entire title.
|
297
|
+
|
298
|
+
_Example:_ Only `howzit another topic` will match 'Another Topic'
|
299
|
+
|
300
|
+
### Pager
|
301
|
+
|
302
|
+
If set to `auto`, howzit will look for pagers in this order, using the first one it finds available:
|
303
|
+
|
304
|
+
- $GIT_PAGER
|
305
|
+
- $PAGER
|
306
|
+
- bat
|
307
|
+
- less
|
308
|
+
- more
|
309
|
+
- cat
|
310
|
+
- pager
|
311
|
+
|
312
|
+
If you're defining your own, make sure to include any flags necessary to handle the output. If you're using howzit's coloring, for example, you need to specify any options needed to display ANSI escape sequences (e.g. `less -r`).
|
313
|
+
|
314
|
+
### Highlighter
|
315
|
+
|
316
|
+
If set to `auto` howzit will look for markdown highlighters in this order, using the first it finds available:
|
317
|
+
|
318
|
+
- mdcat
|
319
|
+
- mdless
|
320
|
+
|
321
|
+
If you're combining a highlighter with howzit's pagination, include any flags needed to disable the highlighter's pagination (e.g. `mdless --no-pager`).
|
322
|
+
|
323
|
+
## Shell Integration
|
324
|
+
|
325
|
+
I personally like to alias `bld` to `howzit -r`. If you define a function in your shell, you can have it default to "build" but accept an alternate argument. There's an example for Fish included, and in Bash it would be as simple as `howzit -r ${1:build}`.
|
326
|
+
|
327
|
+
For completion you can use `howzit -L` to list all topics, and `howzit -T` to list all "runnable" topics (topics containing an @directive or run block). Completion examples for Fish are included in the `fish` directory.
|
328
|
+
|
329
|
+
## Similar Projects
|
330
|
+
|
331
|
+
- [mask](https://github.com/jakedeichert/mask/)
|
332
|
+
- [maid](https://github.com/egoist/maid)
|
333
|
+
- [saku](https://github.com/kt3k/saku)
|
334
|
+
|
335
|
+
There are a few projects that tackle the same concept (a Markdown makefile). Most of them are superior task runners, so if you're looking for a `make` replacement, I recommend exploring the links above. What I like about `howzit` (and what keeps me from switching) is that it's documentation-first, and that I can display the description for each topic on the command line. The others also don't have options for listing topics or runnable tasks, so I can't use completion (or my cool script that adds available tasks to my Macbook Pro Touch Bar...). But no, I don't think `howzit` is as good an overall task runner as `mask` or `maid`.
|
336
|
+
|
337
|
+
## Roadmap
|
338
|
+
|
339
|
+
- Recognize header hierarchy, allow showing/running all sub-topics
|
340
|
+
|
341
|
+
## Author
|
342
|
+
|
343
|
+
**Brett Terpstra** - [brettterpstra.com](https://brettterpstra.com)
|
344
|
+
|
345
|
+
## License
|
346
|
+
|
347
|
+
This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
|
348
|
+
|
349
|
+
<!--END README-->
|
350
|
+
|
351
|
+
## Warranty
|
352
|
+
|
353
|
+
This software is provided "as is" and without any express or
|
354
|
+
implied warranties, including, without limitation, the implied
|
355
|
+
warranties of merchantibility and fitness for a particular
|
356
|
+
purpose.
|
357
|
+
|
358
|
+
## Documentation
|
359
|
+
|
360
|
+
- [YARD documentation][RubyDoc] is hosted by RubyDoc.info.
|
361
|
+
- [Interactive documentation][Omniref] is hosted by Omniref.
|
362
|
+
|
363
|
+
[RubyDoc]: http://www.rubydoc.info/gems/howzit
|
364
|
+
[Omniref]: https://www.omniref.com/ruby/gems/howzit
|
365
|
+
|
366
|
+
## Development and Testing
|
367
|
+
|
368
|
+
### Source Code
|
369
|
+
|
370
|
+
The [howzit source] is hosted on GitHub.
|
371
|
+
Clone the project with
|
372
|
+
|
373
|
+
```
|
374
|
+
$ git clone https://github.com/ttscoff/howzit.git
|
375
|
+
```
|
376
|
+
|
377
|
+
[howzit source]: https://github.com/ttscoff/howzit
|
378
|
+
|
379
|
+
### Requirements
|
380
|
+
|
381
|
+
You will need [Ruby] with [Bundler].
|
382
|
+
|
383
|
+
Install the development dependencies with
|
384
|
+
|
385
|
+
```
|
386
|
+
$ bundle
|
387
|
+
```
|
388
|
+
|
389
|
+
[Bundler]: http://bundler.io/
|
390
|
+
[Ruby]: https://www.ruby-lang.org/
|
391
|
+
|
392
|
+
### Rake
|
393
|
+
|
394
|
+
Run `$ rake -T` to see all Rake tasks.
|
395
|
+
|
396
|
+
```
|
397
|
+
rake build # Build howzit-2.0.1.gem into the pkg directory
|
398
|
+
rake bump:current[tag] # Show current gem version
|
399
|
+
rake bump:major[tag] # Bump major part of gem version
|
400
|
+
rake bump:minor[tag] # Bump minor part of gem version
|
401
|
+
rake bump:patch[tag] # Bump patch part of gem version
|
402
|
+
rake bump:pre[tag] # Bump pre part of gem version
|
403
|
+
rake bump:set # Sets the version number using the VERSION environment variable
|
404
|
+
rake clean # Remove any temporary products
|
405
|
+
rake clobber # Remove any generated files
|
406
|
+
rake install # Build and install howzit-2.0.1.gem into system gems
|
407
|
+
rake install:local # Build and install howzit-2.0.1.gem into system gems without network access
|
408
|
+
rake release[remote] # Create tag v2.0.1 and build and push howzit-2.0.1.gem to Rubygems
|
409
|
+
rake rubocop # Run RuboCop
|
410
|
+
rake rubocop:auto_correct # Auto-correct RuboCop offenses
|
411
|
+
rake spec # Run RSpec code examples
|
412
|
+
rake test # Run test suite
|
413
|
+
rake yard # Generate YARD Documentation
|
414
|
+
```
|
415
|
+
|
416
|
+
### Guard
|
417
|
+
|
418
|
+
Guard tasks have been separated into the following groups:
|
419
|
+
`doc`, `lint`, and `unit`.
|
420
|
+
By default, `$ guard` will generate documentation, lint, and run unit tests.
|
421
|
+
|
422
|
+
## Contributing
|
423
|
+
|
424
|
+
Please submit and comment on bug reports and feature requests.
|
425
|
+
|
426
|
+
To submit a patch:
|
427
|
+
|
428
|
+
1. Fork it (https://github.com/ttscoff/howzit/fork).
|
429
|
+
2. Create your feature branch (`git checkout -b my-new-feature`).
|
430
|
+
3. Make changes. Write and run tests.
|
431
|
+
4. Commit your changes (`git commit -am 'Add some feature'`).
|
432
|
+
5. Push to the branch (`git push origin my-new-feature`).
|
433
|
+
6. Create a new Pull Request.
|
434
|
+
|
data/Rakefile
ADDED
@@ -0,0 +1,18 @@
|
|
1
|
+
require 'bump/tasks'
|
2
|
+
require 'bundler/gem_tasks'
|
3
|
+
require 'rspec/core/rake_task'
|
4
|
+
require 'rubocop/rake_task'
|
5
|
+
require 'yard'
|
6
|
+
|
7
|
+
task default: [:test, :yard]
|
8
|
+
|
9
|
+
desc 'Run test suite'
|
10
|
+
task test: [:rubocop, :spec]
|
11
|
+
|
12
|
+
RSpec::Core::RakeTask.new
|
13
|
+
|
14
|
+
RuboCop::RakeTask.new do |t|
|
15
|
+
t.formatters = ['progress']
|
16
|
+
end
|
17
|
+
|
18
|
+
YARD::Rake::YardocTask.new
|
data/bin/howzit
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
complete -xc bld -a "(howzit -T)"
|
@@ -0,0 +1 @@
|
|
1
|
+
fisher complete
|