doc/source/en/TortoiseGit/tsvn_dug/dug_locking.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
   3 <sect1 id="tsvn-dug-locking">\r
   4         <title>Locking</title>\r
   5         <indexterm>\r
   6                 <primary>locking</primary>\r
   7         </indexterm>\r
   8         <indexterm>\r
   9                 <primary>readonly</primary>\r
  10         </indexterm>\r
  11         <para>\r
  12                 Git generally works best without locking, using the\r
  13                 <quote>Copy-Modify-Merge</quote> methods described earlier in\r
  14                 <xref linkend="tsvn-basics-versioning-copymodifymerge"/>.\r
  15                 However there are a few instances when you may need to implement\r
  16                 some form of locking policy.\r
  17                 <itemizedlist>\r
  18                         <listitem>\r
  19                                 <para>\r
  20                                         You are using <quote>unmergeable</quote> files,\r
  21                                         for example, graphics files. If two people change\r
  22                                         the same file, merging is not possible, so one of you\r
  23                                         will lose their changes.\r
  24                                 </para>\r
  25                         </listitem>\r
  26                         <listitem>\r
  27                                 <para>\r
  28                                         Your company has always used a locking revision control system in the past\r
  29                                         and there has been a management decision that\r
  30                                         <quote>locking is best</quote>.\r
  31                                 </para>\r
  32                         </listitem>\r
  33                 </itemizedlist>\r
  34         </para>\r
  35         <para>\r
  36                 Firstly you need to ensure that your Git server is upgraded to at\r
  37                 least version 1.2. Earlier versions do not support locking at all. If you\r
  38                 are using <literal>file://</literal> access, then of course only your\r
  39                 client needs to be updated.\r
  40         </para>\r
  41         <sect2 id="tsvn-dug-locking-how">\r
  42                 <title>How Locking Works in Git</title>\r
  43                 <para>\r
  44                         By default, nothing is locked and anyone who has commit access can\r
  45                         commit changes to any file at any time. Others will update their\r
  46                         working copies periodically and changes in the repository will be\r
  47                         merged with local changes.\r
  48                 </para>\r
  49                 <para>\r
  50                         If you <firstterm>Get a Lock</firstterm> on a file, then only\r
  51                         you can commit that file. Commits by all other users will be\r
  52                         blocked until you release the lock. A locked file cannot be\r
  53                         modified in any way in the repository, so it cannot be deleted\r
  54                         or renamed either, except by the lock owner.\r
  55                 </para>\r
  56                 <para>\r
  57                         However, other users will not necessarily know that you have taken\r
  58                         out a lock. Unless they check the lock status regularly, the first\r
  59                         they will know about it is when their commit fails, which in most\r
  60                         cases is not very useful. To make it easier to manage locks, there\r
  61                         is a new Git property\r
  62                         <literal>svn:needs-lock</literal>.\r
  63                         When this property is set (to any value) on a file, whenever the\r
  64                         file is checked out or updated, the local copy is made read-only\r
  65                         <emphasis>unless</emphasis> that working copy holds a lock for\r
  66                         the file. This acts as a warning that you should not edit that\r
  67                         file unless you have first acquired a lock.\r
  68                         Files which are versioned and read-only are marked with a\r
  69                         special overlay in TortoiseGit to indicate that you need to\r
  70                         acquire a lock before editing.\r
  71                 </para>\r
  72                 <para>\r
  73                         Locks are recorded by working copy location as well as by owner.\r
  74                         If you have several working copies (at home, at work) then you\r
  75                         can only hold a lock in <emphasis>one</emphasis> of those\r
  76                         working copies.\r
  77                 </para>\r
  78                 <para>\r
  79                         If one of your co-workers acquires a lock and then goes on holiday\r
  80                         without releasing it, what do you do? Git provides a means\r
  81                         to force locks. Releasing a lock held by someone else is referred\r
  82                         to as <firstterm>Breaking</firstterm> the lock, and forcibly\r
  83                         acquiring a lock which someone else already holds is referred to\r
  84                         as <firstterm>Stealing</firstterm> the lock. Naturally these are\r
  85                         not things you should do lightly if you want to remain friends with\r
  86                         your co-workers.\r
  87                 </para>\r
  88                 <para>\r
  89                         Locks are recorded in the repository, and a lock token is created\r
  90                         in your local working copy. If there is a discrepancy, for example\r
  91                         if someone else has broken the lock, the local lock token becomes\r
  92                         invalid. The repository is always the definitive reference.\r
  93                 </para>\r
  94         </sect2>\r
  95         <sect2 id="tsvn-dug-locking-lock">\r
  96                 <?dbhh topicname="HIDD_LOCK"?>\r
  97                 <title>Getting a Lock</title>\r
  98                 <para>\r
  99                         Select the file(s) in your working copy for which you want to \r
 100                         acquire a lock, then select the command\r
 101                         <menuchoice>\r
 102                                 <guimenu>TortoiseGit</guimenu>\r
 103                                 <guimenuitem>Get Lock...</guimenuitem>\r
 104                         </menuchoice>.\r
 105                         <figure id="tsvn-dug-locking-dia-lock">\r
 106                                 <title>The Locking Dialog</title>\r
 107                                 <graphic fileref="../images/GetLock.png"/>\r
 108                         </figure>\r
 109                         A dialog appears, allowing you to enter a comment, so others\r
 110                         can see why you have locked the file. The comment is optional\r
 111                         and currently only used with Svnserve\r
 112                         based repositories.\r
 113                         If (and <emphasis>only</emphasis> if) you need to steal the\r
 114                         lock from someone else, check the\r
 115                         <guilabel>Steal lock</guilabel> box, then click on\r
 116                         <guibutton>OK</guibutton>.\r
 117                 </para>\r
 118                 <para>\r
 119                         If you select a folder and then use\r
 120                         <menuchoice>\r
 121                                 <guimenu>TortoiseGit</guimenu>\r
 122                                 <guimenuitem>Get Lock...</guimenuitem>\r
 123                         </menuchoice>\r
 124                         the lock dialog will open with <emphasis>every</emphasis> file\r
 125                         in <emphasis>every</emphasis> sub-folder selected for locking.\r
 126                         If you really want to lock an entire hierarchy, that is the way\r
 127                         to do it, but you could become very unpopular with your co-workers\r
 128                         if you lock them out of the whole project. Use with care ...\r
 129                 </para>\r
 130         </sect2>\r
 131         <sect2 id="tsvn-dug-locking-unlock">\r
 132                 <title>Releasing a Lock</title>\r
 133                 <para>\r
 134                         To make sure you don't forget to release a lock you don't need\r
 135                         any more, locked files are shown in the commit dialog and selected\r
 136                         by default. If you continue with the commit, locks you hold on the\r
 137                         selected files are removed, even if the files haven't been modified.\r
 138                         If you don't want to release a lock on certain files, you can\r
 139                         uncheck them (if they're not modified).\r
 140                         If you want to keep a lock on a file you've modified, you have\r
 141                         to enable the <guilabel>Keep locks</guilabel> checkbox before\r
 142                         you commit your changes.\r
 143                 </para>\r
 144                 <para>\r
 145                         To release a lock manually, select the file(s) in your working copy\r
 146                         for which you want to release the lock, then select the command\r
 147                         <menuchoice>\r
 148                                 <guimenu>TortoiseGit</guimenu>\r
 149                                 <guimenuitem>Release Lock</guimenuitem>\r
 150                         </menuchoice>\r
 151                         There is nothing further to enter so TortoiseGit will contact\r
 152                         the repository and release the locks. You can also use this\r
 153                         command on a folder to release all locks recursively.\r
 154                 </para>\r
 155         </sect2>\r
 156         <sect2 id="tsvn-dug-locking-status">\r
 157                 <title>Checking Lock Status</title>\r
 158                 <para>\r
 159                         <figure id="tsvn-dug-locking-dia-status">\r
 160                                 <title>The Check for Modifications Dialog</title>\r
 161                                 <graphic fileref="../images/RepoStatus.png"/>\r
 162                         </figure>\r
 163                         To see what locks you and others hold, you can use\r
 164                         <menuchoice>\r
 165                                 <guimenu>TortoiseGit</guimenu>\r
 166                                 <guimenuitem>Check for Modifications...</guimenuitem>\r
 167                         </menuchoice>.\r
 168                         Locally held lock tokens show up immediately. To check for\r
 169                         locks held by others (and to see if any of your locks are\r
 170                         broken or stolen) you need to click on\r
 171                         <guibutton>Check Repository</guibutton>.\r
 172                 </para>\r
 173                 <para>\r
 174                         From the context menu here, you can also get and release locks,\r
 175                         as well as breaking and stealing locks held by others.\r
 176                 </para>\r
 177                 <caution>\r
 178                         <title>Avoid Breaking and Stealing Locks</title>\r
 179                         <para>\r
 180                                 If you break or steal someone else's lock without telling\r
 181                                 them, you could potentially cause loss of work. If you\r
 182                                 are working with unmergeable file types and you steal\r
 183                                 someone else's lock, once you release the lock they\r
 184                                 are free to check in their changes and overwrite yours.\r
 185                                 Git doesn't lose data, but you have lost the\r
 186                                 team-working protection that locking gave you.\r
 187                         </para>\r
 188                 </caution>\r
 189         </sect2>\r
 190         <sect2 id="tsvn-dug-locking-needs-lock">\r
 191                 <title>Making Non-locked Files Read-Only</title>\r
 192                 <para>\r
 193                         As mentioned above, the most effective way to use locking is to set\r
 194                         the <literal>svn:needs-lock</literal> property on files. Refer to\r
 195                         <xref linkend="tsvn-dug-propertypage"/>\r
 196                         for instructions on how to set properties.\r
 197                         Files with this property set will always be checked out and updated\r
 198                         with the read-only flag set unless your working copy holds a lock.\r
 199                         <graphic fileref="../images/ReadOnlyIcon.png"/> \r
 200                         As a reminder, TortoiseGit uses a special overlay to indicate this.\r
 201                 </para>\r
 202                 <para>\r
 203                         If you operate a policy where every file has to be locked then\r
 204                         you may find it easier to use Git's auto-props feature\r
 205                         to set the property automatically every time you add new files.\r
 206                         Read <xref linkend="tsvn-dug-propertypage-auto-props"/> for\r
 207                         further information.\r
 208                 </para>\r
 209         </sect2>\r
 210         <sect2 id="tsvn-dug-locking-hooks">\r
 211                 <title>The Locking Hook Scripts</title>\r
 212                 <para>\r
 213                         When you create a new repository with Git 1.2 or higher,\r
 214                         four hook templates are created in the repository\r
 215                         <filename>hooks</filename> directory. These are called before\r
 216                         and after getting a lock, and before and after releasing a lock.\r
 217                 </para>\r
 218                 <para>\r
 219                         It is a good idea to install a <literal>post-lock</literal>\r
 220                         and <literal>post-unlock</literal> hook script on the server which\r
 221                         sends out an email indicating the file which has been locked.\r
 222                         With such a script in place, all your users can be notified if\r
 223                         someone locks/unlocks a file. You can find an example hook script\r
 224                         <filename>hooks/post-lock.tmpl</filename> in your repository folder.\r
 225                 </para>\r
 226                 <para>\r
 227                         You might also use hooks to disallow breaking or stealing of locks,\r
 228                         or perhaps limit it to a named administrator.\r
 229                         Or maybe you want to email the owner when one of their locks is\r
 230                         broken or stolen.\r
 231                 </para>\r
 232                 <para>\r
 233                         Read <xref linkend="tsvn-repository-hooks"/> to find out more.\r
 234                 </para>\r
 235         </sect2>\r
 236 </sect1>\r