1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
\r
3 <sect1 id="tsvn-dug-patch">
\r
4 <title>Creating and Applying Patches</title>
\r
6 <primary>patch</primary>
\r
9 <primary>diff</primary>
\r
12 <primary>unified diff</primary>
\r
14 <?dbhh topicname="HIDD_PATCH"?>
\r
15 <?dbhh topicname="HIDD_CREATEPATCH"?>
\r
17 For open source projects (like this one) everyone has read
\r
18 access to the repository, and anyone can make a contribution
\r
19 to the project. So how are those contributions controlled?
\r
20 If just anyone could commit changes, the project would be permanently
\r
21 unstable and probably permanently broken. In this situation the
\r
22 change is managed by submitting a <firstterm>patch</firstterm> file
\r
23 to the development team, who do have write access.
\r
24 They can review the patch first, and then either submit it to the
\r
25 repository or reject it back to the author.
\r
28 Patch files are simply Unified-Diff files showing the differences
\r
29 between your working copy and the base revision.
\r
31 <sect2 id="tsvn-dug-patch-1">
\r
32 <title>Creating a Patch File</title>
\r
34 First you need to make <emphasis>and test</emphasis> your changes.
\r
35 Then instead of using
\r
37 <guimenu>TortoiseGit</guimenu>
\r
38 <guimenuitem>Commit...</guimenuitem>
\r
40 on the parent folder, you select
\r
42 <guimenu>TortoiseGit</guimenu>
\r
43 <guimenuitem>Create Patch...</guimenuitem>
\r
46 <figure id="tsvn-dug-patch-dia-1">
\r
47 <title>The Create Patch dialog</title>
\r
48 <graphic fileref="../images/CreatePatch.png"/>
\r
51 you can now select the files you want included in the patch,
\r
52 just as you would with a full commit. This will produce a single
\r
53 file containing a summary of all the changes you have made to the
\r
54 selected files since the last update from the repository.
\r
57 The columns in this dialog can be customized in the same way as the
\r
58 columns in the <guilabel>Check for modifications</guilabel> dialog.
\r
59 Read <xref linkend="tsvn-dug-wcstatus-2"/> for further details.
\r
62 You can produce separate patches containing changes to different
\r
63 sets of files. Of course, if you create a patch file, make some more changes
\r
64 to the <emphasis>same</emphasis> files and then create another patch, the
\r
65 second patch file will include <emphasis>both</emphasis> sets of changes.
\r
68 Just save the file using a filename of your choice.
\r
69 Patch files can have any extension you like, but by convention they
\r
70 should use the <filename>.patch</filename> or
\r
71 <filename>.diff</filename> extension.
\r
72 You are now ready to submit your patch file.
\r
75 You can also save the patch to the clipboard instead of to a file.
\r
76 You might want to do this so that you can paste it into an email for
\r
77 review by others. Or if you have two working copies on one machine and
\r
78 you want to transfer changes from one to the other, a patch on the
\r
79 clipboard is a convenient way of doing this.
\r
82 <sect2 id="tsvn-dug-patch-2">
\r
83 <title>Applying a Patch File</title>
\r
85 Patch files are applied to your working copy. This should be done
\r
86 from the same folder level as was used to create the patch.
\r
87 If you are not sure what this is, just look at the first line of
\r
88 the patch file. For example, if the first file being worked on was
\r
89 <filename>doc/source/english/chapter1.xml</filename>
\r
90 and the first line in the patch file is
\r
91 <filename>Index: english/chapter1.xml</filename>
\r
92 then you need to apply the patch to the
\r
93 <filename>doc/source/</filename> folder.
\r
94 However, provided you are in the correct working copy, if you
\r
95 pick the wrong folder level, TortoiseGit will notice and suggest the
\r
99 In order to apply a patch file to your working copy, you need
\r
100 to have at least read access to the repository.
\r
101 The reason for this is that the merge program must
\r
102 reference the changes back to the revision against
\r
103 which they were made by the remote developer.
\r
106 From the context menu for that folder, click on
\r
108 <guimenu>TortoiseGit</guimenu>
\r
109 <guimenuitem>Apply Patch...</guimenuitem>
\r
111 This will bring up a file open dialog allowing you to select the
\r
112 patch file to apply. By default only <filename>.patch</filename>
\r
113 or <filename>.diff</filename>
\r
114 files are shown, but you can opt for <quote>All files</quote>.
\r
115 If you previously saved a patch to the clipboard, you can use
\r
116 <guibutton>Open from clipboard...</guibutton> in the file
\r
120 Alternatively, if the patch file has a <filename>.patch</filename>
\r
121 or <filename>.diff</filename> extension, you can right click on it
\r
122 directly and select
\r
124 <guimenu>TortoiseGit</guimenu>
\r
125 <guimenuitem>Apply Patch...</guimenuitem>
\r
127 In this case you will be prompted to enter a working copy location.
\r
130 These two methods just offer different ways of doing the same thing.
\r
131 With the first method you select the WC and browse to the patch file.
\r
132 With the second you select the patch file and browse to the WC.
\r
135 Once you have selected the patch file and working copy location,
\r
136 TortoiseMerge runs to merge the changes from the patch file
\r
137 with your working copy. A small window lists the files which have
\r
138 been changed. Double click on each one in turn, review the changes
\r
139 and save the merged files.
\r
142 The remote developer's patch has now been applied to your working copy,
\r
143 so you need to commit to allow everyone else to access the changes
\r
144 from the repository.
\r