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