doc/source/en/TortoiseGit/tgit_dug/dug_branchtag.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
   3 <sect1 id="tgit-dug-branchtag" xmlns:xi="http://www.w3.org/2001/XInclude">\r
   4         <title>Branching / Tagging</title>\r
   5         <indexterm>\r
   6                 <primary>branch</primary>\r
   7         </indexterm>\r
   8         <indexterm>\r
   9                 <primary>tag</primary>\r
  10         </indexterm>\r
  11         <indexterm>\r
  12                 <primary>GPG signing</primary>\r
  13         </indexterm>\r
  14         <indexterm>\r
  15                 <primary>mark release</primary>\r
  16         </indexterm>\r
  17         <?dbhh topicname="HIDD_NEW_BRANCH_TAG"?>\r
  18         <para>\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.\r
  27         </para>\r
  28         <para>\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
  33         </para>\r
  34         <para>\r
  35                 Git is very powerful at branch and tag. It is very easy to create branch\r
  36                 and tag.\r
  37         </para>\r
  38         <sect2 id="tgit-dug-branch-1">\r
  39                 <title>Creating a Branch or Tag</title>\r
  40                 <para>\r
  41                         Creating a branch is very simple:\r
  42                         <menuchoice>\r
  43                                 <guimenu>TortoiseGit</guimenu>\r
  44                                 <guimenuitem>Create Branch...</guimenuitem>\r
  45                         </menuchoice>\r
  46                         <figure id="tgit-dug-branchtag-dia-1">\r
  47                                 <title>The Branch Dialog</title>\r
  48                                 <graphic fileref="../images/Branch.png"/>\r
  49                         </figure>\r
  50                 </para>\r
  51                 <para>\r
  52                         <guilabel>Branch:</guilabel> input your branch name. \r
  53                 </para>\r
  54                 <para>\r
  55                         Creating a tag is very simple:\r
  56                         <menuchoice>\r
  57                                 <guimenu>TortoiseGit</guimenu>\r
  58                                 <guimenuitem>Create Tag...</guimenuitem>\r
  59                         </menuchoice>\r
  60                         \r
  61                         <figure id="tgit-dug-branchtag-dia-2">\r
  62                                 <title>The Tag Dialog</title>\r
  63                                 <graphic fileref="../images/Tag.png"/>\r
  64                         </figure>\r
  65                         \r
  66                 </para>\r
  67                 <para>\r
  68                         <guilabel>Tag:</guilabel> input your tag name. \r
  69                 </para>\r
  70                 <para>\r
  71                         You can choose one commit that base on. \r
  72                         <xi:include href="./dug_chooseversion.xml"/> \r
  73                 </para>\r
  74                 <para>\r
  75                         If you want your working tree to be switched to the newly created\r
  76                         branch automatically, use the\r
  77                         <guilabel>Switch to new branch/tag</guilabel> checkbox.\r
  78                         But if you do that, first make sure that your working tree does not\r
  79                         contain modifications. If it does, those changes will be merged into\r
  80                         the branch working tree when you switch.\r
  81                 </para>\r
  82                 <para>\r
  83                         <guilabel>track</guilabel> is a checkbox with three values. If it is checked\r
  84                         <literal>--track</literal> is passed to git on <guilabel>OK</guilabel>, if it is\r
  85                         unchecked <literal>--no-track</literal> is passed to git on <guilabel>OK</guilabel>.\r
  86                         The third state indicates, that neither <literal>--track</literal> nor <literal>--no-track</literal>\r
  87                         is passed to git on <guilabel>OK</guilabel> - see branch.autosetupmerge configuration variable\r
  88                         (<xref linkend="git-config(1)"/>) and --track parameter documentation for <xref linkend="git-branch(1)"/>.\r
  89                 </para>\r
  90                 <para>\r
  91                         Check <guilabel>Sign</guilabel> to create a GPG signed tag. This requires GPG and also the configuration variable\r
  92                         "user.signingkey" to be set (see <xref linkend="tgit-dug-settings-config"/> and <xref linkend="git-config(1)"/>).\r
  93                         <tip>\r
  94                                 <para>\r
  95                                         When using GPG 1.4 (which is shipped with Git for Windows) this requires a key\r
  96                                         <emphasis>without</emphasis> a passphrase. GPG &gt;= 2 comes with an agent like pageant\r
  97                                         and, thus,.also works with passphrase protected keys, however, you might need to\r
  98                                         configure git to use the right gpg.exe. This can be done be setting the configuration variable\r
  99                                         "gpg.program" (e.g., "C:/Program Files (x86)/GNU/GnuPG/pub/gpg.exe").\r
 100                                         We tested this with\r
 101                                         <ulink url="http://www.gpg4win.de/">\r
 102                                                 <citetitle>Gpg4win</citetitle>\r
 103                                         </ulink>\r
 104                                         (GPG4win vanilla is sufficient and with version 2.2.x it is also compatible to GPG 1.4 key files).\r
 105                                 </para>\r
 106                         </tip>\r
 107                 </para>\r
 108                 <para>\r
 109                         Press <guibutton>OK</guibutton> to create branch or tag at  \r
 110                         <emphasis>local repository</emphasis>.\r
 111                 </para>\r
 112                 <para>\r
 113                         Note that unless you opted to switch your working tree to the newly\r
 114                         created branch, creating a Branch or Tag does <emphasis>not</emphasis>\r
 115                         affect your working tree. Even if you create the branch from your working tree,\r
 116                         those changes are committed to the original branch, not to the new branch.\r
 117                 </para>\r
 118                 <para>\r
 119                         How to switch working tree to tag\branch,\r
 120                         please refer to <xref linkend="tgit-dug-checkout"/> \r
 121                 </para>\r
 122         </sect2>\r
 123         <para>\r
 124                 You can find more information at <xref linkend="git-branch(1)"/> and <xref linkend="git-tag(1)"/>\r
 125         </para>\r
 126 </sect1>\r