1[vset VERSION 0.1]
2[manpage_begin textutil::patch n [vset VERSION]]
3[keywords {diff, unified format} {unified format diff} patch {diff -ruN} git fossil]
4[moddesc   {Text and string utilities}]
5[titledesc {Application of uni-diff patches to directory trees}]
6[category  {Text processing}]
7[require Tcl 8.2]
8[require textutil::patch [opt [vset VERSION]]]
9[description]
10
11This package provides a single command which applies a patch in
12[uri \
13	https://www.gnu.org/software/diffutils/manual/html_node/Detailed-Unified.html \
14	{unified format}]
15to a directory tree.
16
17[list_begin definitions]
18
19[call [cmd ::textutil::patch::apply] [arg basedirectory] \
20	[arg striplevel] [arg patch] [arg reportcmd]]
21
22Applies the [arg patch] (text of the path, not file) to the files in
23the [arg basedirectory] using the specified [arg striplevel].
24
25The result of the command is the empty string.
26
27[para] The [arg striplevel] argument is equivalent to option
28[option -p] of the [syscmd patch] command.
29
30[para] Errors are thrown when the [arg patch] does not parse, and
31nothing is done to the files in [arg basedirectory].
32
33[para] All activities during the application of the patch, including
34the inability to apply a hunk are reported through the command prefix
35[arg reportcmd] instead. Files with problems are left unchanged.  Note
36however that this does [strong {not prevent}] changes to files with no
37problems, before and after the problematic file(s).
38
39[para] The command prefix is called in 3 possible forms:
40
41[list_begin definitions]
42
43[call [cmd {{*}reportcmd}] [method apply] [arg filename]]
44
45The caller begins operation on file [arg fname], applying all hunks
46collected for said file.
47
48[call [cmd {{*}reportcmd}] [method fail] [arg filename] [arg hunk] [arg expected] [arg seen]]
49
50Application of hunk number [arg hunk] of file [arg filename] has failed.
51The command expected to find the text [arg expected], and saw [arg seen] instead.
52
53[call [cmd {{*}reportcmd}] [method fail-already] [arg filename] [arg hunk]]
54
55Application of hunk number [arg hunk] of file [arg filename] has failed.
56The command believes that this hunk has already been applied to the file.
57
58[list_end]
59[list_end]
60
61[vset CATEGORY textutil]
62[include ../common-text/feedback.inc]
63[manpage_end]
64