tools-reference/diff-and-patch/text.xml


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

<?xml version="1.0" encoding="UTF-8"?>
<guide self="tools-reference/diff-and-patch/">
<chapter>
<title><c>diff</c> and <c>patch</c> — file differences</title>
<body>

<p>
The <c>diff</c> tool is used to create patches (sometimes called
diffs). A patch is a program (computer science definition) which
modifies text across one or more files. Typically these are used for
making changes to source code before it is compiled.
</p>

<p>
The simplest invocation is <c>diff -u oldfile newfile</c>, which will
create a list of differences in unified format between <c>oldfile</c>
and <c>newfile</c>. To operate over directories instead, use <c>diff
-urN olddir newdir</c>.
</p>

<note>
VCS like <c>git</c>,<c>svn</c> or <c>cvs</c> provide built-in diff
functionality (<c>git diff</c>, <c>svn diff</c>, <c>cvs diff</c>)
which may be more helpful.
</note>

<p>
For patches which go in the main tree, use unified (<c>-u</c>)
format. This is generally the best format to use when sending patches
upstream too <d/> however, occasionally you may be asked to provide
context diffs, which are more portable than unifieds (but don't handle
conflicts as cleanly). In this case, use <c>-c</c> rather
than <c>-u</c>. For a verbose guide into patches and patching, see
<uri link="::ebuild-writing/misc-files/patches/"/>.
</p>

<p>
To apply a patch, use <c>patch -pX &lt; whatever.patch</c>,
where <c>X</c> is a number representing the number of path components
which must be removed (typically this is <c>0</c> or <c>1</c>). Within
ebuilds, use the <c>eapply</c> function instead <d/> see
<uri link="::ebuild-writing/functions/src_prepare/eapply/"/>.
</p>

<p>
The <c>diff(1)</c> and <c>patch(1)</c> manual pages provide more information.
</p>

</body>
</chapter>
</guide>