Return Option on cache read
[tt.git] / README.md
CommitLineData
3773a4cd
SK
1tt
2==
691c20d1 3A more-unixy [twtxt](https://github.com/buckket/twtxt) client.
3773a4cd 4
6df41218
SK
5[![Build Status](https://travis-ci.org/xandkar/tt.svg?branch=master)](https://travis-ci.org/xandkar/tt)
6
3773a4cd
SK
7Doesn't force you to maintain a master "following" file (the way Twitter does),
8but let's you point it to any follow-file every time it runs.
9
10This means unlimited possibilities for ad-hoc, interesting filtering
11combinations. Especially when paired with
12[process substitution](https://en.wikipedia.org/wiki/Process_substitution).
13
01e4c499
SK
14### long format (default)
15![Screenshot](screenshot-long.jpg)
16
17### short format (CLI option: -s)
18![Screenshot](screenshot-short.jpg)
3773a4cd 19
236a8692 20
3773a4cd
SK
21instructions
22------------
23
24### requirements
6a07fde0
SK
25
26#### manual
3773a4cd
SK
27[Racket](https://download.racket-lang.org/)
28
6a07fde0
SK
29#### package manager
30- Void Linux: `xbps-install racket`
31- Debian: `apt install racket`
32
3773a4cd 33### installation
8676fbce
SK
34`make build && make install` will build and copy `tt` binary into
35`$PREFIX/bin`, where `$PREFIX` defaults to `$HOME`.
3773a4cd 36
0b9f3c2c
SK
37### configuration
38Put your `<nick>` and `<uri>` into `~/.tt/me`. For example, mine is:
39
40```
41$ cat ~/.tt/me
42xandkar https://xandkar.net/twtxt.txt
43```
44It will be used to fill the `User-Agent` header, so that others can tell you're
45reading their twtxts and perhaps read yours. This isn't strictly necessary and
46if omitted, you'll stay anonymous.
47
3773a4cd 48### usage
58b95fe2 49
b79d0368
SK
50 $ tt --help
51 tt [ <option> ... ] <command> [<args>] ...
52 where <option> is one of
53 -d, --debug : Enable debug log level.
54
55 and <command> is one of
56 r, read : Read the timeline (offline operation).
57 d, download : Download the timeline.
58 u, upload : Upload your twtxt file (alias to execute ~/.tt/upload).
59 c, crawl : Discover new peers mentioned by known peers (offline operation).
60
61 --help, -h : Show this help
62 -- : Do not treat any remaining argument as a switch (at this level)
63 Multiple single-letter switches can be combined after one `-'; for
64 example: `-h-' is the same as `-h --'
65
66#### download
67peers' feeds from the Internet:
68
69 $ tt d -h
70 tt download [ <option> ... ] [<file-paths>] ...
71 where <option> is one of
72 -j <njobs>, --jobs <njobs> : Number of concurrent jobs.
73 --help, -h : Show this help
74 -- : Do not treat any remaining argument as a switch (at this level)
75 Multiple single-letter switches can be combined after one `-'; for
76 example: `-h-' is the same as `-h --'
77
78#### read
79your timeline:
80
81 $ tt r -h
82 tt read [ <option> ... ] [<file-paths>] ...
83 where <option> is one of
84 -r, --rev : Reverse displayed timeline order.
85 / -s, --short : Short output format
86 \ -l, --long : Long output format
87 --help, -h : Show this help
88 -- : Do not treat any remaining argument as a switch (at this level)
89 /|\ Brackets indicate mutually exclusive options.
90 Multiple single-letter switches can be combined after one `-'; for
91 example: `-h-' is the same as `-h --'
24f1f64b 92
0b9f3c2c
SK
93`FOLLOW-FILE` contains lines with space-separated nick and twtxt.txt URI, like:
94
95```
96xandkar https://xandkar.net/twtxt.txt
97```
98
fd69d11e
SK
99If omitted, `FOLLOW-FILE` defaults to `~/.tt/peers`.
100
b79d0368 101#### other commands
58b95fe2 102
b79d0368 103 tt <command> -h
236a8692
SK
104
105
106notes
107-----
108
109### LWW downloads
fd69d11e
SK
110Downloaded timelines are stored in `~/.tt/cache/objects/<URL_ENCODED_URL>`, but
111no attempt is made to preserve the previously-downloaded messages - each
112download overrites the previous. One of the implications is that authors can
113edit/delete history without you noticing.
This page took 0.053161 seconds and 4 git commands to generate.