aboutsummaryrefslogtreecommitdiff
path: root/man/man7/dotfiles.7df
blob: 0b8ab981cbaaf2d43a1b88f4d3e104f7716cd854 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
.\" Automatically generated by Pandoc 1.19.2.1
.\"
.TH "DOTFILES" "7" "October 2017" "Tom Ryder's personal scripts and configuration" ""
.hy
.SH Dotfiles (Tom Ryder)
.PP
This is my personal repository of configuration files and scripts for
\f[C]$HOME\f[], including most of the settings that migrate well between
machines.
.PP
This repository began as a simple way to share Vim and tmux
configuration, but over time a lot of scripts and shell configuration
have been added, making it into a personal suite of custom Unix tools.
.SS Installation
.IP
.nf
\f[C]
$\ git\ clone\ https://sanctum.geek.nz/code/dotfiles.git\ ~/.dotfiles
$\ cd\ ~/.dotfiles
$\ git\ submodule\ init
$\ git\ submodule\ update
$\ make
$\ make\ \-n\ install
$\ make\ install
\f[]
.fi
.PP
For the default \f[C]all\f[] target, you'll need a POSIX\-fearing
userland, including \f[C]make(1)\f[] and \f[C]m4(1)\f[].
.PP
The installation \f[C]Makefile\f[] will overwrite things standing in the
way of its installed files without backing them up, so read the output
of \f[C]make\ \-n\ install\f[] before running \f[C]make\ install\f[] to
make sure you aren't going to lose anything unexpected.
If you're still not sure, install it in a temporary directory so you can
explore:
.IP
.nf
\f[C]
$\ tmpdir=$(mktemp\ \-d)
$\ make\ install\ HOME="$tmpdir"
$\ env\ \-i\ HOME="$tmpdir"\ TERM="$TERM"\ "$SHELL"\ \-l
\f[]
.fi
.PP
The default \f[C]install\f[] target will install these targets and all
their dependencies.
Note that you don't actually have to have any of this except \f[C]sh\f[]
installed.
.IP \[bu] 2
\f[C]install\-bin\f[]
.IP \[bu] 2
\f[C]install\-bin\-man\f[]
.IP \[bu] 2
\f[C]install\-curl\f[]
.IP \[bu] 2
\f[C]install\-ex\f[]
.IP \[bu] 2
\f[C]install\-git\f[]
.IP \[bu] 2
\f[C]install\-gnupg\f[]
.IP \[bu] 2
\f[C]install\-less\f[]
.IP \[bu] 2
\f[C]install\-login\-shell\f[]
.IP \[bu] 2
\f[C]install\-readline\f[]
.IP \[bu] 2
\f[C]install\-vim\f[]
.PP
The \f[C]install\-login\-shell\f[] looks at your \f[C]SHELL\f[]
environment variable and tries to figure out which shell's configuration
files to install, falling back on \f[C]install\-sh\f[].
.PP
The remaining files can be installed with the other \f[C]install\-*\f[]
targets.
Try \f[C]awk\ \-f\ bin/mftl.awk\ Makefile\f[] in the project's root
directory to see a list.
.SS Tools
.PP
Configuration is included for:
.IP \[bu] 2
Bourne\-style POSIX shells, sharing a \f[C]\&.profile\f[], an
\f[C]ENV\f[] file, and some helper functions:
.RS 2
.IP \[bu] 2
GNU Bash (https://www.gnu.org/software/bash/) (2.05a or higher)
.IP \[bu] 2
Korn shell (http://www.kornshell.com/) (\f[C]ksh93\f[], \f[C]pdksh\f[],
\f[C]mksh\f[])
.IP \[bu] 2
Z shell (https://www.zsh.org/)
.RE
.IP \[bu] 2
Abook (http://abook.sourceforge.net/) \[en] curses address book program
.IP \[bu] 2
cURL (https://curl.haxx.se/) \[en] Command\-line tool for transferring
data with URL syntax
.IP \[bu] 2
Dunst (http://knopwob.org/dunst/) \[en] A lightweight X11 notification
daemon that works with \f[C]libnotify\f[]
.IP \[bu] 2
\f[C]finger(1)\f[] \[en] User information lookup program
.IP \[bu] 2
Git (https://git-scm.com/) \[en] Distributed version control system
.IP \[bu] 2
GnuPG (https://www.gnupg.org/) \[en] GNU Privacy Guard, for private
communication and file encryption
.IP \[bu] 2
GTK+ (https://www.gtk.org/) \[en] GIMP Toolkit, for graphical user
interface elements
.IP \[bu] 2
i3 (https://i3wm.org/) \[en] Tiling window manager
.IP \[bu] 2
less (https://www.gnu.org/software/less/) \[en] Terminal pager
.IP \[bu] 2
Mutt (http://www.mutt.org/) \[en] Terminal mail user agent
.IP \[bu] 2
\f[C]mysql(1)\f[] (https://linux.die.net/man/1/mysql) \[en]
Command\-line MySQL client
.IP \[bu] 2
Ncmpcpp (https://rybczak.net/ncmpcpp/) \[en] ncurses music player client
.IP \[bu] 2
Newsbeuter (https://www.newsbeuter.org/) \[en] Terminal RSS/Atom feed
reader
.IP \[bu] 2
\f[C]psql(1)\f[] (https://linux.die.net/man/1/psql) \[en] Command\-line
PostgreSQL client
.IP \[bu] 2
Perl::Critic (http://perlcritic.com/) \[en] static source code analysis
engine for Perl
.IP \[bu] 2
Perl::Tidy (http://perltidy.sourceforge.net/) \[en] Perl source code
reformatter
.IP \[bu] 2
Readline (https://cnswww.cns.cwru.edu/php/chet/readline/rltop.html)
\[en] GNU library for user input used by Bash, MySQL, and others
.IP \[bu] 2
rxvt\-unicode (http://software.schmorp.de/pkg/rxvt-unicode.html) \[en]
Fork of the rxvt terminal emulator with Unicode support
.IP \[bu] 2
Subversion (https://subversion.apache.org/) \[en] Apache Subversion, a
version control system
.IP \[bu] 2
tidy (http://www.html-tidy.org/) \[en] HTML/XHTML linter and tidier
.IP \[bu] 2
tmux (https://tmux.github.io/) \[en] Terminal multiplexer similar to GNU
Screen
.IP \[bu] 2
Vim (http://www.vim.org/) \[en] Vi IMproved, a text editor
.IP \[bu] 2
X11 (https://www.x.org/wiki/) \[en] Windowing system with network
transparency for Unix
.PP
The configurations for shells, GnuPG, Mutt, tmux, and Vim are the most
expansive, and most likely to be of interest.
The i3 configuration is mostly changed to make window switching behave
like Vim windows and tmux panes do, and there's a fair few resources
defined for rxvt\-unicode.
.SS Shell
.PP
My \f[C]\&.profile\f[] and other files in \f[C]sh\f[] are written in
POSIX shell script, so they should work in most \f[C]sh(1)\f[]
implementations.
Individual scripts called by \f[C]\&.profile\f[] are saved in
\f[C]\&.profile.d\f[] and iterated on login for ease of management.
Most of these boil down to exporting variables appropriate to the system
and the software it has available.
.PP
Configuration that should be sourced for all POSIX\-fearing interactive
shells is kept in \f[C]~/.shrc\f[], with subscripts read from
\f[C]~/.shrc.d\f[].
There's a shim in \f[C]~/.shinit\f[] to act as \f[C]ENV\f[].
I make an effort to target POSIX for my functions and scripts where I
can so that the same files can be loaded for all shells.
.PP
On GNU/Linux I use Bash, on BSD I use some variant of Korn Shell,
preferably \f[C]ksh93\f[] if it's available.
.PP
As I occasionally have work on very old internal systems, my Bash is
written to work with any version 2.05a or
newer (http://wiki.bash-hackers.org/scripting/bashchanges).
This is why I use older syntax for certain things such as appending
items to arrays:
.IP
.nf
\f[C]
array[${#array[\@]}]=$item
\f[]
.fi
.PP
Compare this to the much nicer syntax available since 3.1\-alpha1, which
actually works for arrays with sparse indices, unlike the above syntax:
.IP
.nf
\f[C]
array+=("$item")
\f[]
.fi
.PP
Where I do use features that are only available in versions of Bash
newer than 2.05a, such as newer \f[C]shopt\f[] options or
\f[C]PROMPT_DIRTRIM\f[], they are only run after testing
\f[C]BASH_VERSINFO\f[] appropriately.
.SS Prompt
.PP
A terminal session with my prompt looks something like this:
.IP
.nf
\f[C]
~$\ ssh\ remote
remote:~$\ cd\ .dotfiles
remote:~/.dotfiles(master+!)$\ git\ status
\ M\ README.md
M\ \ bash/bashrc.d/prompt.bash
A\ \ init
remote:~/.dotfiles(master+!)$\ foobar
foobar:\ command\ not\ found
remote:~/.dotfiles(master+!)<127>$\ sleep\ 5\ &
[1]\ 28937
remote:~/.dotfiles(master+!){1}$
\f[]
.fi
.PP
The hostname is elided if not connected via SSH.
The working directory with tilde abbreviation for \f[C]$HOME\f[] is
always shown.
The rest of the prompt expands based on context to include these
elements in this order:
.IP \[bu] 2
Whether in a Git repository if applicable, and punctuation to show
repository status including reference to upstreams at a glance.
Subversion support can also be enabled (I need it at work), in which
case a \f[C]git:\f[] or \f[C]svn:\f[] prefix is added appropriately.
.IP \[bu] 2
The number of running background jobs, if non\-zero.
.IP \[bu] 2
The exit status of the last command, if non\-zero.
.PP
You can set \f[C]PROMPT_COLOR\f[], \f[C]PROMPT_PREFIX\f[], and
\f[C]PROMPT_SUFFIX\f[] too, which all do about what you'd expect.
.PP
If you start up Bash, Korn shell, or Z shell, and it detects that it's
normally your \f[C]$SHELL\f[] is one of the other two, the prompt will
display an appropriate prefix.
.PP
This is all managed within the \f[C]prompt\f[] function.
There's some mildly hacky logic on \f[C]tput\f[] codes included such
that it should work correctly for most common terminals using both
\f[C]termcap(5)\f[] and \f[C]terminfo(5)\f[], including *BSD systems.
It's also designed to degrade gracefully for eight\-color and no\-color
terminals.
.SS Functions
.PP
If a function can be written in POSIX \f[C]sh\f[] without too much
hackery, I put it in \f[C]sh/shrc.d\f[] to be loaded by any POSIX
interactive shell.
Those include:
.IP \[bu] 2
Four functions for using a \[lq]marked\[rq] directory, which I find a
more manageable concept than the \f[C]pushd\f[]/\f[C]popd\f[] directory
stack:
.RS 2
.IP \[bu] 2
\f[C]md()\f[] marks a given (or the current) directory.
.IP \[bu] 2
\f[C]gd()\f[] goes to the marked directory.
.IP \[bu] 2
\f[C]pmd()\f[] prints the marked directory.
.IP \[bu] 2
\f[C]xd()\f[] swaps the current and marked directories.
.RE
.IP \[bu] 2
Ten other directory management and navigation functions:
.RS 2
.IP \[bu] 2
\f[C]bd()\f[] changes into a named ancestor of the current directory.
.IP \[bu] 2
\f[C]gt()\f[] changes into a directory or into a file's directory.
.IP \[bu] 2
\f[C]lgt()\f[] runs \f[C]gt()\f[] on the first result from a
\f[C]loc(1df)\f[] search.
.IP \[bu] 2
\f[C]mkcd()\f[] creates a directory and changes into it.
.IP \[bu] 2
\f[C]pd()\f[] changes to the argument's parent directory.
.IP \[bu] 2
\f[C]rd()\f[] replaces the first instance of its first argument with its
second argument in \f[C]$PWD\f[], emulating a feature of the Zsh
\f[C]cd\f[] builtin that I like.
.IP \[bu] 2
\f[C]scr()\f[] creates a temporary directory and changes into it.
.IP \[bu] 2
\f[C]sd()\f[] changes into a sibling of the current directory.
.IP \[bu] 2
\f[C]ud()\f[] changes into an indexed ancestor of a directory.
.IP \[bu] 2
\f[C]vr()\f[] tries to change to the root directory of a source control
repository.
.RE
.IP \[bu] 2
\f[C]bc()\f[] silences startup messages from GNU \f[C]bc(1)\f[].
.IP \[bu] 2
\f[C]ed()\f[] tries to get verbose error messages, a prompt, and a
Readline environment for \f[C]ed(1)\f[].
.IP \[bu] 2
\f[C]gdb()\f[] silences startup messages from \f[C]gdb(1)\f[].
.IP \[bu] 2
\f[C]gpg()\f[] quietens \f[C]gpg(1)\f[] down for most commands.
.IP \[bu] 2
\f[C]grep()\f[] tries to apply color and other options good for
interactive use if available.
.IP \[bu] 2
\f[C]hgrep()\f[] allows searching \f[C]$HISTFILE\f[].
.IP \[bu] 2
\f[C]keychain()\f[] keeps \f[C]$GPG_TTY\f[] up to date if a GnuPG agent
is available.
.IP \[bu] 2
\f[C]ls()\f[] tries to apply color and other options good for
interactive use if available.
.RS 2
.IP \[bu] 2
\f[C]la()\f[] runs \f[C]ls\ \-A\f[] if it can, or \f[C]ls\ \-a\f[]
otherwise.
.IP \[bu] 2
\f[C]ll()\f[] runs \f[C]ls\ \-Al\f[] if it can, or \f[C]ls\ \-al\f[]
otherwise.
.RE
.IP \[bu] 2
\f[C]path()\f[] manages the contents of \f[C]PATH\f[] conveniently.
.IP \[bu] 2
\f[C]scp()\f[] tries to detect forgotten hostnames in \f[C]scp(1)\f[]
command calls.
.IP \[bu] 2
\f[C]sudo()\f[] forces \f[C]\-H\f[] for \f[C]sudo(8)\f[] calls so that
\f[C]$HOME\f[] is never preserved; I hate having \f[C]root\f[]\-owned
files in my home directory.
.IP \[bu] 2
\f[C]tree()\f[] colorizes GNU \f[C]tree(1)\f[] output if possible
(without having \f[C]LS_COLORS\f[] set).
.IP \[bu] 2
\f[C]x()\f[] is a one\-key shortcut for \f[C]exec\ startx\f[].
.PP
There are a few other little tricks defined for other shells providing
non\-POSIX features, as compatibility allows:
.IP \[bu] 2
\f[C]keep()\f[] stores ad\-hoc shell functions and variables (Bash, Korn
Shell 93, Z shell).
.IP \[bu] 2
\f[C]prompt()\f[] sets up my interactive prompt (Bash, Korn Shell, Z
shell).
.IP \[bu] 2
\f[C]pushd()\f[] adds a default destination of \f[C]$HOME\f[] to the
\f[C]pushd\f[] builtin (Bash).
.IP \[bu] 2
\f[C]vared()\f[] allows interactively editing a variable with Readline,
emulating a Zsh function I like by the same name (Bash).
.IP \[bu] 2
\f[C]ver()\f[] prints the current shell's version information (Bash,
Korn Shell, Z shell).
.SS Completion
.PP
I find the \f[C]bash\-completion\f[] package a bit too heavy for my
tastes, and turn it off using a stub file installed in
\f[C]~/.config/bash_completion\f[].
The majority of the time I just want to complete paths anyway, and this
makes for a quicker startup without a lot of junk functions in my Bash
namespace.
.PP
I do make some exceptions with completions defined in
\f[C]\&.bash_completion.d\f[] files, for things I really do get tired of
typing repeatedly:
.IP \[bu] 2
Bash builtins: commands, help topics, shell options, variables, etc.
.IP \[bu] 2
\f[C]find(1)\f[]'s more portable options
.IP \[bu] 2
\f[C]ftp(1)\f[] hostnames from \f[C]~/.netrc\f[]
.IP \[bu] 2
\f[C]git(1)\f[] subcommands, remotes, branches, tags, and addable files
.IP \[bu] 2
\f[C]gpg(1)\f[] long options
.IP \[bu] 2
\f[C]make(1)\f[] targets read from a \f[C]Makefile\f[]
.IP \[bu] 2
\f[C]man(1)\f[] page titles
.IP \[bu] 2
\f[C]pass(1)\f[] entries
.IP \[bu] 2
\f[C]ssh(1)\f[] hostnames from \f[C]~/.ssh/config\f[]
.PP
For commands that pretty much always want to operate on text, such as
text file or stream editors, I exclude special file types and extensions
I know are binary.
I don't actually read the file, so this is more of a heuristic thing,
and sometimes it will get things wrong.
.PP
I also add completions for my own scripts and functions where useful.
The completions are dynamically loaded if Bash is version 4.0 or
greater.
Otherwise, they're all loaded on startup.
.SS Korn shell
.PP
These are experimental; they are mostly used to tinker with MirBSD
\f[C]mksh\f[], AT&T \f[C]ksh93\f[], and OpenBSD \f[C]pdksh\f[].
All shells in this family default to a yellow prompt if detected.
.SS Z shell
.PP
These are experimental; I do not like Z shell much at the moment.
The files started as a joke (\f[C]exec\ bash\f[]).
\f[C]zsh\f[] shells default to having a prompt colored cyan.
.SS GnuPG
.PP
The configuration for GnuPG is intended to follow RiseUp's OpenPGP best
practices (https://riseup.net/en/security/message-security/openpgp/best-practices).
The configuration file is rebuilt using \f[C]mi5(1df)\f[] and
\f[C]make(1)\f[] because it requires hard\-coding a path to the SKS
keyserver certificate authority, and neither tilde nor \f[C]$HOME\f[]
expansion works for this.
.SS Mutt
.PP
My mail is kept in individual Maildirs under \f[C]~/Mail\f[], with
\f[C]inbox\f[] being where most unfiltered mail is sent.
I use Getmail (http://pyropus.ca/software/getmail/),
maildrop (https://www.courier-mta.org/maildrop/), and
msmtp (http://msmtp.sourceforge.net/); the configurations for these are
not included here.
I sign whenever I have some indication that the recipient might be using
a PGP implementation, and I encrypt whenever I have a public key
available for them.
The GnuPG and S/MIME interfacing is done with
GPGme (https://www.gnupg.org/related_software/gpgme/), rather than
defining commands for each crypto operation.
I wrote an article about this
setup (https://sanctum.geek.nz/arabesque/linux-crypto-email/) if it
sounds appealing.
.PP
You'll need Abook (http://abook.sourceforge.net/) installed if you want
to use the \f[C]query_command\f[] I have defined, and
msmtp (http://msmtp.sourceforge.net/) for the \f[C]sendmail\f[] command.
.SS rxvt\-unicode
.PP
I've butchered the URxvt Perl extensions
\f[C]selection\-to\-clipboard\f[] and \f[C]selection\f[] into a single
\f[C]select\f[] extension in \f[C]~/.urxvt/ext\f[], which is the only
extension I define in \f[C]~/.Xresources\f[].
.PP
The included \f[C]\&.Xresources\f[] file assumes that \f[C]urxvt\f[] can
use 256 colors and Perl extensions.
If you're missing functionality, try changing \f[C]perl\-ext\-common\f[]
to \f[C]default\f[].
.PP
My choice of font is Ubuntu Mono (http://font.ubuntu.com/), but the file
should allow falling back to the more common Deja Vu Sans
Mono (https://dejavu-fonts.github.io/).
I've found Terminus (http://terminus-font.sourceforge.net/) works well
too, but bitmap fonts are not really my cup of tea.
The Lohit Kannada font bit is purely to make ಠ_ಠ work correctly.
( ͡° ͜ʖ ͡°) seems to work out of the box.
.SS tmux
.PP
These are just generally vi\-friendly settings, not much out of the
ordinary.
Note that the configuration presently uses a hard\-coded 256\-color
color scheme, and uses non\-login shells, with an attempt to control the
environment to stop shells thinking they have access to an X display.
.PP
The shell scripts in \f[C]bin\f[] include \f[C]tm(1df)\f[], a shortcut
to make \f[C]attach\f[] into the default command if no arguments are
given and sessions do already exist.
My \f[C]~/.inputrc\f[] file binds Alt+M to run that, and Tmux in turn
binds the same key combination to detach.
.SS Vim
.PP
The majority of the Vim configuration is just setting options, with a
few mappings.
I try not to deviate too much from the Vim defaults behavior in terms of
interactive behavior and keybindings.
.PP
The configuration is broken into smaller files in
\f[C]~/.vim/config/*.vim\f[], included by \f[C]~/.vimrc\f[] using
\f[C]:runtime\f[] (http://vimdoc.sourceforge.net/htmldoc/repeat.html#:runtime).
It's extensively commented, mostly because I was reading through it one
day and realized I'd forgotten what half of it did.
.SS Plugins
.PP
If the logic for doing something involves more than a few lines or any
structures like functions, I like to implement it as a plugin in
\f[C]~/.vim/plugin\f[] and/or \f[C]~/.vim/autoload\f[].
There's documentation for each of those in \f[C]~/.vim/doc\f[].
.PP
I also define a few rules specific to file types I often edit in
\f[C]~/.vim/ftplugin\f[], including some local mappings for checking,
linting, and tidying.
.PP
Any/all of the plugins may eventually be spun off into their own
repositories in the future, but for the moment they live here.
Contact me if you find one of them useful and you'd like to see it in
its own distribution.
.PP
Third\-party plugins are in submodules in \f[C]~/.vim/bundle\f[], loaded
using Tim Pope's pathogen.vim (https://github.com/tpope/vim-pathogen).
.SS Scripts
.PP
Where practical, I make short scripts into POSIX (but not Bourne)
\f[C]sh(1)\f[], \f[C]awk(1)\f[], or \f[C]sed(1)\f[] scripts in
\f[C]~/.local/bin\f[].
I try to use shell functions only when I actually need to, which tends
to be when I need to tinker with the namespace of the user's current
shell.
.PP
Installed by the \f[C]install\-bin\f[] target:
.IP \[bu] 2
Three SSH\-related scripts:
.RS 2
.IP \[bu] 2
\f[C]sls(1df)\f[] prints hostnames read from a \f[C]ssh_config(5)\f[]
file.
It uses \f[C]slsf(1df)\f[] to read each one.
.IP \[bu] 2
\f[C]sra(1df)\f[] runs a command on multiple hosts read from
\f[C]sls(1df)\f[] and prints output.
.IP \[bu] 2
\f[C]sta(1df)\f[] runs a command on multiple hosts read from
\f[C]sls(1df)\f[] and prints the hostname if the command returns zero.
.RE
.IP \[bu] 2
Five URL\-related shortcut scripts:
.RS 2
.IP \[bu] 2
\f[C]hurl(1df)\f[] extracts values of \f[C]href\f[] attributes of
\f[C]<a>\f[] tags, sorts them uniquely, and writes them to
\f[C]stdout\f[]; it requires pup (https://github.com/ericchiang/pup).
.IP \[bu] 2
\f[C]murl(1df)\f[] converts Markdown documents to HTML with
\f[C]pandoc(1)\f[] and runs the output through \f[C]hurl(1df)\f[].
.IP \[bu] 2
\f[C]urlc(1df)\f[] accepts a list of URLs on \f[C]stdin\f[] and writes
error messages to \f[C]stderr\f[] if any of the URLs are broken,
redirecting, or are insecure and have working secure versions; requires
\f[C]curl(1)\f[].
.IP \[bu] 2
\f[C]urlh(1df)\f[] prints the values for a given HTTP header from a HEAD
response.
.IP \[bu] 2
\f[C]urlmt(1df)\f[] prints the MIME type from the \f[C]Content\-Type\f[]
header as retrieved by \f[C]urlh(1df)\f[].
.RE
.IP \[bu] 2
Three RFC\-related shortcut scripts:
.RS 2
.IP \[bu] 2
\f[C]rfcf(1df)\f[] fetches ASCII RFCs from the IETF website.
.IP \[bu] 2
\f[C]rfct(1df)\f[] formats ASCII RFCs.
.IP \[bu] 2
\f[C]rfcr(1df)\f[] does both, displaying in a pager if appropriate, like
a \f[C]man(1)\f[] reader for RFCs.
.RE
.IP \[bu] 2
Five toy random\-number scripts (not for sensitive/dead\-serious use):
.RS 2
.IP \[bu] 2
\f[C]rndi(1df)\f[] gets a random integer within two bounds.
.IP \[bu] 2
\f[C]rnds(1df)\f[] attempts to get an optional random seed for
\f[C]rndi(1df)\f[].
.IP \[bu] 2
\f[C]rnda(1df)\f[] uses \f[C]rndi(1df)\f[] to choose a random argument.
.IP \[bu] 2
\f[C]rndf(1df)\f[] uses \f[C]rnda(1df)\f[] to choose a random file from
a directory.
.IP \[bu] 2
\f[C]rndl(1df)\f[] uses \f[C]rndi(1df)\f[] to choose a random line from
files.
.RE
.IP \[bu] 2
Four file formatting scripts:
.RS 2
.IP \[bu] 2
\f[C]d2u(1df)\f[] converts DOS line endings in files to UNIX ones.
.IP \[bu] 2
\f[C]u2d(1df)\f[] converts UNIX line endings in files to DOS ones.
.IP \[bu] 2
\f[C]stbl(1df)\f[] strips a trailing blank line from the files in its
arguments.
.IP \[bu] 2
\f[C]stws(1df)\f[] strips trailing spaces from the ends of lines of the
files in its arguments.
.RE
.IP \[bu] 2
Seven stream formatting scripts:
.RS 2
.IP \[bu] 2
\f[C]sd2u(1df)\f[] converts DOS line endings in streams to UNIX ones.
.IP \[bu] 2
\f[C]su2d(1df)\f[] converts UNIX line endings in streams to DOS ones.
.IP \[bu] 2
\f[C]slow(1df)\f[] converts uppercase to lowercase.
.IP \[bu] 2
\f[C]supp(1df)\f[] converts lowercase to uppercase.
.IP \[bu] 2
\f[C]tl(1df)\f[] tags input lines with a prefix or suffix, basically a
\f[C]sed(1)\f[] shortcut.
.IP \[bu] 2
\f[C]tlcs(1df)\f[] executes a command and uses \f[C]tl(1df)\f[] to tag
standard output and standard error lines, and color them if you want.
.IP \[bu] 2
\f[C]unf(1df)\f[] joins lines with leading spaces to the previous line.
Intended for unfolding HTTP headers, but it should work for most RFC 822
formats.
.RE
.IP \[bu] 2
Six simple aggregate scripts for numbers:
.RS 2
.IP \[bu] 2
\f[C]max(1df)\f[] prints the maximum.
.IP \[bu] 2
\f[C]mean(1df)\f[] prints the mean.
.IP \[bu] 2
\f[C]med(1df)\f[] prints the median.
.IP \[bu] 2
\f[C]min(1df)\f[] prints the minimum.
.IP \[bu] 2
\f[C]mode(1df)\f[] prints the first encountered mode.
.IP \[bu] 2
\f[C]tot(1df)\f[] totals the set.
.RE
.IP \[bu] 2
Three quick\-and\-dirty HTML tools:
.RS 2
.IP \[bu] 2
\f[C]htenc(1df)\f[] encodes.
.IP \[bu] 2
\f[C]htdec(1df)\f[] decodes.
.IP \[bu] 2
\f[C]htrec(1df)\f[] wraps \f[C]a\f[] tags around URLs.
.RE
.IP \[bu] 2
Two internet message quoting tools:
.RS 2
.IP \[bu] 2
\f[C]quo(1df)\f[] indents with quoting right angle\-brackets.
.IP \[bu] 2
\f[C]wro(1df)\f[] adds a quote attribution header to its input.
.RE
.IP \[bu] 2
Six Git\-related tools:
.RS 2
.IP \[bu] 2
\f[C]fgscr(1df)\f[] finds Git repositories in a directory root and
scrubs them with \f[C]gscr(1df)\f[].
.IP \[bu] 2
\f[C]grc(1df)\f[] quietly tests whether the given directory appears to
be a Git repository with pending changes.
.IP \[bu] 2
\f[C]gscr(1df)\f[] scrubs Git repositories.
.IP \[bu] 2
\f[C]isgr(1df)\f[] quietly tests whether the given directory appears to
be a Git repository.
.IP \[bu] 2
\f[C]jfc(1df)\f[] adds and commits lazily to a Git repository.
.IP \[bu] 2
\f[C]jfcd(1df)\f[] watches a directory for changes and runs
\f[C]jfc(1df)\f[] if it sees any.
.RE
.IP \[bu] 2
Two time duration functions:
.RS 2
.IP \[bu] 2
\f[C]hms(1df)\f[] converts seconds to \f[C]hh:mm:ss\f[] or
\f[C]mm:ss\f[] timestamps.
.IP \[bu] 2
\f[C]sec(1df)\f[] converts \f[C]hh:mm:ss\f[] or \f[C]mm:ss\f[]
timestamps to seconds.
.RE
.IP \[bu] 2
Three pipe interaction tools:
.RS 2
.IP \[bu] 2
\f[C]pst(1df)\f[] runs an interactive program on data before passing it
along a pipeline.
.IP \[bu] 2
\f[C]ped(1df)\f[] runs \f[C]pst(1df)\f[] with \f[C]$EDITOR\f[] or
\f[C]ed(1)\f[].
.IP \[bu] 2
\f[C]pvi(1df)\f[] runs \f[C]pvi(1df)\f[] with \f[C]$VISUAL\f[] or
\f[C]vi(1)\f[].
.RE
.IP \[bu] 2
\f[C]ap(1df)\f[] reads arguments for a given command from the standard
input, prompting if appropriate.
.IP \[bu] 2
\f[C]apf(1df)\f[] inserts arguments to a command with ones read from a
file, intended as a framework for shell wrappers or functions.
.IP \[bu] 2
\f[C]ax(1df)\f[] evaluates an AWK expression given on the command line;
this is intended as a quick way to test how Awk would interpret a given
expression.
.IP \[bu] 2
\f[C]bcq(1df)\f[] runs \f[C]bc(1)\f[], quieting it down if need be.
.IP \[bu] 2
\f[C]bel(1df)\f[] prints a terminal bell character.
.IP \[bu] 2
\f[C]bl(1df)\f[] generates a given number of blank lines.
.IP \[bu] 2
\f[C]bp(1df)\f[] runs \f[C]br(1df)\f[] after prompting for an URL.
.IP \[bu] 2
\f[C]br(1df)\f[] launches \f[C]$BROWSER\f[].
.IP \[bu] 2
\f[C]ca(1df)\f[] prints a count of its given arguments.
.IP \[bu] 2
\f[C]cf(1df)\f[] prints a count of entries in a given directory.
.IP \[bu] 2
\f[C]cfr(1df)\f[] does the same as \f[C]cf(1df)\f[], but recurses into
subdirectories as well.
.IP \[bu] 2
\f[C]chc(1df)\f[] caches the output of a command.
.IP \[bu] 2
\f[C]chn(1df)\f[] runs a filter over its input a given number of times.
.IP \[bu] 2
\f[C]clog(1df)\f[] is a tiny timestamped log system.
.IP \[bu] 2
\f[C]clrd(1df)\f[] sets up a per\-line file read, clearing the screen
first.
.IP \[bu] 2
\f[C]clwr(1df)\f[] sets up a per\-line file write, clearing the screen
before each line.
.IP \[bu] 2
\f[C]csmw(1df)\f[] prints an English list of monospace\-quoted words
read from the input.
.IP \[bu] 2
\f[C]dam(1df)\f[] buffers all its input before emitting it as output.
.IP \[bu] 2
\f[C]ddup(1df)\f[] removes duplicate lines from unsorted input.
.IP \[bu] 2
\f[C]dmp(1df)\f[] copies a pass(1) entry selected by \f[C]dmenu(1)\f[]
to the X CLIPBOARD.
.IP \[bu] 2
\f[C]dub(1df)\f[] lists the biggest entries in a directory.
.IP \[bu] 2
\f[C]edda(1df)\f[] provides a means to run \f[C]ed(1)\f[] over a set of
files preserving any options, mostly useful for scripts.
.IP \[bu] 2
\f[C]eds(1df)\f[] edits executable script files in \f[C]EDSPATH\f[],
defaulting to \f[C]~/.local/bin\f[], for personal scripting snippets.
.IP \[bu] 2
\f[C]exm(1df)\f[] works around a screen\-clearing quirk of Vim's
\f[C]ex\f[] mode.
.IP \[bu] 2
\f[C]finc(1df)\f[] counts the number of results returned from a set of
given \f[C]find(1)\f[] conditions.
.IP \[bu] 2
\f[C]fnl(1df)\f[] runs a command and saves its output and error into
temporary files, printing their paths and line counts.
.IP \[bu] 2
\f[C]fnp(1df)\f[] prints the given files to standard output, each with a
plain text heading with the filename in it.
.IP \[bu] 2
\f[C]gms(1df)\f[] runs a set of \f[C]getmailrc\f[] files; does much the
same thing as the script \f[C]getmails\f[] in the \f[C]getmail\f[]
suite, but runs the requests in parallel and does up to three silent
retries using \f[C]try(1df)\f[].
.IP \[bu] 2
\f[C]grec(1df)\f[] is a more logically\-named \f[C]grep\ \-c\f[].
.IP \[bu] 2
\f[C]gred(1df)\f[] is a more logically\-named \f[C]grep\ \-v\f[].
.IP \[bu] 2
\f[C]gwp(1df)\f[] searches for alphanumeric words in a similar way to
\f[C]grep(1)\f[].
.IP \[bu] 2
\f[C]han(1df)\f[] provides a \f[C]keywordprg\f[] for Vim's Bash script
file type that will look for \f[C]help\f[] topics.
You could use it from the shell too.
.IP \[bu] 2
\f[C]igex(1df)\f[] wraps around a command to allow you to ignore error
conditions that don't actually worry you, exiting with 0 anyway.
.IP \[bu] 2
\f[C]ix(1df)\f[] posts its input to the \f[C]ix.io\f[] pastebin.
.IP \[bu] 2
\f[C]jfp(1df)\f[] prints its input, excluding any shebang on the first
line only.
.IP \[bu] 2
\f[C]loc(1df)\f[] is a quick\-search wrapped around \f[C]find(1)\f[].
.IP \[bu] 2
\f[C]maybe(1df)\f[] is like \f[C]true(1)\f[] or \f[C]false(1)\f[]; given
a probability of success, it exits with success or failure.
Good for quick tests.
.IP \[bu] 2
\f[C]mex(1df)\f[] makes given filenames in \f[C]$PATH\f[] executable.
.IP \[bu] 2
\f[C]mi5(1df)\f[] is a crude preprocessor for \f[C]m4\f[].
.IP \[bu] 2
\f[C]mftl(1df)\f[] finds usable\-looking targets in makefiles.
.IP \[bu] 2
\f[C]mkcp(1df)\f[] creates a directory and copies preceding arguments
into it.
.IP \[bu] 2
\f[C]mkmv(1df)\f[] creates a directory and moves preceding arguments
into it.
.IP \[bu] 2
\f[C]motd(1df)\f[] shows the system MOTD.
.IP \[bu] 2
\f[C]mw(1df)\f[] prints alphabetic space\-delimited words from the input
one per line.
.IP \[bu] 2
\f[C]oii(1df)\f[] runs a command on input only if there is any.
.IP \[bu] 2
\f[C]onl(1df)\f[] crunches input down to one printable line.
.IP \[bu] 2
\f[C]osc(1df)\f[] implements a \f[C]netcat(1)\f[]\-like wrapper for
\f[C]openssl(1)\f[]'s \f[C]s_client\f[] subcommand.
.IP \[bu] 2
\f[C]p(1df)\f[] prints concatenated standard input; \f[C]cat(1)\f[] as
it should always have been.
.IP \[bu] 2
\f[C]pa(1df)\f[] prints its arguments, one per line.
.IP \[bu] 2
\f[C]pp(1df)\f[] prints the full path of each argument using
\f[C]$PWD\f[].
.IP \[bu] 2
\f[C]pph(1df)\f[] runs \f[C]pp(1df)\f[] and includes a leading
\f[C]$HOSTNAME:\f[].
.IP \[bu] 2
\f[C]paz(1df)\f[] print its arguments terminated by NULL chars.
.IP \[bu] 2
\f[C]pit(1df)\f[] runs its input through a pager if its standard output
looks like a terminal.
.IP \[bu] 2
\f[C]plmu(1df)\f[] retrieves a list of installed modules from
\f[C]plenv\f[] (https://github.com/tokuhirom/plenv), filters out any
modules in \f[C]~/.plenv/non\-cpan\-modules\f[], and updates them all.
.IP \[bu] 2
\f[C]pwg(1df)\f[] generates just one decent password with
\f[C]pwgen(1)\f[].
.IP \[bu] 2
\f[C]rep(1df)\f[] repeats a command a given number of times.
.IP \[bu] 2
\f[C]rgl(1df)\f[] is a very crude interactive \f[C]grep(1)\f[] loop.
.IP \[bu] 2
\f[C]shb(1df)\f[] attempts to build shebang lines for scripts from the
system paths.
.IP \[bu] 2
\f[C]sqs(1df)\f[] chops off query strings from filenames, usually
downloads.
.IP \[bu] 2
\f[C]sshi(1df)\f[] prints human\-readable SSH connection details.
.IP \[bu] 2
\f[C]stex(1df)\f[] strips extensions from filenames.
.IP \[bu] 2
\f[C]sue(8df)\f[] execs \f[C]sudoedit(8)\f[] as the owner of all the
file arguments given, perhaps in cases where you may not necessarily
have \f[C]root\f[] \f[C]sudo(8)\f[] privileges.
.IP \[bu] 2
\f[C]swr(1df)\f[] allows you to run commands locally specifying remote
files in \f[C]scp(1)\f[]'s HOST:PATH format.
.IP \[bu] 2
\f[C]td(1df)\f[] manages a to\-do file for you with \f[C]$EDITOR\f[] and
\f[C]git(1)\f[]; I used to use Taskwarrior, but found it too complex and
buggy.
.IP \[bu] 2
\f[C]tm(1df)\f[] runs \f[C]tmux(1)\f[] with
\f[C]attach\-session\ \-d\f[] if a session exists, and
\f[C]new\-session\f[] if it doesn't.
.IP \[bu] 2
\f[C]trs(1df)\f[] replaces strings (not regular expression) in its
input.
.IP \[bu] 2
\f[C]try(1df)\f[] repeats a command up to a given number of times until
it succeeds, only printing error output if all three attempts failed.
Good for tolerating blips or temporary failures in \f[C]cron(8)\f[]
scripts.
.IP \[bu] 2
\f[C]umake(1df)\f[] iterates upwards through the directory tree from
\f[C]$PWD\f[] until it finds a Makefile for which to run
\f[C]make(1)\f[] with the given arguments.
.IP \[bu] 2
\f[C]uts(1df)\f[] gets the current UNIX timestamp in an unorthodox way
that should work on all POSIX\-compliant operating systems.
.IP \[bu] 2
\f[C]vest(1df)\f[] runs \f[C]test(1)\f[] but fails with explicit output
via \f[C]vex(1df)\f[].
.IP \[bu] 2
\f[C]vex(1df)\f[] runs a command and prints \f[C]true\f[] or
\f[C]false\f[] explicitly to \f[C]stdout\f[] based on the exit value.
.IP \[bu] 2
\f[C]xrbg(1df)\f[] applies the same randomly\-selected background to
each X screen.
.IP \[bu] 2
\f[C]xrq(1df)\f[] gets the values of specific resources out of
\f[C]xrdb\ \-query\f[] output.
.PP
There's some silly stuff in \f[C]install\-games\f[]:
.IP \[bu] 2
\f[C]aaf(6df)\f[] gets a random ASCII Art
Farts (http://www.asciiartfarts.com/) comic.
.IP \[bu] 2
\f[C]acq(6df)\f[] allows you to interrogate AC, the interplanetary
computer.
.IP \[bu] 2
\f[C]aesth(6df)\f[] converts English letters to their full width CJK
analogues, for AESTHETIC PURPOSES.
.IP \[bu] 2
\f[C]squ(6df)\f[] makes a reduced Latin square out of each line of
input.
.IP \[bu] 2
\f[C]kvlt(6df)\f[] translates input to emulate a style of typing unique
to black metal communities on the internet.
.IP \[bu] 2
\f[C]philsay(6df)\f[] shows a picture to accompany \f[C]pks(6df)\f[]
output.
.IP \[bu] 2
\f[C]pks(6df)\f[] laughs at a randomly selected word.
.IP \[bu] 2
\f[C]rndn(6df)\f[] implements an esoteric random number generation
algorithm.
.IP \[bu] 2
\f[C]strik(6df)\f[] outputs s̶t̶r̶i̶k̶e̶d̶ ̶o̶u̶t̶ struck out text.
.IP \[bu] 2
\f[C]rot13(6df)\f[] rotates the Latin letters in its input.
.IP \[bu] 2
\f[C]xyzzy(6df)\f[] teleports to a marked location on the filesystem.
.IP \[bu] 2
\f[C]zs(6df)\f[] prefixes \[lq]z\[rq] case\-appropriately to every
occurrence of \[lq]s\[rq] in the text on its standard input.
.SS Manuals
.PP
The \f[C]install\-bin\f[] and \f[C]install\-games\f[] targets install
manuals for each script they install.
If you want to use the manuals, you may need to add
\f[C]~/.local/share/man\f[] to your \f[C]~/.manpath\f[] or
\f[C]/etc/manpath\f[] configuration, depending on your system.
.SS Testing
.PP
You can check that both sets of shell scripts are syntactically correct
with \f[C]make\ check\-bash\f[], \f[C]make\ check\-sh\f[], or
\f[C]make\ check\f[] for everything including the scripts in
\f[C]bin\f[] and \f[C]games\f[].
There's no proper test suite for the actual functionality (yet).
.PP
There are also optional \f[C]lint\f[] targets, if you have the
appropriate tools available to run them:
.IP \[bu] 2
ShellCheck (https://www.shellcheck.net/):
.RS 2
.IP \[bu] 2
\f[C]lint\-bash\f[]
.IP \[bu] 2
\f[C]lint\-bin\f[]
.IP \[bu] 2
\f[C]lint\-games\f[]
.IP \[bu] 2
\f[C]lint\-ksh\f[]
.IP \[bu] 2
\f[C]lint\-sh\f[]
.IP \[bu] 2
\f[C]lint\-xinit\f[]
.RE
.IP \[bu] 2
Perl::Critic (http://perlcritic.com/):
.RS 2
.IP \[bu] 2
\f[C]lint\-urxvt\f[]
.RE
.IP \[bu] 2
Vint (https://github.com/Kuniwak/vint):
.RS 2
.IP \[bu] 2
\f[C]lint\-vim\f[]
.RE
.SS Known issues
.PP
See ISSUES.markdown.
.SS License
.PP
Public domain; see the included \f[C]UNLICENSE\f[] file.
It's just configuration and simple scripts, so do whatever you like with
it if any of it's useful to you.
If you're feeling generous, please join and/or donate to a free software
advocacy group, and let me know you did it because of this project:
.IP \[bu] 2
Free Software Foundation (https://www.fsf.org/)
.IP \[bu] 2
Software in the Public Interest (https://www.spi-inc.org/)
.IP \[bu] 2
FreeBSD Foundation (https://www.freebsdfoundation.org/)
.IP \[bu] 2
OpenBSD Foundation (http://www.openbsdfoundation.org/)
.SH AUTHORS
Tom Ryder.