| blob | 0635d08070e20e1f163e9998dab7a202b7933cfd |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect1 id="tsvn-dug-commit">\r
4 <title>Committing Your Changes To The Repository</title>\r
5 <indexterm>\r
6 <primary>commit</primary>\r
7 </indexterm>\r
8 <indexterm>\r
9 <primary>send changes</primary>\r
10 </indexterm>\r
11 <indexterm>\r
12 <primary>check in</primary>\r
13 </indexterm>\r
14 <?dbhh topicname="HIDD_COMMITDLG"?>\r
15 <para>\r
16 Sending the changes you made to your working tree is known as\r
17 <firstterm>committing</firstterm> the changes. you can use\r
18 <menuchoice>\r
19 <guimenu>TortoiseGit</guimenu>\r
20 <guimenuitem>Check for Modifications</guimenuitem>\r
21 </menuchoice>\r
22 first, to see which files have changed locally.\r
23 </para>\r
24 <sect2 id="tsvn-dug-commit-basics">\r
25 <title>The Commit Dialog</title>\r
26 <para>\r
27 If there are no conflicts,\r
28 you are ready to commit your changes. Select any file\r
29 and/or folders you want to commit, then\r
30 <menuchoice>\r
31 <guimenu>TortoiseGit</guimenu>\r
32 <guimenuitem>Commit...</guimenuitem>\r
33 </menuchoice>.\r
34 <figure id="tsvn-dug-commit-dia-1">\r
35 <title>The Commit dialog</title>\r
36 <graphic fileref="../images/Commit.png"/>\r
37 </figure>\r
38 </para>\r
39 <para>\r
40 The commit dialog will show you every changed file,\r
41 including added, deleted and unversioned files. If you don't\r
42 want a changed file to be committed, just uncheck that\r
43 file. If you want to include an unversioned file,\r
44 just check that file to add it to the commit.\r
45 </para>\r
46 <para>\r
47 Default commit dialog just list select paths and their child directory files. \r
48 If you want to list all files of project, you can just click <guilabel>\r
49 Whole Project</guilabel>\r
50 </para>\r
51 <!--\r
52 <para>\r
53 Items which have been switched to a different repository path are\r
54 also indicated using an <literal>(s)</literal> marker. You may have\r
55 switched something while working on a branch and forgotten to switch\r
56 back to trunk. This is your warning sign!\r
57 </para>\r
58 -->\r
59 <!--\r
60 <tip>\r
61 <title>Commit files or folders?</title>\r
62 <para>\r
63 When you commit files, the commit dialog shows only\r
64 the files you have selected. When you commit a folder\r
65 the commit dialog will select the changed files automatically.\r
66 If you forget about a new file you created, committing the\r
67 folder will find it anyway. Committing a folder does <emphasis>not</emphasis>\r
68 mean that every file gets marked as changed; It just makes\r
69 your life easier by doing more work for you.\r
70 </para>\r
71 </tip>\r
72 -->\r
73 <!--\r
74 <para>\r
75 If you have modified files which have been included from a different\r
76 repository using <literal>svn:externals</literal>, those changes cannot\r
77 be included in the same atomic commit. A warning symbol below the file\r
78 list tells you if this has happened, and the tooltip explains that\r
79 those external files have to be committed separately.\r
80 </para>\r
81 -->\r
82 <tip>\r
83 <title>Many unversioned files in the commit dialog</title>\r
84 <para>\r
85 If you think that the commit dialog shows you too\r
86 many unversioned (e.g. compiler generated or editor backup)\r
87 files, there are several ways to handle this. You can:\r
88 <itemizedlist>\r
89 <!--\r
90 <listitem>\r
91 <para>\r
92 add the file (or a wildcard extension)\r
93 to the list of files to exclude on the settings page.\r
94 This will affect every working tree you have.\r
95 </para>\r
96 </listitem>\r
97 -->\r
98 <listitem>\r
99 <para>\r
100 add the file to the <literal>.gitignore</literal> list\r
101 using\r
102 <menuchoice>\r
103 <guimenu>TortoiseGit</guimenu>\r
104 <guimenuitem>Add to ignore list</guimenuitem>\r
105 </menuchoice>\r
106 <!--\r
107 This will only affect the directory on\r
108 which you set the <literal>svn:ignore</literal> property.\r
109 Using the SVN Property Dialog, you can alter the\r
110 <literal>svn:ignore</literal> property for a directory.\r
111 -->\r
112 </para>\r
113 </listitem>\r
114 </itemizedlist>\r
115 Read <xref linkend="tsvn-dug-ignore"/> for more information. \r
116 </para>\r
117 </tip>\r
118 <para>\r
119 <action>Double clicking</action> on any modified file in the commit\r
120 dialog will launch the external diff tool to show your changes.\r
121 The context menu will give you more options, as shown in the screenshot.\r
122 You can also drag files from here into another application such as a\r
123 text editor or an IDE.\r
124 </para>\r
125 <para>\r
126 You can select or deselect items by clicking on the checkbox to the\r
127 left of the item. For directories you can use <keycap>Shift</keycap>-<action>select</action>\r
128 to make the action recursive.\r
129 </para>\r
130 <para>\r
131 The columns displayed in the bottom pane are customizable. If you\r
132 <action>right click</action> on any column header you will see a\r
133 context menu allowing you to select which columns are displayed.\r
134 You can also change column width by using the drag handle which\r
135 appears when you move the mouse over a column boundary. These\r
136 customizations are preserved, so you will see the same headings\r
137 next time.\r
138 </para>\r
139 <!--\r
140 <para>\r
141 By default when you commit changes, any locks that you hold on files\r
142 are released automatically after the commit succeeds. If you want\r
143 to keep those locks, make sure the <guilabel>Keep locks</guilabel>\r
144 checkbox is checked. The default state of this checkbox is taken\r
145 from the <literal>no_unlock</literal> option in the Git\r
146 configuration file. Read <xref linkend="tsvn-dug-settings-main"/>\r
147 for information on how to edit the Git configuration file.\r
148 </para>\r
149 -->\r
150 <tip>\r
151 <title>Drag and Drop</title>\r
152 <!--\r
153 <para>\r
154 You can drag files into the commit dialog from elsewhere, so\r
155 long as the working trees are checked out from the same repository.\r
156 For example, you may have a huge working tree with several\r
157 explorer windows open to look at distant folders of the\r
158 hierarchy. If you want to avoid committing from the top\r
159 level folder (with a lengthy folder crawl to check for changes)\r
160 you can open the commit dialog for one folder and drag in items\r
161 from the other windows to include within the same atomic commit.\r
162 </para>\r
163 <para>\r
164 You can drag unversioned files which reside within a working tree\r
165 into the commit dialog, and they will be Git added automatically.\r
166 </para>\r
167 -->\r
168 </tip>\r
169 <!--\r
170 <tip>\r
171 <title>Repairing External Renames</title>\r
172 <para>\r
173 Sometimes files get renamed outside of Git, and they show up\r
174 in the file list as a missing file and an unversioned file. To avoid\r
175 losing the history you need to notify Git about the connection.\r
176 Simply select both the old name (missing) and the new name (unversioned)\r
177 and use\r
178 <menuchoice>\r
179 <guimenu>Context Menu</guimenu>\r
180 <guimenuitem>Repair Move</guimenuitem>\r
181 </menuchoice>\r
182 to pair the two files as a rename.\r
183 </para>\r
184 </tip>\r
185 -->\r
186 </sect2>\r
187 <!--\r
188 <sect2 id="tsvn-dug-commit-changelists">\r
189 <title>Change Lists</title>\r
190 <para>\r
191 The commit dialog supports Git's changelist feature to help\r
192 with grouping related files together. Find out about this feature\r
193 in <xref linkend="tsvn-dug-changelists"/>.\r
194 </para>\r
195 </sect2>\r
196 -->\r
197 <!--\r
198 <sect2 id="tsvn-dug-commit-ignore">\r
199 <title>Excluding Items from the Commit List</title>\r
200 <para>\r
201 Sometimes you have versioned files that change frequently but that you\r
202 really don't want to commit. Sometimes this indicates a flaw in your\r
203 build process - why are those files versioned? should you be using\r
204 template files? But occasionally it is inevitable. A classic reason\r
205 is that your IDE changes a timestamp in the project file every time\r
206 you build. The project file has to be versioned as it includes all the\r
207 build settings, but it doesn't need to be committed just because the\r
208 timestamp changed.\r
209 </para>\r
210 <para>\r
211 To help out in awkward cases like this, we have reserved a changelist\r
212 called <literal>ignore-on-commit</literal>. Any file added to this\r
213 changelist will automatically be unchecked in the commit dialog.\r
214 You can still commit changes, but you have to select it manually\r
215 in the commit dialog.\r
216 </para>\r
217 </sect2>\r
218 -->\r
219 <sect2 id="tsvn-dug-commit-restore">\r
220 <title>Commit only parts of files</title>\r
221 <para>\r
222 Sometimes you want to only commit parts of the changes\r
223 you made to a file. Such a situation usually happens when\r
224 you're working on something but then an urgent fix needs\r
225 to be committed, and that fix happens to be in the same file\r
226 you're working on.\r
227 </para>\r
228 <para>\r
229 <action>right click</action> on the file and use\r
230 <menuchoice>\r
231 <guimenu>Context Menu</guimenu>\r
232 <guimenuitem>Restore after commit</guimenuitem>\r
233 </menuchoice>.\r
234 This will create a copy of the file as it is. Then you\r
235 can edit the file, e.g. in TortoiseMerge and undo all\r
236 the changes you don't want to commit. After saving those\r
237 changes you can commit the file.\r
238 </para>\r
239 <para>\r
240 After the commit is done, the copy of the file is restored\r
241 automatically, and you have the file with all your modifications\r
242 that were not committed back.\r
243 </para>\r
244 </sect2>\r
245 <sect2 id="tsvn-dug-commit-log">\r
246 <title>Commit Log Messages</title>\r
247 <para>\r
248 Be sure to enter a log message which describes the changes you are\r
249 committing. This will help you to see what happened and when, as you\r
250 browse through the project log messages at a later date. The message\r
251 can be as long or as brief as you like; many projects have guidelines\r
252 for what should be included, the language to use, and sometimes even\r
253 a strict format.\r
254 </para>\r
255 <para>\r
256 You can apply simple formatting to your log messages using a convention\r
257 similar to that used within emails.\r
258 To apply styling to <literal>text</literal>, use\r
259 <literal>*text*</literal> for bold,\r
260 <literal>_text_</literal> for underlining, and\r
261 <literal>^text^</literal> for italics.\r
262 </para>\r
263 <para>\r
264 <figure id="tsvn-dug-commit-dia-2">\r
265 <title>The Commit Dialog Spellchecker</title>\r
266 <graphic fileref="../images/CommitSpellcheck.png"/>\r
267 </figure>\r
268 TortoiseGit includes a spellchecker to help you get your log messages\r
269 right. This will highlight any mis-spelled words. Use the context menu\r
270 to access the suggested corrections. Of course, it doesn't know\r
271 <emphasis>every</emphasis> technical term that you do, so correctly\r
272 spelt words will sometimes show up as errors. But don't worry. You can\r
273 just add them to your personal dictionary using the context menu.\r
274 </para>\r
275 <para>\r
276 The log message window also includes a filename and function auto-completion\r
277 facility. This uses regular expressions to extract class and function names\r
278 from the (text) files you are committing, as well as the filenames themselves.\r
279 If a word you are typing matches anything in the list (after you have typed at\r
280 least 3 characters, or pressed <keycap>Ctrl+Space</keycap>),\r
281 a drop-down appears allowing you to select the full name.\r
282 The regular expressions supplied with TortoiseGit are held in the TortoiseGit\r
283 installation <filename>bin</filename> folder. You can also define your own\r
284 regexes and store them in <filename>%APPDATA%\TortoiseGit\autolist.txt</filename>.\r
285 Of course your private autolist will not be overwritten when you update your\r
286 installation of TortoiseGit. If you are unfamiliar with regular expressions,\r
287 take a look at the introduction at\r
288 <ulink url="http://en.wikipedia.org/wiki/Regular_expression">\r
289 <citetitle>http://en.wikipedia.org/wiki/Regular_expression</citetitle>\r
290 </ulink>,\r
291 and the online documentation and tutorial at\r
292 <ulink url="http://www.regular-expressions.info/">\r
293 <citetitle>http://www.regular-expressions.info/</citetitle>\r
294 </ulink>.\r
295 </para>\r
296 <!--\r
297 <para>\r
298 You can re-use previously entered log messages. Just click on\r
299 <guibutton>Recent messages</guibutton> to view a list of the last few\r
300 messages you entered for this working tree. The number of stored messages\r
301 can be customized in the TortoiseGit settings dialog.\r
302 </para>\r
303 -->\r
304 <para>\r
305 You can add your name and email address to end of log message by click\r
306 <guibutton>Sign</guibutton>\r
307 </para>\r
308 <!--\r
309 <para>\r
310 You can clear all stored commit messages from the <guilabel>Saved data</guilabel>\r
311 page of TortoiseGit's settings, or you can clear individual messages from\r
312 within the <guilabel>Recent messages</guilabel> dialog using the\r
313 <keycap>Delete</keycap> key.\r
314 </para>\r
315 -->\r
316 <para>\r
317 If you want to include the checked paths in your log message, you can use\r
318 the command\r
319 <menuchoice>\r
320 <guimenu>Context Menu</guimenu>\r
321 <guimenuitem>Paste filename list</guimenuitem>\r
322 </menuchoice>\r
323 in the edit control.\r
324 </para>\r
325 <para>\r
326 Another way to insert the paths into the log message is to simply\r
327 drag the files from the file list onto the edit control.\r
328 </para>\r
329 <!--\r
330 <tip>\r
331 <title>Special Folder Properties</title>\r
332 <para>\r
333 There are several special folder properties which can be used to\r
334 help give more control over the formatting of commit log messages and\r
335 the language used by the spellchecker module.\r
336 Read <xref linkend="tsvn-dug-propertypage"/> for further information.\r
337 </para>\r
338 </tip>\r
339 -->\r
340 <tip>\r
341 <title>Integration with Bug Tracking Tools</title>\r
342 <para>\r
343 If you have activated the bug tracking system, you can set one or more \r
344 Issues in the <guilabel>Bug-ID / Issue-Nr:</guilabel> text box. Multiple\r
345 issues should be comma separated. Alternatively, if you are using\r
346 regex-based bug tracking support, just add your issue references\r
347 as part of the log message.\r
348 Learn more in <xref linkend="tsvn-dug-bugtracker"/>.\r
349 </para>\r
350 </tip>\r
351 </sect2>\r
352 <!--\r
353 <sect2 id="tsvn-dug-commit-progress">\r
354 <title>Commit Progress</title>\r
355 <para>\r
356 After pressing <guibutton>OK</guibutton>, a dialog appears displaying\r
357 the progress of the commit.\r
358 <figure id="tsvn-dug-commit-dia-3">\r
359 <title>The Progress dialog showing a commit in progress</title>\r
360 <graphic fileref="../images/CommitProgress.png"/>\r
361 </figure>\r
362 </para>\r
363 <para>\r
364 The progress dialog uses colour coding to highlight different\r
365 commit actions\r
366 <variablelist>\r
367 <varlistentry>\r
368 <term>Blue</term>\r
369 <listitem>\r
370 <para>\r
371 Committing a modification.\r
372 </para>\r
373 </listitem>\r
374 </varlistentry>\r
375 <varlistentry>\r
376 <term>Purple</term>\r
377 <listitem>\r
378 <para>\r
379 Committing a new addition.\r
380 </para>\r
381 </listitem>\r
382 </varlistentry>\r
383 <varlistentry>\r
384 <term>Dark red</term>\r
385 <listitem>\r
386 <para>\r
387 Committing a deletion or a replacement.\r
388 </para>\r
389 </listitem>\r
390 </varlistentry>\r
391 <varlistentry>\r
392 <term>Black</term>\r
393 <listitem>\r
394 <para>\r
395 All other items.\r
396 </para>\r
397 </listitem>\r
398 </varlistentry>\r
399 </variablelist>\r
400 </para>\r
401 <para>\r
402 This is the default colour scheme, but you can customise those colours\r
403 using the settings dialog.\r
404 Read <xref linkend="tsvn-dug-settings-colours"/> for more information.\r
405 </para>\r
406 </sect2>\r
407 -->\r
408 </sect1>\r