1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE appendix SYSTEM "../../dtd/dblite.dtd">
\r
3 <appendix id="tsvn-howto" xmlns:xi="http://www.w3.org/2001/XInclude">
\r
4 <title>How Do I...</title>
\r
7 This appendix contains solutions to problems/questions you might
\r
8 have when using TortoiseGit.
\r
11 <sect1 id="tsvn-howto-move">
\r
12 <title>Move/copy a lot of files at once</title>
\r
14 <primary>moving</primary>
\r
17 <primary>rename</primary>
\r
20 <primary>reorganize</primary>
\r
23 Moving/Copying single files can be done by using
\r
25 <guimenu>TortoiseGit</guimenu>
\r
26 <guimenuitem>Rename...</guimenuitem>
\r
28 But if you want to move/copy a lot of files, this way is just
\r
29 too slow and too much work.
\r
32 The recommended way is by <action>right-dragging</action> the files to
\r
33 the new location. Simply <action>right-click</action> on the files you want
\r
34 to move/copy without releasing the mouse button. Then drag the files
\r
35 to the new location and release the mouse button. A context menu will appear
\r
36 where you can either choose
\r
38 <guimenu>Context Menu</guimenu>
\r
39 <guimenuitem>Git Copy versioned files here</guimenuitem>
\r
43 <guimenu>Context Menu</guimenu>
\r
44 <guimenuitem>Git Move versioned files here</guimenuitem>
\r
50 <videodata fileref="images/svn_move.swf" format="SWF" contentwidth="590" contentdepth="290"/>
\r
53 <imagedata fileref="images/svn_move.png"/>
\r
58 <sect1 id="tsvn-howto-minlogmsgsize">
\r
59 <title>Force users to enter a log message</title>
\r
61 <primary>log message</primary>
\r
64 <primary>commit message</primary>
\r
67 <primary>empty message</primary>
\r
70 There are two ways to prevent users from committing with an empty
\r
71 log message. One is specific to TortoiseGit, the other works for
\r
72 all Git clients, but requires access to the server directly.
\r
74 <sect2 id="tsvn-howto-minlogsize-hookscript">
\r
75 <title>Hook-script on the server</title>
\r
77 If you have direct access to the repository server, you can install
\r
78 a pre-commit hook script which rejects all commits with an empty
\r
79 or too short log message.
\r
82 In the repository folder on the server, there's a sub-folder
\r
83 <filename>hooks</filename>
\r
84 which contains some example hook scripts you can use. The file
\r
85 <filename>pre-commit.tmpl</filename>
\r
86 contains a sample script which will reject commits if no log message
\r
87 is supplied, or the message is too short.
\r
88 The file also contains comments on how to install/use this script.
\r
89 Just follow the instructions in that file.
\r
92 This method is the recommended way if your users also use other
\r
93 Git clients than TortoiseGit. The drawback is that the commit
\r
94 is rejected by the server and therefore users will get an error
\r
95 message. The client can't know before the commit that it will be
\r
96 rejected. If you want to make TortoiseGit have the <guibutton>OK</guibutton>
\r
97 button disabled until the log message is long enough
\r
98 then please use the method described below.
\r
101 <sect2 id="tsvn-howto-minlogsize-projectproperties">
\r
102 <title>Project properties</title>
\r
104 TortoiseGit uses properties to control some of its features. One of those
\r
105 properties is the <literal>tsvn:logminsize</literal> property.
\r
108 If you set that property on a folder, then TortoiseGit will disable the
\r
109 <guibutton>OK</guibutton> button in all commit dialogs until the user has
\r
110 entered a log message with at least the length specified in the property.
\r
113 For detailed information on those project properties, please refer to
\r
114 <xref linkend="tsvn-dug-propertypage"/>
\r
118 <sect1 id="tsvn-howto-selective-update">
\r
119 <title>Update selected files from the repository</title>
\r
121 <primary>update</primary>
\r
124 Normally you update your working copy using
\r
126 <guimenu>TortoiseGit</guimenu>
\r
127 <guimenuitem>Update</guimenuitem>
\r
129 But if you only want to pick up some new files that a colleague has added
\r
130 without merging in any changes to other files at the same time, you need
\r
131 a different approach.
\r
136 <guimenu>TortoiseGit</guimenu>
\r
137 <guimenuitem>Check for Modifications</guimenuitem>
\r
139 and click on <guibutton>Check repository</guibutton> to see what has changed
\r
140 in the repository. Select the files you want to update locally, then use
\r
141 the context menu to update just those files.
\r
144 <sect1 id="tsvn-howto-rollback">
\r
145 <title>Roll back (Undo) revisions in the repository</title>
\r
147 <primary>rollback</primary>
\r
150 <primary>revert</primary>
\r
153 <primary>undo commit</primary>
\r
156 <primary>undo change</primary>
\r
158 <sect2 id="tsvn-howto-rollback-log">
\r
159 <title>Use the revision log dialog</title>
\r
161 The easiest way to revert the changes from a single revision,
\r
162 or from a range of revisions,
\r
163 is to use the revision log dialog.
\r
164 This is also the method to use of you want to discard recent
\r
165 changes and make an earlier revision the new HEAD.
\r
170 Select the file or folder in which you need to revert
\r
171 the changes. If you want to revert all changes, this
\r
172 should be the top level folder.
\r
179 <guimenu>TortoiseGit</guimenu>
\r
180 <guimenuitem>Show Log</guimenuitem>
\r
182 to display a list of revisions. You may need to use
\r
183 <guibutton>Show All</guibutton> or
\r
184 <guibutton>Next 100</guibutton>
\r
185 to show the revision(s) you are interested in.
\r
190 Select the revision you wish to revert. If you want
\r
191 to undo a range of revisions, select the first one
\r
192 and hold the <keycap>Shift</keycap> key while selecting the last one.
\r
193 Note that for multiple revisions, the range must be
\r
194 unbroken with no gaps.
\r
195 <action>Right click</action> on the selected revision(s),
\r
198 <guimenu>Context Menu</guimenu>
\r
199 <guimenuitem>Revert changes from this revision</guimenuitem>
\r
205 Or if you want to make an earlier revision the new HEAD revision,
\r
206 <action>right click</action> on the selected revision,
\r
209 <guimenu>Context Menu</guimenu>
\r
210 <guimenuitem>Revert to this revision</guimenuitem>
\r
212 This will discard <emphasis>all</emphasis> changes after
\r
213 the selected revision.
\r
218 You have reverted the changes within your working copy.
\r
219 Check the results, then commit the changes.
\r
222 <sect2 id="tsvn-howto-rollback-merge">
\r
223 <title>Use the merge dialog</title>
\r
225 To undo a larger range of revisions, you can use the Merge dialog.
\r
226 The previous method uses merging behind the scenes; this method
\r
227 uses it explicitly.
\r
232 In your working copy select
\r
234 <guimenu>TortoiseGit</guimenu>
\r
235 <guimenuitem>Merge</guimenuitem>
\r
241 In the <guilabel>From:</guilabel> field enter the full
\r
242 folder URL of the branch or tag containing the changes
\r
243 you want to revert in your working copy. This should come
\r
244 up as the default URL.
\r
249 In the <guilabel>From Revision</guilabel> field enter the
\r
250 revision number that you are currently at. If you are
\r
251 sure there is no-one else making changes, you can use the
\r
257 make sure the <guilabel>Use "From:" URL</guilabel>
\r
258 checkbox is checked.
\r
263 In the <guilabel>To Revision</guilabel> field enter the
\r
264 revision number that you want to revert to, namely the one
\r
265 <emphasis>before</emphasis> the first revision to be reverted.
\r
270 Click <guibutton>OK</guibutton> to complete the merge.
\r
275 You have reverted the changes within your working copy.
\r
276 Check the results, then commit the changes.
\r
279 <sect2 id="tsvn-howto-rollback-dumpload">
\r
280 <title>Use <literal>svndumpfilter</literal></title>
\r
282 Since TortoiseGit never loses data, your <quote>rolled back</quote>
\r
283 revisions still exist as intermediate revisions in the repository. Only
\r
284 the HEAD revision was changed to a previous state.
\r
285 If you want to make revisions disappear completely from your
\r
286 repository, erasing all trace that they ever existed, you have
\r
287 to use more extreme measures. Unless there is a really good reason
\r
288 to do this, it is <emphasis>not recommended</emphasis>. One
\r
289 possible reason would be that someone committed a confidential
\r
290 document to a public repository.
\r
293 The only way to remove data from the repository is to use the
\r
294 Git command line tool <literal>svnadmin</literal>.
\r
295 You can find a description of how this works in the
\r
296 <ulink url="http://svnbook.red-bean.com/en/1.5/svn.reposadmin.maint.html">
\r
297 <citetitle>Repository Maintenance</citetitle>
\r
302 <sect1 id="tsvn-howto-compare">
\r
303 <title>Compare two revisions of a file or folder</title>
\r
305 <primary>compare files</primary>
\r
308 <primary>compare folders</primary>
\r
311 <primary>changes</primary>
\r
314 If you want to compare two revisions in an item's history,
\r
315 for example revisions 100 and 200 of the same file, just use
\r
317 <guimenu>TortoiseGit</guimenu>
\r
318 <guimenuitem>Show Log</guimenuitem>
\r
320 to list the revision history for that file. Pick the two revisions
\r
321 you want to compare then use
\r
323 <guimenu>Context Menu</guimenu>
\r
324 <guimenuitem>Compare Revisions</guimenuitem>
\r
328 If you want to compare the same item in two different trees,
\r
329 for example the trunk and a branch, you can use the repository
\r
330 browser to open up both trees, select the file in both places,
\r
333 <guimenu>Context Menu</guimenu>
\r
334 <guimenuitem>Compare Revisions</guimenuitem>
\r
338 If you want to compare two trees to see what has changed,
\r
339 for example the trunk and a tagged release, you can use
\r
341 <guimenu>TortoiseGit</guimenu>
\r
342 <guimenuitem>Revision Graph</guimenuitem>
\r
344 Select the two nodes to compare, then use
\r
346 <guimenu>Context Menu</guimenu>
\r
347 <guimenuitem>Compare HEAD Revisions</guimenuitem>
\r
349 This will show a list of changed files, and you can then select
\r
350 individual files to view the changes in detail.
\r
351 You can also export a tree structure containing all the changed
\r
352 files, or simply a list of all changed files.
\r
353 Read <xref linkend="tsvn-dug-compare-revs"/> for more information.
\r
356 <guimenu>Context Menu</guimenu>
\r
357 <guimenuitem>Unified Diff of HEAD Revisions</guimenuitem>
\r
359 to see a summary of all differences, with minimal context.
\r
362 <sect1 id="tsvn-howto-common-projects">
\r
363 <title>Include a common sub-project</title>
\r
365 <primary>common projects</primary>
\r
368 <primary>externals</primary>
\r
371 <primary>vendor projects</primary>
\r
374 Sometimes you will want to include another project within
\r
375 your working copy, perhaps some library code. You don't
\r
376 want to make a duplicate of this code in your repository
\r
377 because then you would lose connection with the original
\r
378 (and maintained) code. Or maybe you have several projects
\r
379 which share core code. There are at least 3 ways of dealing
\r
382 <sect2 id="tsvn-howto-common-externals">
\r
383 <title>Use svn:externals</title>
\r
385 Set the <literal>svn:externals</literal> property for a folder
\r
386 in your project. This property consists of one or more lines;
\r
387 each line has the name of a sub-folder which you want to use
\r
388 as the checkout folder for common code, and the repository URL
\r
389 that you want to be checked out there. For full details
\r
390 refer to <xref linkend="tsvn-dug-import-4"/>.
\r
393 Commit the new folder. Now when you update, Git
\r
394 will pull a copy of that project from its repository
\r
395 into your working copy. The sub-folders will be created
\r
396 automatically if required.
\r
397 Each time you update your main working copy, you will also
\r
398 receive the latest version of all external projects.
\r
401 If the external project is in the same repository, any changes
\r
402 you make there there will be included in the commit list when
\r
403 you commit your main project.
\r
406 If the external project is in a different repository, any
\r
407 changes you make to the external project will be notified
\r
408 when you commit the main project, but you have to commit
\r
409 those external changes separately.
\r
412 Of the three methods described, this is the only one which needs
\r
413 no setup on the client side. Once externals are specified in
\r
414 the folder properties, all clients will get populated folders
\r
418 <sect2 id="tsvn-howto-common-nested">
\r
419 <title>Use a nested working copy</title>
\r
421 Create a new folder within your project to contain the
\r
422 common code, but do not add it to Git
\r
427 <guimenu>TortoiseGit</guimenu>
\r
428 <guimenuitem>Checkout</guimenuitem>
\r
430 for the new folder and checkout a copy of the common
\r
431 code into it. You now have a separate working copy nested
\r
432 within your main working copy.
\r
435 The two working copies are independent. When you commit
\r
436 changes to the parent, changes to the nested WC are ignored.
\r
437 Likewise when you update the parent, the nested WC is not updated.
\r
440 <sect2 id="tsvn-howto-common-location">
\r
441 <title>Use a relative location</title>
\r
443 If you use the same common core code in several projects,
\r
444 and you do not want to keep multiple working copies of it
\r
445 for every project that uses it, you can just check it out
\r
446 to a separate location which is related to all the other
\r
447 projects which use it. For example:
\r
454 and refer to the common code using a relative path, eg.
\r
455 <filename>..\..\Common\DSPcore</filename>.
\r
458 If your projects are scattered in unrelated locations you
\r
459 can use a variant of this, which is to put the common
\r
460 code in one location and use drive letter substitution to
\r
461 map that location to something you can hard code in your
\r
462 projects, eg. Checkout the common code to
\r
463 <filename>D:\Documents\Framework</filename> or
\r
464 <filename>C:\Documents and Settings\{login}\My Documents\framework</filename>
\r
467 SUBST X: "D:\Documents\framework"
\r
469 to create the drive mapping used in your source code.
\r
470 Your code can then use absolute locations.
\r
472 #include "X:\superio\superio.h"
\r
476 This method will only work in an all-PC environment,
\r
477 and you will need to document the required drive mappings
\r
478 so your team know where these mysterious files are.
\r
479 This method is strictly for use in closed development environments,
\r
480 and not recommended for general use.
\r
484 <sect1 id="tsvn-howto-repo-shortcut">
\r
485 <title>Create a shortcut to a repository</title>
\r
487 <primary>shortcut</primary>
\r
490 If you frequently need to open the repository browser at a
\r
491 particular location, you can create a desktop shortcut
\r
492 using the automation interface to TortoiseProc. Just
\r
493 create a new shortcut and set the target to:
\r
495 TortoiseProc.exe /command:repobrowser /path:"url/to/repository"
\r
497 Of course you need to include the real repository URL.
\r
500 <sect1 id="tsvn-howto-unversion">
\r
501 <title>Ignore files which are already versioned</title>
\r
503 <primary>unversion</primary>
\r
506 <primary>remove versioning</primary>
\r
509 <primary>detach from repository</primary>
\r
512 If you accidentally added some files which should have been
\r
513 ignored, how do you get them out of version control without
\r
514 losing them? Maybe you have your own IDE configuration file
\r
515 which is not part of the project, but which took you a long
\r
516 time to set up just the way you like it.
\r
519 If you have not yet committed the add, then all you have to do
\r
522 <guimenu>TortoiseGit</guimenu>
\r
523 <guimenuitem>Revert...</guimenuitem>
\r
525 to undo the add. You should then add the file(s) to the ignore
\r
526 list so they don't get added again later by mistake.
\r
529 If the files are already in the repository, you have to do
\r
530 a little more work.
\r
534 Hold the <keycap>Shift</keycap> key to get the extended
\r
535 context menu and use
\r
537 <guimenu>TortoiseGit</guimenu>
\r
538 <guimenuitem>Delete (keep local)</guimenuitem>
\r
540 to mark the file/folder for deletion from the repository
\r
541 without losing the local copy.
\r
547 <guimenu>TortoiseGit</guimenu>
\r
548 <guimenuitem>Commit</guimenuitem>
\r
555 Add the file/folder to the ignore list so you don't get
\r
556 into the same trouble again.
\r
562 <sect1 id="tsvn-howto-unversion-wc">
\r
563 <title>Unversion a working copy</title>
\r
565 If you have a working copy which you want to convert back to
\r
566 a plain folder tree without the <literal>.svn</literal>
\r
567 directories, you can simply export it to itself. Read
\r
568 <xref linkend="tsvn-dug-export-unversion"/> to find out how.
\r
571 <sect1 id="tsvn-howto-remove-wc">
\r
572 <title>Remove a working copy</title>
\r
574 If you have a working copy which you no longer need, how do you
\r
575 get rid of it cleanly? Easy - just delete it in Windows Explorer!
\r
576 Working copies are private local entities, and they are self-contained.
\r