| blob | 4f15c68c0e57814693cceb8359a18607bc74cbf8 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect1 id="tgit-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="tgit-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="tgit-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 <tip>\r
52 <title>Many unversioned files in the commit dialog</title>\r
53 <para>\r
54 If you think that the commit dialog shows you too\r
55 many unversioned (e.g. compiler generated or editor backup)\r
56 files, there are several ways to handle this. You can:\r
57 <itemizedlist>\r
58 <!--\r
59 <listitem>\r
60 <para>\r
61 add the file (or a wildcard extension)\r
62 to the list of files to exclude on the settings page.\r
63 This will affect every working tree you have.\r
64 </para>\r
65 </listitem>\r
66 -->\r
67 <listitem>\r
68 <para>\r
69 add the file to the <literal>.gitignore</literal> list\r
70 using\r
71 <menuchoice>\r
72 <guimenu>TortoiseGit</guimenu>\r
73 <guimenuitem>Add to ignore list</guimenuitem>\r
74 </menuchoice>\r
75 </para>\r
76 </listitem>\r
77 </itemizedlist>\r
78 Read <xref linkend="tgit-dug-ignore"/> for more information. \r
79 </para>\r
80 </tip>\r
81 <para>\r
82 <action>Double clicking</action> on any modified file in the commit\r
83 dialog will launch the external diff tool to show your changes.\r
84 The context menu will give you more options, as shown in the screenshot.\r
85 You can also drag files from here into another application such as a\r
86 text editor or an IDE.\r
87 </para>\r
88 <para>\r
89 You can select or deselect items by clicking on the checkbox to the\r
90 left of the item.\r
91 </para>\r
92 <para>\r
93 The columns displayed in the bottom pane are customizable. If you\r
94 <action>right click</action> on any column header you will see a\r
95 context menu allowing you to select which columns are displayed.\r
96 You can also change column width by using the drag handle which\r
97 appears when you move the mouse over a column boundary. These\r
98 customizations are preserved, so you will see the same headings\r
99 next time.\r
100 </para>\r
101 <!--\r
102 <tip>\r
103 <title>Drag and Drop</title>\r
104 <para>\r
105 You can drag files into the commit dialog from elsewhere, so\r
106 long as the working trees are checked out from the same repository.\r
107 For example, you may have a huge working tree with several\r
108 explorer windows open to look at distant folders of the\r
109 hierarchy. If you want to avoid committing from the top\r
110 level folder (with a lengthy folder crawl to check for changes)\r
111 you can open the commit dialog for one folder and drag in items\r
112 from the other windows to include within the same atomic commit.\r
113 </para>\r
114 <para>\r
115 You can drag unversioned files which reside within a working tree\r
116 into the commit dialog, and they will be Git added automatically.\r
117 </para>\r
118 </tip>\r
119 -->\r
120 </sect2>\r
121 <!--\r
122 <sect2 id="tgit-dug-commit-changelists">\r
123 <title>Change Lists</title>\r
124 <para>\r
125 The commit dialog supports Git's changelist feature to help\r
126 with grouping related files together. Find out about this feature\r
127 in <xref linkend="tgit-dug-changelists"/>.\r
128 </para>\r
129 </sect2>\r
130 -->\r
131 <!--\r
132 <sect2 id="tgit-dug-commit-ignore">\r
133 <title>Excluding Items from the Commit List</title>\r
134 <para>\r
135 Sometimes you have versioned files that change frequently but that you\r
136 really don't want to commit. Sometimes this indicates a flaw in your\r
137 build process - why are those files versioned? should you be using\r
138 template files? But occasionally it is inevitable. A classic reason\r
139 is that your IDE changes a timestamp in the project file every time\r
140 you build. The project file has to be versioned as it includes all the\r
141 build settings, but it doesn't need to be committed just because the\r
142 timestamp changed.\r
143 </para>\r
144 <para>\r
145 To help out in awkward cases like this, we have reserved a changelist\r
146 called <literal>ignore-on-commit</literal>. Any file added to this\r
147 changelist will automatically be unchecked in the commit dialog.\r
148 You can still commit changes, but you have to select it manually\r
149 in the commit dialog.\r
150 </para>\r
151 </sect2>\r
152 -->\r
153 <sect2 id="tgit-dug-commit-restore">\r
154 <title>Commit only parts of files</title>\r
155 <para>\r
156 Sometimes you want to only commit parts of the changes\r
157 you made to a file. Such a situation usually happens when\r
158 you're working on something but then an urgent fix needs\r
159 to be committed, and that fix happens to be in the same file\r
160 you're working on.\r
161 </para>\r
162 <para>\r
163 <action>right click</action> on the file and use\r
164 <menuchoice>\r
165 <guimenu>Context Menu</guimenu>\r
166 <guimenuitem>Restore after commit</guimenuitem>\r
167 </menuchoice>.\r
168 This will create a copy of the file as it is. Then you\r
169 can edit the file, e.g. in TortoiseGitMerge and undo all\r
170 the changes you don't want to commit. After saving those\r
171 changes you can commit the file.\r
172 <tip>\r
173 <title>Using TortoiseGitMerge</title>\r
174 <para>\r
175 If you use TortoiseGitMerge to edit the file, you can either edit\r
176 the changes as you're used to, or mark\r
177 all the changes that you want to include. <action>right click</action>\r
178 on a modified block and use\r
179 <menuchoice>\r
180 <guimenu>Context Menu</guimenu>\r
181 <guimenuitem>Mark this block</guimenuitem>\r
182 </menuchoice>\r
183 to include that change.\r
184 Finally <action>right click</action>\r
185 and use\r
186 <menuchoice>\r
187 <guimenu>Context Menu</guimenu>\r
188 <guimenuitem>Use left file except marked blocks</guimenuitem>\r
189 </menuchoice>\r
190 which will invert your changes (unmarked blocks) that you\r
191 don't want to them to appear in current commit.\r
192 </para>\r
193 </tip>\r
194 </para>\r
195 <para>\r
196 After the commit is done, the copy of the file is restored\r
197 automatically, and you have the file with all your modifications\r
198 that were not committed back.\r
199 </para>\r
200 </sect2>\r
201 <sect2 id="tgit-dug-commit-log">\r
202 <title>Commit Log Messages</title>\r
203 <para>\r
204 Be sure to enter a log message which describes the changes you are\r
205 committing. This will help you to see what happened and when, as you\r
206 browse through the project log messages at a later date. The message\r
207 can be as long or as brief as you like; many projects have guidelines\r
208 for what should be included, the language to use, and sometimes even\r
209 a strict format.\r
210 </para>\r
211 <para>\r
212 You can apply simple formatting to your log messages using a convention\r
213 similar to that used within emails.\r
214 To apply styling to <literal>text</literal>, use\r
215 <literal>*text*</literal> for bold,\r
216 <literal>_text_</literal> for underlining, and\r
217 <literal>^text^</literal> for italics.\r
218 </para>\r
219 <para>\r
220 <figure id="tgit-dug-commit-dia-2">\r
221 <title>The Commit Dialog Spellchecker</title>\r
222 <graphic fileref="../images/CommitSpellcheck.png"/>\r
223 </figure>\r
224 TortoiseGit includes a spellchecker to help you get your log messages\r
225 right. This will highlight any mis-spelled words. Use the context menu\r
226 to access the suggested corrections. Of course, it doesn't know\r
227 <emphasis>every</emphasis> technical term that you do, so correctly\r
228 spelt words will sometimes show up as errors. But don't worry. You can\r
229 just add them to your personal dictionary using the context menu.\r
230 </para>\r
231 <para>\r
232 The log message window also includes a filename and function auto-completion\r
233 facility. This uses regular expressions to extract class and function names\r
234 from the (text) files you are committing, as well as the filenames themselves.\r
235 If a word you are typing matches anything in the list (after you have typed at\r
236 least 3 characters, or pressed <keycap>Ctrl+Space</keycap>),\r
237 a drop-down appears allowing you to select the full name.\r
238 The regular expressions supplied with TortoiseGit are held in the TortoiseGit\r
239 installation <filename>bin</filename> folder. You can also define your own\r
240 regexes and store them in <filename>%APPDATA%\TortoiseGit\autolist.txt</filename>.\r
241 Of course your private autolist will not be overwritten when you update your\r
242 installation of TortoiseGit. If you are unfamiliar with regular expressions,\r
243 take a look at the introduction at\r
244 <ulink url="https://en.wikipedia.org/wiki/Regular_expression">\r
245 <citetitle>https://en.wikipedia.org/wiki/Regular_expression</citetitle>\r
246 </ulink>,\r
247 and the online documentation and tutorial at\r
248 <ulink url="http://www.regular-expressions.info/">\r
249 <citetitle>http://www.regular-expressions.info/</citetitle>\r
250 </ulink>.\r
251 </para>\r
252 <para>\r
253 Getting the regex just right can be tricky, so to help you sort out a\r
254 suitable expression there is a test dialog which allows you to enter\r
255 an expression and then type in filenames to test it against.\r
256 Start it from the command prompt using the command\r
257 <literal>TortoiseGitProc.exe /command:autotexttest</literal>.\r
258 </para>\r
259 <para>\r
260 You can re-use previously entered log messages. Just use the command\r
261 <menuchoice>\r
262 <guimenu>Context Menu</guimenu>\r
263 <guimenuitem>Paste Recent messages</guimenuitem>\r
264 </menuchoice>\r
265 to view a list of the last few\r
266 messages you entered for this working tree. The number of stored messages\r
267 can be customized in the TortoiseGit settings dialog.\r
268 </para>\r
269 <para>\r
270 The log message window also includes a commit message snippet facility.\r
271 These snippets are shown in the autocomplete dropdown once you type\r
272 a snippet shortcut, and selecting the snippet in the autocomplete dropdown\r
273 then inserts the full text of the snippet.\r
274 The snippets supplied with TortoiseGit are held in the TortoiseGit\r
275 installation <filename>bin</filename> folder. You can also define your own\r
276 snippets and store them in <filename>%APPDATA%\TortoiseGit\snippet.txt</filename>.\r
277 # is the comment character. Use escape sequences \t \r \n \\.\r
278 </para>\r
279 <para>\r
280 You can add your name and email address to end of log message by click\r
281 <guibutton>Sign</guibutton>\r
282 </para>\r
283 <para>\r
284 You can clear all stored commit messages from the <guilabel>Saved data</guilabel>\r
285 page of TortoiseGit's settings, or you can clear individual messages from\r
286 within the <guilabel>Recent messages</guilabel> dialog using the\r
287 <keycap>Delete</keycap> key.\r
288 </para>\r
289 <para>\r
290 If you want to include the checked paths in your log message, you can use\r
291 the command\r
292 <menuchoice>\r
293 <guimenu>Context Menu</guimenu>\r
294 <guimenuitem>Paste filename list</guimenuitem>\r
295 </menuchoice>\r
296 in the edit control.\r
297 </para>\r
298 <!--\r
299 <para>\r
300 Another way to insert the paths into the log message is to simply\r
301 drag the files from the file list onto the edit control.\r
302 </para>\r
303 -->\r
304 <tip>\r
305 <title>Using keyboard</title>\r
306 <para>\r
307 You can access the <guilabel>OK</guilabel> button from keyboard by pressing <keycap>Ctrl+return</keycap>.\r
308 </para>\r
309 </tip>\r
310 <tip>\r
311 <title>Integration with Bug Tracking Tools</title>\r
312 <para>\r
313 If you have activated the bug tracking system, you can set one or more \r
314 Issues in the <guilabel>Bug-ID / Issue-Nr:</guilabel> text box. Multiple\r
315 issues should be comma separated. Alternatively, if you are using\r
316 regex-based bug tracking support, just add your issue references\r
317 as part of the log message.\r
318 Learn more in <xref linkend="tgit-dug-bugtracker"/>.\r
319 </para>\r
320 </tip>\r
321 </sect2>\r
322 <!--\r
323 <sect2 id="tgit-dug-commit-progress">\r
324 <title>Commit Progress</title>\r
325 <para>\r
326 After pressing <guibutton>OK</guibutton>, a dialog appears displaying\r
327 the progress of the commit.\r
328 <figure id="tgit-dug-commit-dia-3">\r
329 <title>The Progress dialog showing a commit in progress</title>\r
330 <graphic fileref="../images/CommitProgress.png"/>\r
331 </figure>\r
332 </para>\r
333 <para>\r
334 The progress dialog uses colour coding to highlight different\r
335 commit actions\r
336 <variablelist>\r
337 <varlistentry>\r
338 <term>Blue</term>\r
339 <listitem>\r
340 <para>\r
341 Committing a modification.\r
342 </para>\r
343 </listitem>\r
344 </varlistentry>\r
345 <varlistentry>\r
346 <term>Purple</term>\r
347 <listitem>\r
348 <para>\r
349 Committing a new addition.\r
350 </para>\r
351 </listitem>\r
352 </varlistentry>\r
353 <varlistentry>\r
354 <term>Dark red</term>\r
355 <listitem>\r
356 <para>\r
357 Committing a deletion or a replacement.\r
358 </para>\r
359 </listitem>\r
360 </varlistentry>\r
361 <varlistentry>\r
362 <term>Black</term>\r
363 <listitem>\r
364 <para>\r
365 All other items.\r
366 </para>\r
367 </listitem>\r
368 </varlistentry>\r
369 </variablelist>\r
370 </para>\r
371 <para>\r
372 This is the default colour scheme, but you can customise those colours\r
373 using the settings dialog.\r
374 Read <xref linkend="tgit-dug-settings-colours"/> for more information.\r
375 </para>\r
376 </sect2>\r
377 -->\r
378 </sect1>\r