-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.txt
138 lines (99 loc) · 4.42 KB
/
README.txt
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
ILP(1)
======
slowpoke <[email protected]>
:encoding: utf-8
:doctype: manpage
NAME
----
ilp - a tag-based file indexer
SYNOPSIS
--------
ilp <subcommand> [<args>]
ilp -i
DESCRIPTION
-----------
ilp is a command-line utility which indexes files, and organizes them
with tags. It will not touch the files on disk, but instead keep track of them
in a database, much like the mlocate utility found on many UNIX or UNIX-like
systems. To uniquely identify a file, ilp stores it as a hash of its
contents.
OPTIONS
-------
<subcommand>::
All functionality of ilp is implemented in subcommands, similar to
git or other VCS. See 'SUBCOMMANDS' for an overview, or use the command
"help".
-i::
Start an interactive shell, where you can issue subcommands directly.
SUBCOMMANDS
-----------
Much like a VCS such as git, ilp does all the work with various
subcommands. You can either issue them as an argument to the command line
utility, or start an interactive shell with '-i' and issue them directly.
ilp index [-r] <path> [<path>...]::
Add one or more files to the index. The '-r' switch turns on recursive
indexing, in which case <path> can be either a file or directory, and will
add all files below a given directory to the index.
ilp forget [-r] <path> [<path>...]::
Counterpart to the *index* subcommand. Removes files from the index.
Correspondingly, '-r' turns on recursive removing.
ilp tag [-r] <path> <tag> [<tag>...]::
Tag a file with one or more tags. Similar to *index* and *forget*, '-r' will
apply the tags recursively to all files below a given directory.
ilp untag [-r] <path> <tag> [<tag>...]::
Counterpart to tag. Remove tags from a file. '-r' works the same way.
ilp deltag <tag> [<tag>...]::
Delete tags from the database. Note that tags are automatically created when
first used, so this command has no counterpart.
ilp list <what>::
List items on the index. <what> can be 'files' or 'tags'.
ilp info [-t] <what>::
Get info on files or tags. Since filenames and tags can't meaningfully be
differentiated, '-t' ('--tag') needs to be passed if information on a tag is
wanted.
ilp search <query>::
Search files on the index. See 'SEARCH QUERIES' for how a query works.
ilp clear [-y]::
Purge the database. This won't do anything unless '-y' ('--yes') is passed.
SEARCH QUERIES
--------------
ilp uses a simple DSL for search queries, which is based on basic set
operations. It requires a bit of understanding about how tagging in ilp
works. If you just want a quick start (it might be all you need, it's rather
intuitive already), see 'EXAMPLE QUERIES'.
Basically, every tag is regarded as a set of all files it is tagging. That might
sound counterintuitive at first (because you would probably expect the relation
to be the other way round), but makes searching through tagged files incredibly
easy, yet powerful - because every operation on a set results in a new set, on
which more operations can be applied. Think of it in terms of Venn diagrams.
For example, if you want to have all files which are tagged both "foo" and
"bar", you'd simply do a logical and on the two sets, and the resulting set is
your wanted result.
This works analogously (and intuitively!) with logical or and not. Even
exclusive or (xor) works, and is quite useful, too - you can use it to find all
files which are either tagged "foo" or "bar", but not both.
Here's a simple overview of the language in Pseudo-BNFL:
<query> := [<operator>] <tag> [<query>]
<operator> := "or" | "and" | "not" | "xor"
EXAMPLE QUERIES
~~~~~~~~~~~~~~~
A simple search query might look like
foo and bar
or
foo not bar
Something more complex could be
foo xor bar not baz spam
Notice that if you just write multiple tags, the last given operator is always
implied. The query could have been written explicitly as
foo xor bar not baz not spam
If no operator is given at all, "or" is implied. That means
search for "foo bar" is the same as searching for "foo or bar" (or even "or foo
or bar").
TRIVIA
------
If you have wondered what ilp stands for, its an acronym for Index Librorum
Prohibitorum - the infamous (and since 1966 defunct) list of books prohibited by
the Vatican. It's really just the first thing that came to mind in relation to
indexing files, and "ilp" sounded catchy and is short to type. Besides, *omnia
dicta fortiora si dicta Latina* ("everything sounds more impressive when said in
Latin").