← Back to branch summary

~ultradvorka/hstr/hh

« back to all changes in this revision

Viewing changes to DOCUMENTATION.md

  • Committer: Martin Dvorak
  • Date: 2015-04-28 06:56:59 UTC
  • Revision ID: git-v1:f82800ae5daab4850e0dfb87682b83b9a4bb6999
Minor favorites refactoring and blacklist skeleton.

Show diffs side-by-side

added added

removed removed

Lines of Context:
DOCUMENTATION.md
 
1
This document is an unfinished draft.
 
2
 
 
3
HSTR DOCUMENTATION
 
4
==================
 
5
Table of contents:
 
6
* Installation
 
7
  * Distribution
 
8
  * Source code
 
9
  * Ubuntu
 
10
  * Debian
 
11
  * Mint
 
12
  * Arch
 
13
  * Mac OS
 
14
* Configuration
 
15
  * Keyboard shortcut
 
16
  * Colors
 
17
  * View
 
18
  * Verbosity
 
19
  * Shell specific
 
20
    * Bash
 
21
    * Zsh
 
22
* Features
 
23
  * History views
 
24
    * Ranking
 
25
    * Raw
 
26
    * Favorites
 
27
  * History filtering
 
28
  * Choosing a command
 
29
  * Favorite commands
 
30
  * Blacklist
 
31
* Examples
 
32
  
 
33
 
 
34
Features
 
35
--------
 
36
`hh` is typically started by pressing `Ctrl-r` after
 
37
you configure it for this shorcut for your shell. However,
 
38
you can run it as a normal program just by typing:
 
39
```bash
 
40
hh
 
41
```
 
42
 
 
43
It opens a page with a history view (ranking view is default).
 
44
Alternatively you can run `hh` in non-interactive mode - 
 
45
commands are just listed on standard output based on history
 
46
view:
 
47
```bash
 
48
hh --non-interactive
 
49
```
 
50
 
 
51
Filtering pattern can be optionally specified as well:
 
52
```bash
 
53
hh -i git
 
54
```
 
55
 
 
56
Prints history items containing `git` to standard output and
 
57
exits.
 
58
 
 
59
 
 
60
### History filtering
 
61
When `hh` starts in interative mode, a view of commands
 
62
is shown. This list of commands can be filtered just by typing
 
63
a string pattern.
 
64
 
 
65
 
 
66
### Choosing a command
 
67
When you filtered the view of history items enough, you can
 
68
move around it with `UP` and `DOWN` arrow keys. Selected history
 
69
items is highlighted. Once you are done with your choice:
 
70
 
 
71
* press `ENTER` to choose the command and execute it
 
72
* or press `TAB` or `RIGHT` arrow key to choose the command and edit it on command line after exiting `hh`
 
73
* or press `LEFT` arrow key to choose the command and open it in editor (Bash `fc` i.e. fix command)
 
74
 
 
75
 
 
76
 
 
77
Favorite Commands
 
78
-----------------
 
79
`hh` allows you to store and manage your favorite 
 
80
commands. 
 
81
 
 
82
A new favorite command can be added from
 
83
ranking or raw history view by pressing `Ctrl-f`.
 
84
 
 
85
You can check your favorite commands by choosing 
 
86
favorite view - rotate views using `Ctrl-/` or start
 
87
`hh` by adding `favorites` to `HH_CONFIG` environment
 
88
property. A favorite command can be choosen just
 
89
by pressing `ENTER` when on command in favorite view.
 
90
Last chosen favorite commands appears as the first
 
91
one (at the top of the page) in the favorite view.
 
92
You can delete a favorite command with `DEL` key.
 
93
 
 
94
Tips:
 
95
* Favorite commands are stored in `~/.hh_favorites`
 
96
* Suffix your favorite commands with comments
 
97
  describing their purpose. For example 
 
98
  `printf "\e[?2004l"   # fix terminal copy/paste`
 
99
  Such comment can be used for normal commands
 
100
  as well and may serve as a way how to **tag**
 
101
  commands.
 
102
 
 
103
 
 
104
Blacklist
 
105
---------
 
106
`hh` allows you to specify a set of commands to be
 
107
skipped from all the views. Blacklist typically contains
 
108
frequently used commands whose completion from history 
 
109
has a little or no value. The default blacklist looks 
 
110
like this:
 
111
 
 
112
```bash
 
113
pwd
 
114
cd
 
115
cd ..
 
116
ls
 
117
hh
 
118
mc
 
119
```
 
120
 
 
121
Tips:
 
122
* Blacklist of commands is stored in `~/.hh_blacklist`
 
123
  If the file doesn't exist, you may create it and complete
 
124
  it with your own blacklist.
 
125
* You can skip any command from history just by
 
126
  prefixing it with `SPACE`. For example:
 
127
  ` echo "Skip this from history"` It's a Bash
 
128
  option that is configured using 
 
129
  `HISTCONTROL=ignorespace` environment variable.
 
130
 
 
131
 
 
132
Examples
 
133
--------
 
134
Get more colors when running `hh`:
 
135
```bash
 
136
export HH_CONFIG=hicolor
 
137
```
 
138
 
 
139
Start `hh` in configured view and filter out history items 
 
140
containing 'git':
 
141
```bash
 
142
hh git
 
143
```
 
144
 
 
145
Print history items containing 'git' to standard output and exit:
 
146
```bash
 
147
hh --non-interactive git
 
148
```
 
149
 
 
150
Append  default `hh` configuration to your Bash profile:
 
151
```bash
 
152
hh --show-configuration >> ~/.bashrc
 
153
```
 
154
 
 
155
Check `hh` man page:
 
156
```bash
 
157
man hh
 
158
```