<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-dug-locking">
	<title>Locking</title>
	<indexterm>
		<primary>locking</primary>
	</indexterm>
	<indexterm>
		<primary>readonly</primary>
	</indexterm>
	<para>
		Git generally works best without locking, using the
		<quote>Copy-Modify-Merge</quote> methods described earlier in
		<xref linkend="tsvn-basics-versioning-copymodifymerge"/>.
		However there are a few instances when you may need to implement
		some form of locking policy.
		<itemizedlist>
			<listitem>
				<para>
					You are using <quote>unmergeable</quote> files,
					for example, graphics files. If two people change
					the same file, merging is not possible, so one of you
					will lose their changes.
				</para>
			</listitem>
			<listitem>
				<para>
					Your company has always used a locking revision control system in the past
					and there has been a management decision that
					<quote>locking is best</quote>.
				</para>
			</listitem>
		</itemizedlist>
	</para>
	<para>
		Firstly you need to ensure that your Git server is upgraded to at
		least version 1.2. Earlier versions do not support locking at all. If you
		are using <literal>file://</literal> access, then of course only your
		client needs to be updated.
	</para>
	<sect2 id="tsvn-dug-locking-how">
		<title>How Locking Works in Git</title>
		<para>
			By default, nothing is locked and anyone who has commit access can
			commit changes to any file at any time. Others will update their
			working copies periodically and changes in the repository will be
			merged with local changes.
		</para>
		<para>
			If you <firstterm>Get a Lock</firstterm> on a file, then only
			you can commit that file. Commits by all other users will be
			blocked until you release the lock. A locked file cannot be
			modified in any way in the repository, so it cannot be deleted
			or renamed either, except by the lock owner.
		</para>
		<para>
			However, other users will not necessarily know that you have taken
			out a lock. Unless they check the lock status regularly, the first
			they will know about it is when their commit fails, which in most
			cases is not very useful. To make it easier to manage locks, there
			is a new Git property
			<literal>svn:needs-lock</literal>.
			When this property is set (to any value) on a file, whenever the
			file is checked out or updated, the local copy is made read-only
			<emphasis>unless</emphasis> that working copy holds a lock for
			the file. This acts as a warning that you should not edit that
			file unless you have first acquired a lock.
			Files which are versioned and read-only are marked with a
			special overlay in TortoiseGit to indicate that you need to
			acquire a lock before editing.
		</para>
		<para>
			Locks are recorded by working copy location as well as by owner.
			If you have several working copies (at home, at work) then you
			can only hold a lock in <emphasis>one</emphasis> of those
			working copies.
		</para>
		<para>
			If one of your co-workers acquires a lock and then goes on holiday
			without releasing it, what do you do? Git provides a means
			to force locks. Releasing a lock held by someone else is referred
			to as <firstterm>Breaking</firstterm> the lock, and forcibly
			acquiring a lock which someone else already holds is referred to
			as <firstterm>Stealing</firstterm> the lock. Naturally these are
			not things you should do lightly if you want to remain friends with
			your co-workers.
		</para>
		<para>
			Locks are recorded in the repository, and a lock token is created
			in your local working copy. If there is a discrepancy, for example
			if someone else has broken the lock, the local lock token becomes
			invalid. The repository is always the definitive reference.
		</para>
	</sect2>
	<sect2 id="tsvn-dug-locking-lock">
		<?dbhh topicname="HIDD_LOCK"?>
		<title>Getting a Lock</title>
		<para>
			Select the file(s) in your working copy for which you want to 
			acquire a lock, then select the command
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Get Lock...</guimenuitem>
			</menuchoice>.
			<figure id="tsvn-dug-locking-dia-lock">
				<title>The Locking Dialog</title>
				<graphic fileref="../images/GetLock.png"/>
			</figure>
			A dialog appears, allowing you to enter a comment, so others
			can see why you have locked the file. The comment is optional
			and currently only used with Svnserve
			based repositories.
			If (and <emphasis>only</emphasis> if) you need to steal the
			lock from someone else, check the
			<guilabel>Steal lock</guilabel> box, then click on
			<guibutton>OK</guibutton>.
		</para>
		<para>
			If you select a folder and then use
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Get Lock...</guimenuitem>
			</menuchoice>
			the lock dialog will open with <emphasis>every</emphasis> file
			in <emphasis>every</emphasis> sub-folder selected for locking.
			If you really want to lock an entire hierarchy, that is the way
			to do it, but you could become very unpopular with your co-workers
			if you lock them out of the whole project. Use with care ...
		</para>
	</sect2>
	<sect2 id="tsvn-dug-locking-unlock">
		<title>Releasing a Lock</title>
		<para>
			To make sure you don't forget to release a lock you don't need
			any more, locked files are shown in the commit dialog and selected
			by default. If you continue with the commit, locks you hold on the
			selected files are removed, even if the files haven't been modified.
			If you don't want to release a lock on certain files, you can
			uncheck them (if they're not modified).
			If you want to keep a lock on a file you've modified, you have
			to enable the <guilabel>Keep locks</guilabel> checkbox before
			you commit your changes.
		</para>
		<para>
			To release a lock manually, select the file(s) in your working copy
			for which you want to release the lock, then select the command
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Release Lock</guimenuitem>
			</menuchoice>
			There is nothing further to enter so TortoiseGit will contact
			the repository and release the locks. You can also use this
			command on a folder to release all locks recursively.
		</para>
	</sect2>
	<sect2 id="tsvn-dug-locking-status">
		<title>Checking Lock Status</title>
		<para>
			<figure id="tsvn-dug-locking-dia-status">
				<title>The Check for Modifications Dialog</title>
				<graphic fileref="../images/RepoStatus.png"/>
			</figure>
			To see what locks you and others hold, you can use
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Check for Modifications...</guimenuitem>
			</menuchoice>.
			Locally held lock tokens show up immediately. To check for
			locks held by others (and to see if any of your locks are
			broken or stolen) you need to click on
			<guibutton>Check Repository</guibutton>.
		</para>
		<para>
			From the context menu here, you can also get and release locks,
			as well as breaking and stealing locks held by others.
		</para>
		<caution>
			<title>Avoid Breaking and Stealing Locks</title>
			<para>
				If you break or steal someone else's lock without telling
				them, you could potentially cause loss of work. If you
				are working with unmergeable file types and you steal
				someone else's lock, once you release the lock they
				are free to check in their changes and overwrite yours.
				Git doesn't lose data, but you have lost the
				team-working protection that locking gave you.
			</para>
		</caution>
	</sect2>
	<sect2 id="tsvn-dug-locking-needs-lock">
		<title>Making Non-locked Files Read-Only</title>
		<para>
			As mentioned above, the most effective way to use locking is to set
			the <literal>svn:needs-lock</literal> property on files. Refer to
			<xref linkend="tsvn-dug-propertypage"/>
			for instructions on how to set properties.
			Files with this property set will always be checked out and updated
			with the read-only flag set unless your working copy holds a lock.
			<graphic fileref="../images/ReadOnlyIcon.png"/> 
			As a reminder, TortoiseGit uses a special overlay to indicate this.
		</para>
		<para>
			If you operate a policy where every file has to be locked then
			you may find it easier to use Git's auto-props feature
			to set the property automatically every time you add new files.
			Read <xref linkend="tsvn-dug-propertypage-auto-props"/> for
			further information.
		</para>
	</sect2>
	<sect2 id="tsvn-dug-locking-hooks">
		<title>The Locking Hook Scripts</title>
		<para>
			When you create a new repository with Git 1.2 or higher,
			four hook templates are created in the repository
			<filename>hooks</filename> directory. These are called before
			and after getting a lock, and before and after releasing a lock.
		</para>
		<para>
			It is a good idea to install a <literal>post-lock</literal>
			and <literal>post-unlock</literal> hook script on the server which
			sends out an email indicating the file which has been locked.
			With such a script in place, all your users can be notified if
			someone locks/unlocks a file. You can find an example hook script
			<filename>hooks/post-lock.tmpl</filename> in your repository folder.
		</para>
		<para>
			You might also use hooks to disallow breaking or stealing of locks,
			or perhaps limit it to a named administrator.
			Or maybe you want to email the owner when one of their locks is
			broken or stolen.
		</para>
		<para>
			Read <xref linkend="tsvn-repository-hooks"/> to find out more.
		</para>
	</sect2>
</sect1>
