1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
\r
3 <sect1 id="tsvn-dug-branchtag">
\r
4 <title>Branching / Tagging</title>
\r
6 <primary>branch</primary>
\r
9 <primary>tag</primary>
\r
12 <primary>copy</primary>
\r
15 <primary>mark release</primary>
\r
17 <?dbhh topicname="HIDD_COPY"?>
\r
19 One of the features of version control systems is the ability
\r
20 to isolate changes onto a separate line of development.
\r
21 This line is known as a <firstterm>branch</firstterm>.
\r
22 Branches are often used to try out new features without
\r
23 disturbing the main line of development with compiler
\r
24 errors and bugs. As soon as the new feature is stable enough
\r
25 then the development branch is <firstterm>merged</firstterm>
\r
26 back into the main branch (trunk).
\r
29 Another feature of version control systems is the ability
\r
30 to mark particular revisions (e.g. a release version),
\r
31 so you can at any time recreate a certain build or
\r
32 environment. This process is known as <firstterm>tagging</firstterm>.
\r
35 Subversion does not have special commands for branching
\r
36 or tagging, but uses so-called <quote>cheap copies</quote>
\r
37 instead. Cheap copies are similar to hard links in Unix, which means
\r
38 that instead of making a complete copy in the repository, an internal
\r
39 link is created, pointing to a specific tree/revision. As a result
\r
40 branches and tags are very quick to create, and take up almost
\r
41 no extra space in the repository.
\r
43 <sect2 id="tsvn-dug-branch-1">
\r
44 <title>Creating a Branch or Tag</title>
\r
46 If you have imported your project with the recommended
\r
47 directory structure, creating a branch or tag version is very simple:
\r
48 <figure id="tsvn-dug-branchtag-dia-1">
\r
49 <title>The Branch/Tag Dialog</title>
\r
50 <graphic fileref="../images/Copy.png"/>
\r
52 Select the folder in your working copy which you want to copy
\r
53 to a branch or tag, then select the command
\r
55 <guimenu>TortoiseGit</guimenu>
\r
56 <guimenuitem>Branch/Tag...</guimenuitem>
\r
60 The default destination URL for the new branch
\r
61 will be the source URL on which your working copy is based.
\r
62 You will need to edit that URL to the new path for your branch/tag.
\r
65 http://svn.collab.net/repos/ProjectName/trunk
\r
67 you might now use something like
\r
69 http://svn.collab.net/repos/ProjectName/tags/Release_1.10
\r
71 If you can't remember the naming convention you used last time,
\r
72 click the button on the right to open the repository browser
\r
73 so you can view the existing repository structure.
\r
76 Now you have to select the source of the copy. Here you have
\r
80 <term>HEAD revision in the repository</term>
\r
83 The new branch is copied directly in the repository
\r
84 from the HEAD revision. No data needs to be transferred
\r
85 from your working copy, and the branch is created
\r
91 <term>Specific revision in the repository</term>
\r
94 The new branch is copied directly in the repository
\r
95 but you can choose an older revision. This is useful
\r
96 if you forgot to make a tag when you released your
\r
97 project last week. If you can't remember the revision
\r
98 number, click the button on the right to show the
\r
99 revision log, and select the revision number from
\r
100 there. Again no data is transferred from your working
\r
101 copy, and the branch is created very quickly.
\r
106 <term>Working copy</term>
\r
109 The new branch is an identical copy of your local
\r
110 working copy. If you have updated some files to an
\r
111 older revision in your WC, or if you have made local
\r
112 changes, that is exactly what goes into the copy.
\r
113 Naturally this sort of complex tag may involve
\r
114 transferring data from your WC back to the repository
\r
115 if it does not exist there already.
\r
122 If you want your working copy to be switched to the newly created
\r
123 branch automatically, use the
\r
124 <guilabel>Switch working copy to new branch/tag</guilabel> checkbox.
\r
125 But if you do that, first make sure that your working copy does not
\r
126 contain modifications. If it does, those changes will be merged into
\r
127 the branch WC when you switch.
\r
130 Press <guibutton>OK</guibutton> to commit the new copy to the
\r
131 repository. Don't forget to supply a log message. Note that the
\r
132 copy is created <emphasis>inside the repository</emphasis>.
\r
135 Note that unless you opted to switch your working copy to the newly
\r
136 created branch, creating a Branch or Tag does <emphasis>not</emphasis>
\r
137 affect your working copy. Even if you create the branch from your WC,
\r
138 those changes are committed to the new branch, not to the trunk, so your
\r
139 WC may still be marked as modified with respect to the trunk.
\r
142 <sect2 id="tsvn-dug-switch-1">
\r
143 <title>To Checkout or to Switch...</title>
\r
144 <?dbhh topicname="HIDD_SWITCH"?>
\r
146 <primary>switch</primary>
\r
149 ...that is (not really) the question. While a checkout downloads
\r
150 everything from the desired branch in the repository to your working
\r
153 <guimenu>TortoiseGit</guimenu>
\r
154 <guimenuitem>Switch...</guimenuitem>
\r
156 only transfers the changed data to your
\r
157 working copy. Good for the network load, good for your patience. :-)
\r
160 To be able to work with your freshly generated branch or tag you
\r
161 have several ways to handle it. You can:
\r
166 <guimenu>TortoiseGit</guimenu>
\r
167 <guimenuitem>Checkout</guimenuitem>
\r
169 to make a fresh checkout in an empty folder.
\r
170 You can check out to any location on your
\r
171 local disk and you can create as many working copies
\r
172 from your repository as you like.
\r
177 Switch your current working copy to the
\r
178 newly created copy in the repository. Again select the
\r
179 top level folder of your project and use
\r
181 <guimenu>TortoiseGit</guimenu>
\r
182 <guimenuitem>Switch...</guimenuitem>
\r
184 from the context menu.
\r
187 In the next dialog enter the URL of the branch you just created.
\r
189 <guilabel>Head Revision</guilabel>
\r
190 radio button and click on
\r
191 <guibutton>OK</guibutton>.
\r
192 Your working copy is switched to the new branch/tag.
\r
195 Switch works just like Update in that it never discards your
\r
196 local changes. Any changes you have made to your working copy
\r
197 which have not yet been committed will be merged when you
\r
198 do the Switch. If you do not want this to happen then you
\r
199 must either commit the changes before switching, or revert
\r
200 your working copy to an already-committed revision (typically HEAD).
\r
205 If you want to work on trunk and branch, but don't want
\r
206 the expense of a fresh checkout, you can use Windows Explorer
\r
207 to make a copy of your trunk checkout in another folder, then
\r
209 <guimenu>TortoiseGit</guimenu>
\r
210 <guimenuitem>Switch...</guimenuitem>
\r
212 that copy to your new branch.
\r
216 <figure id="tsvn-dug-switch-dia-1">
\r
217 <title>The Switch Dialog</title>
\r
218 <graphic fileref="../images/Switch.png"/>
\r
222 Although Subversion itself makes no distinction between tags
\r
223 and branches, the way they are typically used differs a bit.
\r
227 Tags are typically used to create a static snapshot of the
\r
228 project at a particular stage. As such they not normally
\r
229 used for development - that's what branches are for, which
\r
230 is the reason we recommended the
\r
231 <filename>/trunk /branches /tags</filename>
\r
232 repository structure in the first place. Working on a tag
\r
233 revision is <emphasis>not a good idea</emphasis>, but
\r
234 because your local files are not write protected there is
\r
235 nothing to stop you doing this by mistake.
\r
236 However, if you try to commit to a path in the repository
\r
237 which contains <filename>/tags/</filename>, TortoiseGit will
\r
243 It may be that you need to make further changes to a
\r
244 release which you have already tagged. The correct way
\r
245 to handle this is to create a new branch from the tag
\r
246 first and commit the branch. Do your Changes on this
\r
247 branch and then create a new tag from this new branch, e.g.
\r
248 <filename>Version_1.0.1</filename>.
\r
253 If you modify a working copy created from
\r
254 a branch and commit, then all changes go to the new
\r
255 branch and <emphasis>not</emphasis> the trunk.
\r
256 Only the modifications are stored.
\r
257 The rest remains a cheap copy.
\r