]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/lei-p2q.pod
ipc: drop unused $args from ->ipc_worker_stop
[public-inbox.git] / Documentation / lei-p2q.pod
1 =head1 NAME
2
3 lei-p2q - use a patch to generate a lei-q query
4
5 =head1 SYNOPSIS
6
7 lei p2q [OPTIONS] (FILE|COMMIT)
8
9 lei p2q [OPTIONS] (--stdin|-)
10
11 =head1 DESCRIPTION
12
13 Given a patch, create a query that can be fed on stdin to L<lei-q(1)>.
14 This is useful for mapping the patch to associated messages of an
15 inbox.
16
17 The patch can be provided on stdin or as a file.  Alternatively, when
18 an argument is given that does not point to an existing file, it is
19 taken as a reference to a commit in the current git repository, and
20 L<git-format-patch(1)> is used to generate the patch.
21
22 =head1 OPTIONS
23
24 =over
25
26 =item -w PREFIX[,PREFIX]
27
28 =item --want=PREFIX[,PREFIX]
29
30 Search prefixes to use.  C<dfpost> (post-image git blob ID) and C<dfn>
31 (file names from the diff) are the most useful.  Other available
32 values are C<dfa>, C<dfb>, C<dfctx>, C<dfhh>, and C<dfpre>.
33
34 =for comment
35 TODO: Put a table of prefixes somewhere and reference that (at least
36 here and in lei-q)?
37
38 Appending an integer to C<dfpost> or C<dfpre> indicates a minimum ID
39 length, and the generated query will be for that value up through the
40 default abbreviation length.  For example, if the repository's
41 C<core.abbrev> is set to C<auto> and git calculates the default
42 abbreviation length as 7, C<dfpost6> will expand a post-image blob ID
43 of e7b4b32 (seven characters) into C<dfpost:e7b4b32 OR dfpost:e7b4b3>.
44
45 This option may be given multiple times.
46
47 Default: C<dfpost7>
48
49 =item --stdin
50
51 Read message from stdin.  This is implicit if no arguments are given
52 and stdin is a pipe or regular file.
53
54 =item --debug
55
56 Dump output that shows the information collected for every prefix.
57 This information can be useful for seeing how a patch is processed,
58 but the format should not be considered stable.
59
60 =item --uri
61
62 URI escape output for interacting with HTTP(S) public-inbox instances.
63
64 =item -q
65
66 =item --quiet
67
68 Suppress feedback messages.
69
70 =back
71
72 =head1 EXAMPLES
73
74   # to search for all threads which touch a given thread:
75   lei p2q $COMMIT_OID | lei q -t -o /tmp/results
76
77   # to view results on a remote HTTP(S) public-inbox instance
78   $BROWSER https://example.com/pub-inbox/?q=$(lei p2q --uri $COMMIT_OID)
79
80   # to view unapplied patches for a given $FILE from the past year:
81   echo \( rt:last.year.. AND dfn:$FILE \) AND NOT \( \
82         $(git log -p --pretty=mboxrd --since=last.year $FILE |
83                 lei p2q -F mboxrd )
84         \) | lei q -o /tmp/unapplied
85
86 =head1 CONTACT
87
88 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
89
90 The mail archives are hosted at L<https://public-inbox.org/meta/> and
91 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
92
93 =head1 COPYRIGHT
94
95 Copyright all contributors L<mailto:meta@public-inbox.org>
96
97 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
98
99 =head1 SEE ALSO
100
101 L<lei-q(1)>