<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter SYSTEM "../../dtd/dblite.dtd">
<!-- This chapter is copied over from the Git book and slightly
	 modified for the TortoiseGit client.
-->
<chapter id="tsvn-basics">
	<title>Basic Concepts</title>
	<simplesect>
		<indexterm>
			<primary>Git book</primary>
		</indexterm>
		<para>
			This chapter is a slightly modified version of the same chapter
			in the Git book. An online version of the Git book is 
			available here:
			<ulink url="http://svnbook.red-bean.com/">
				<citetitle>http://svnbook.red-bean.com/</citetitle>
			</ulink>.
		</para>
		<para>
			This chapter is a short, casual introduction to Git.
			If you're new to version control, this chapter is definitely for
			you. We begin with a discussion of general version control
			concepts, work our way into the specific ideas behind
			Git, and show some simple examples of Git in
			use.
		</para>
		<para>
			Even though the examples in this chapter show people sharing
			collections of program source code, keep in mind that Git
			can manage any sort of file collection - it's not limited to
			helping computer programmers.
		</para>
	</simplesect>
	<sect1 id="tsvn-basics-repository">
		<title>The Repository</title>
		<indexterm>
			<primary>repository</primary>
		</indexterm>
		<para>
			Git is a centralized system for sharing information.
			At its core is a <firstterm>repository</firstterm>, which is a
			central store of data. The repository stores information in the
			form of a <firstterm>filesystem tree</firstterm> - a typical
			hierarchy of files and directories. Any number of
			<firstterm>clients</firstterm> connect to the repository, and
			then read or write to these files. By writing data, a client
			makes the information available to others; by reading data, the
			client receives information from others.
		</para>
		<figure id="tsvn-basics-dia1">
			<title>A Typical Client/Server System</title>
			<graphic fileref="images/ch02dia1.png"/>
		</figure>
		<para>
			So why is this interesting? So far, this sounds like the
			definition of a typical file server. And indeed, the repository
			<emphasis>is</emphasis> a kind of file server, but it's not your
			usual breed. What makes the Git repository special is
			that <emphasis>it remembers every change</emphasis> ever written
			to it: every change to every file, and even changes to the
			directory tree itself, such as the addition, deletion, and
			rearrangement of files and directories.
		</para>
		<para>
			When a client reads data from the repository, it normally
			sees only the latest version of the filesystem tree. But the
			client also has the ability to view
			<emphasis>previous</emphasis> states of the filesystem. For
			example, a client can ask historical questions like, <quote>what did
			this directory contain last Wednesday?</quote>, or <quote>who was the last
			person to change this file, and what changes did they make?</quote>
			These are the sorts of questions that are at the heart of any
			<firstterm>version control system</firstterm>: systems that are
			designed to record and track changes to data over time.
		</para>
	</sect1>
	<!-- the philosophical section -->
	<sect1 id="tsvn-basics-versioning">
		<title>Versioning Models</title>
		<para>
			All version control systems have to solve the same
			fundamental problem: how will the system allow users to share
			information, but prevent them from accidentally stepping on
			each other's feet? It's all too easy for users to
			accidentally overwrite each other's changes in the
			repository.
		</para>
		<sect2 id="tsvn-basics-versioning-filesharing">
			<title>The Problem of File-Sharing</title>
			<para>
				Consider this scenario: suppose we have two co-workers,
				Harry and Sally. They each decide to edit the same repository
				file at the same time. If Harry saves his changes to the
				repository first, then it's possible that (a few moments
				later) Sally could accidentally overwrite them with her own
				new version of the file. While Harry's version of the file
				won't be lost forever (because the system remembers every
				change), any changes Harry made <emphasis>won't</emphasis> be
				present in Sally's newer version of the file, because she
				never saw Harry's changes to begin with. Harry's work is
				still effectively lost - or at least missing from the
				latest version of the file - and probably by accident.
				This is definitely a situation we want to avoid!
			</para>
			<figure id="tsvn-basics-dia2">
				<title>The Problem to Avoid</title>
				<graphic fileref="images/ch02dia2.png"/>
			</figure>
		</sect2>
		<sect2 id="tsvn-basics-versioning-lockmodifyunlock">
			<title>The Lock-Modify-Unlock Solution</title>
			<para>
				Many version control systems use a
				<firstterm>lock-modify-unlock</firstterm> model to address
				this problem, which is a very simple solution. In such a
				system, the repository allows only one person to change a file
				at a time. First Harry must <emphasis>lock</emphasis> the file before he can begin
				making changes to it. Locking a file is a lot like borrowing
				a book from the library; if Harry has locked a file, then Sally
				cannot make any changes to it. If she tries to lock the file,
				the repository will deny the request. All she can do is read
				the file, and wait for Harry to finish his changes and release
				his lock. After Harry unlocks the file, his turn is over, and
				now Sally can take her turn by locking and editing.
			</para>
			<figure id="tsvn-basics-dia3">
				<title>The Lock-Modify-Unlock Solution</title>
				<graphic fileref="images/ch02dia3.png"/>
			</figure>
			<para>
				The problem with the lock-modify-unlock model is that it's
				a bit restrictive, and often becomes a roadblock for
				users:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis>Locking may cause administrative problems.</emphasis>
						Sometimes Harry will lock a file and then forget about it.
						Meanwhile, because Sally is still waiting to edit the file,
						her hands are tied. And then Harry goes on vacation. Now
						Sally has to get an administrator to release Harry's lock.
						The situation ends up causing a lot of unnecessary delay
						and wasted time.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis>Locking may cause unnecessary serialization.</emphasis>
						What if Harry is editing the beginning of a text file,
						and Sally simply wants to edit the end of the same file?
						These changes don't overlap at all. They could easily
						edit the file simultaneously, and no great harm would
						come, assuming the changes were properly merged together.
						There's no need for them to take turns in this
						situation.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis>Locking may create a false sense of security.</emphasis>
						Pretend that Harry locks and edits file A, while
						Sally simultaneously locks and edits file B. But suppose
						that A and B depend on one another, and the changes made
						to each are semantically incompatible. Suddenly A and B
						don't work together anymore. The locking system was
						powerless to prevent the problem - yet it somehow
						provided a sense of false security. It's easy for Harry and
						Sally to imagine that by locking files, each is beginning a
						safe, insulated task, and thus inhibits them from
						discussing their incompatible changes early
						on.
					</para>
				</listitem>
			</itemizedlist>
		</sect2>
		<sect2 id="tsvn-basics-versioning-copymodifymerge">
			<title>The Copy-Modify-Merge Solution</title>
			<para>
				Git, CVS, and other version control systems use a
				<firstterm>copy-modify-merge</firstterm> model as an
				alternative to locking. In this model, each user's client
				reads the repository and creates a personal <firstterm>working
				copy</firstterm> of the file or project. Users then work in
				parallel, modifying their private copies. Finally, the
				private copies are merged together into a new, final version.
				The version control system often assists with the merging, but
				ultimately a human being is responsible for making it happen
				correctly.
			</para>
			<para>
				Here's an example. Say that Harry and Sally each create
				working copies of the same project, copied from the
				repository. They work concurrently, and make changes to the
				same file <filename>A</filename> within their copies. Sally saves her changes to
				the repository first. When Harry attempts to save his changes
				later, the repository informs him that his file A is
				<firstterm>out-of-date</firstterm>. In other words, that file
				A in the repository has somehow changed since he last copied
				it. So Harry asks his client to <firstterm>merge</firstterm>
				any new changes from the repository into his working copy of
				file A. Chances are that Sally's changes don't overlap with
				his own; so once he has both sets of changes integrated, he
				saves his working copy back to the repository.</para>
			<figure id="tsvn-basics-dia4">
				<title>The Copy-Modify-Merge Solution</title>
				<graphic fileref="images/ch02dia4.png"/>
			</figure>
			<figure id="tsvn-basics-dia5">
				<title>...Copy-Modify-Merge Continued</title>
				<graphic fileref="images/ch02dia5.png"/>
			</figure>
			<indexterm>
				<primary>conflict</primary>
			</indexterm>
			<para>
				But what if Sally's changes <emphasis>do</emphasis> overlap
				with Harry's changes? What then? This situation is called a
				<firstterm>conflict</firstterm>, and it's usually not much of
				a problem. When Harry asks his client to merge the latest
				repository changes into his working copy, his copy of file A
				is somehow flagged as being in a state of conflict: he'll be
				able to see both sets of conflicting changes, and manually
				choose between them. Note that software can't automatically
				resolve conflicts; only humans are capable of understanding
				and making the necessary intelligent choices. Once Harry has
				manually resolved the overlapping changes (perhaps by
				discussing the conflict with Sally!), he can safely save the
				merged file back to the repository.
			</para>
			<para>
				The copy-modify-merge model may sound a bit chaotic, but
				in practice, it runs extremely smoothly. Users can work in
				parallel, never waiting for one another. When they work on
				the same files, it turns out that most of their concurrent
				changes don't overlap at all; conflicts are infrequent. And
				the amount of time it takes to resolve conflicts is far less
				than the time lost by a locking system.
			</para>
			<para>
				In the end, it all comes down to one critical factor: user
				communication. When users communicate poorly, both syntactic
				and semantic conflicts increase. No system can force users to
				communicate perfectly, and no system can detect semantic
				conflicts. So there's no point in being lulled into a false
				promise that a locking system will somehow prevent conflicts;
				in practice, locking seems to inhibit productivity more than
				anything else.
			</para>
			<para>
				There is one common situation where the lock-modify-unlock
				model comes out better, and that is where you have unmergeable
				files. For example if your repository contains some graphic
				images, and two people change the image at the same time, there
				is no way for those changes to be merged together. Either Harry
				or Sally will lose their changes.
			</para>
		</sect2>
		<sect2 id="tsvn-basics-versioning-4">
			<title>What does Git Do?</title>
			<para>
				Git uses the copy-modify-merge solution by default,
				and in many cases this is all you will ever need. However,
				as of Version 1.2, Git also supports file locking,
				so if you have unmergeable files, or if you are simply
				forced into a locking policy by management, Git
				will still provide the features you need.
			</para>
		</sect2>
	</sect1>
	<!-- How svn implements the philosophy -->
	<sect1 id="tsvn-basics-svn">
		<title>Git in Action</title>
		<sect2 id="tsvn-basics-svn-workingcopy">
			<title>Working Copies</title>
			<indexterm>
				<primary>working copy</primary>
			</indexterm>
			<para>
				You've already read about working copies; now we'll
				demonstrate how the Git client creates and uses
				them.
			</para>
			<para>
				A Git working copy is an ordinary directory tree on
				your local system, containing a collection of files. You can
				edit these files however you wish, and if they're source code
				files, you can compile your program from them in the usual
				way. Your working copy is your own private work area:
				Git will never incorporate other people's changes, nor
				make your own changes available to others, until you
				explicitly tell it to do so.
			</para>
			<para>
				After you've made some changes to the files in your
				working copy and verified that they work properly, Git
				provides you with commands to <emphasis>publish</emphasis> your changes to the
				other people working with you on your project (by writing to
				the repository). If other people publish their own changes,
				Git provides you with commands to merge those changes
				into your working directory (by reading from the
				repository).
			</para>
			<para>
				A working copy also contains some extra files, created and
				maintained by Git, to help it carry out these commands.
				In particular, each directory in your working copy contains a
				subdirectory named <filename>.svn</filename>, also known as
				the working copy <firstterm>administrative
				directory</firstterm>. The files in each administrative
				directory help Git recognize which files contain
				unpublished changes, and which files are out-of-date with
				respect to others' work.
			</para>
			<para>
				A typical Git repository often holds the files (or
				source code) for several projects; usually, each project is a
				subdirectory in the repository's filesystem tree. In this
				arrangement, a user's working copy will usually correspond to
				a particular subtree of the repository.
			</para>
			<para>
				For example, suppose you have a repository that contains
				two software projects.
			</para>
			<figure id="tsvn-basics-dia6">
				<title>The Repository's Filesystem</title>
				<graphic fileref="images/ch02dia6.png"/>
			</figure>
			<para>
				In other words, the repository's root directory has two
				subdirectories: <filename>paint</filename> and
				<filename>calc</filename>.
			</para>
			<para>
				To get a working copy, you must <firstterm>check
				out</firstterm> some subtree of the repository. (The term
				<emphasis>check out</emphasis> may sound like it has something to do with locking
				or reserving resources, but it doesn't; it simply creates a
				private copy of the project for you).
			</para>
			<para>
				Suppose you make changes to <filename>button.c</filename>.
				Since the <filename>.svn</filename> directory remembers the
				file's modification date and original contents, Git can
				tell that you've changed the file. However, Git does
				not make your changes public until you explicitly tell it to.
				The act of publishing your changes is more commonly known as
				<firstterm>committing</firstterm> (or <firstterm>checking
				in</firstterm>) changes to the repository.
			</para>
			<para>
				To publish your changes to others, you can use
				Git's <command>commit</command> command.
			</para>
			<para>
				Now your changes to <filename>button.c</filename> have
				been committed to the repository; if another user checks out a
				working copy of <filename>/calc</filename>, they will see
				your changes in the latest version of the file.
			</para>
			<para>
				Suppose you have a collaborator, Sally, who checked out a
				working copy of <filename>/calc</filename> at the same time
				you did. When you commit your change to
				<filename>button.c</filename>, Sally's working copy is left
				unchanged; Git only modifies working copies at the
				user's request.
			</para>
			<para>
				To bring her project up to date, Sally can ask
				Git to <firstterm>update</firstterm> her working copy,
				by using the Git <command>update</command> command.
				This will incorporate your changes into her working copy, as
				well as any others that have been committed since she checked
				it out.
			</para>
			<para>
				Note that Sally didn't need to
				specify which files to update; Git uses the information
				in the <filename>.svn</filename> directory, and further
				information in the repository, to decide which files need to
				be brought up to date.
			</para>
		</sect2>
		<sect2 id="tsvn-basics-svn-urls">
			<title>Repository URLs</title>
			<para>
				Git repositories can be accessed through many
				different methods - on local disk, or through various
				network protocols. A repository location, however, is
				always a URL. The URL schema indicates the access
				method:
			</para>
			<table id="tsvn-basics-svn-table-1">
				<title>Repository Access URLs</title>
				<tgroup cols="2">
					<colspec colnum="1" colwidth="2*"/>
					<colspec colnum="2" colwidth="5*"/>
					<thead>
						<row>
							<entry>Schema</entry>
							<entry>Access Method</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>
								<literal>file://</literal>
							</entry>
							<entry>
								Direct repository access on local or network drive.
							</entry>
						</row>
						<row>
							<entry>
								<literal>http://</literal>
							</entry>
							<entry>
								Access via WebDAV protocol to Git-aware Apache server.
							</entry>
						</row>
						<row>
							<entry>
								<literal>https://</literal>
							</entry>
							<entry>
								Same as <literal>http://</literal>, but with SSL encryption.
							</entry>
						</row>
						<row>
							<entry>
								<literal>svn://</literal>
							</entry>
							<entry>
								Unauthenticated TCP/IP access via custom protocol
								to a <literal>svnserve</literal> server.
							</entry>
						</row>
						<row>
							<entry>
								<literal>svn+ssh://</literal>
							</entry>
							<entry>
								authenticated, encrypted TCP/IP access via custom protocol
								to a <literal>svnserve</literal> server.
							</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
			<para>
				For the most part, Git's URLs use the standard
				syntax, allowing for server names and port numbers to be
				specified as part of the URL.
				The <literal>file://</literal> access method is normally used
				for local access, although it can be used with UNC paths to
				a networked host. The URL therefore takes the form
				<systemitem class="url">file://hostname/path/to/repos</systemitem>. For the
				local machine, the <literal>hostname</literal> portion of the URL is required
				to be either absent or <literal>localhost</literal>. For
				this reason, local paths normally appear with three slashes,
				<systemitem class="url">file:///path/to/repos</systemitem>.
			</para>
			<para>
				Also, users of the <literal>file://</literal> scheme on
				Windows platforms will need to use an unofficially
				<quote>standard</quote> syntax for accessing repositories
				that are on the same machine, but on a different drive than
				the client's current working drive. Either of the two
				following URL path syntaxes will work where
				<literal>X</literal> is the drive on which the repository
				resides:
			</para>
<screen>
file:///X:/path/to/repos
...
file:///X|/path/to/repos
...
</screen>
			<para>
				Note that a URL uses ordinary slashes even though the native
				(non-URL) form of a path on Windows uses backslashes.
			</para>
			<para>
				You can safely access a FSFS repository via a network share,
				but you <emphasis>cannot</emphasis> access a BDB repository
				in this way.
			</para>
			<warning>
				<para>
					Do not create or access a Berkeley DB repository on a network share.
					It <emphasis>cannot</emphasis> exist on a remote filesystem.
					Not even if you have the network drive mapped to a drive letter.
					If you attempt to use Berkeley DB on a network share,
					the results are unpredictable - you may see mysterious errors
					right away, or it may be months before you discover that your
					repository database is subtly corrupted.
				</para>
			</warning>
		</sect2>
		<sect2 id="tsvn-basics-svn-revisions">
			<title>Revisions</title>
			<indexterm>
				<primary>revision</primary>
			</indexterm>
			<para>
				A <command>svn commit</command> operation can publish
				changes to any number of files and directories as a single
				atomic transaction. In your working copy, you can change
				files' contents, create, delete, rename and copy files and
				directories, and then commit the complete set of changes as a
				unit.
			</para>
			<para>
				In the repository, each commit is treated as an atomic
				transaction: either all the commits changes take place, or
				none of them take place. Git retains this
				atomicity in the face of program crashes, system crashes,
				network problems, and other users' actions.
			</para>
			<para>
				Each time the repository accepts a commit, this creates a
				new state of the filesystem tree, called a
				<firstterm>revision</firstterm>. Each revision is assigned a
				unique natural number, one greater than the number of the
				previous revision. The initial revision of a freshly created
				repository is numbered zero, and consists of nothing but an
				empty root directory.
			</para>
			<para>
				A nice way to visualize the repository is as a series of
				trees. Imagine an array of revision numbers, starting at 0,
				stretching from left to right. Each revision number has a
				filesystem tree hanging below it, and each tree is a
				<quote>snapshot</quote> of the way the repository looked after
				each commit.
			</para>
			<figure id="tsvn-basics-dia7">
				<title>The Repository</title>
				<graphic fileref="images/ch02dia7.png"/>
			</figure>
			<sidebar>
				<title>Global Revision Numbers</title>
				<para>
					Unlike those of many other version control systems,
					Git's revision numbers apply to <emphasis>entire
					trees</emphasis>, not individual files. Each revision
					number selects an entire tree, a particular state of the
					repository after some committed change. Another way to
					think about it is that revision N represents the state of
					the repository filesystem after the Nth commit. When a
					Git user talks about ``revision 5 of
					<filename>foo.c</filename>'', they really mean
					``<filename>foo.c</filename> as it appears in revision 5.''
					Notice that in general, revisions N and M of a file do
					<emphasis>not</emphasis> necessarily differ!
				</para>
			</sidebar>
			<para>
				It's important to note that working copies do not always
				correspond to any single revision in the repository; they may
				contain files from several different revisions. For example,
				suppose you check out a working copy from a repository whose
				most recent revision is 4:
			</para>
<screen>
calc/Makefile:4
     integer.c:4
     button.c:4
</screen>
			<para>
				At the moment, this working directory corresponds exactly
				to revision 4 in the repository. However, suppose you make a
				change to <filename>button.c</filename>, and commit that
				change. Assuming no other commits have taken place, your
				commit will create revision 5 of the repository, and your
				working copy will now look like this:
			</para>
<screen>
calc/Makefile:4
     integer.c:4
     button.c:5
</screen>
			<para>
				Suppose that, at this point, Sally commits a change to
				<filename>integer.c</filename>, creating revision 6. If you
				use <command>svn update</command> to bring your working copy
				up to date, then it will look like this:
			</para>
<screen>
calc/Makefile:6
     integer.c:6
     button.c:6
</screen>
			<para>
				Sally's changes to <filename>integer.c</filename> will
				appear in your working copy, and your change will still be
				present in <filename>button.c</filename>. In this example,
				the text of <filename>Makefile</filename> is identical in
				revisions 4, 5, and 6, but Git will mark your working
				copy of <filename>Makefile</filename> with revision 6 to
				indicate that it is still current. So, after you do a clean
				update at the top of your working copy, it will generally
				correspond to exactly one revision in the repository.
			</para>
		</sect2>
		<sect2 id="tsvn-basics-svn-wcrepository">
			<title>How Working Copies Track the Repository</title>
			<para>
				For each file in a working directory, Git records
				two essential pieces of information in the
				<filename>.svn/</filename> administrative area:</para>
			<itemizedlist>
				<listitem>
					<para>
							what revision your working file is based on
							(this is called the file's <firstterm>working
							 revision</firstterm>), and
						</para>
				</listitem>
				<listitem>
					<para>
						a timestamp recording when the local copy was
						last updated by the repository.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				Given this information, by talking to the repository,
				Git can tell which of the following four states a
				working file is in:
			</para>
			<variablelist>
				<varlistentry>
					<term>Unchanged, and current</term>
					<listitem>
						<para>
							The file is unchanged in the working
							directory, and no changes to that file have been committed
							to the repository since its working revision. A
							<command>commit</command> of the file will do nothing,
							and an <command>update</command> of the file will do
							nothing.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Locally changed, and current</term>
					<listitem>
						<para>
							The file has been changed in the working
							directory, and no changes to that file have been committed
							to the repository since its base revision. There are local
							changes that have not been committed to the repository, thus
							a <command>commit</command> of the file will succeed in
							publishing your changes, and an <command>update</command>
							of the file will do nothing.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Unchanged, and out-of-date</term>
					<listitem>
						<para>
							The file has not been changed in the working
							directory, but it has been changed in the repository. The
							file should eventually be updated, to make it current with
							the public revision. A <command>commit</command> of the
							file will do nothing, and an <command>update</command> of
							the file will fold the latest changes into your working
							copy.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Locally changed, and out-of-date</term>
					<listitem>
						<para>
							The file has been changed both in the
							working directory, and in the repository. A <command>commit</command>
							of the file will fail with an <emphasis>out-of-date</emphasis>
							error. The file should be updated first; an <command>update</command>
							command will attempt to merge the public
							changes with the local changes. If Git can't
							complete the merge in a plausible way automatically, it
							leaves it to the user to resolve the
							conflict.
						</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect2>
	</sect1>
	<sect1 id="tsvn-basics-summary">
		<title>Summary</title>
		<para>
			We've covered a number of fundamental Git concepts in
			this chapter:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					We've introduced the notions of the central repository,
					the client working copy, and the array of repository
					revision trees.</para>
			</listitem>
			<listitem>
				<para>
					We've seen some simple examples of how two collaborators
					can use Git to publish and receive changes from one
					another, using the 'copy-modify-merge' model.
				</para>
			</listitem>
			<listitem>
				<para>
					We've talked a bit about the way Git tracks and
					manages information in a working copy.
				</para>
			</listitem>
		</itemizedlist>
	</sect1>
</chapter>
<!--
local variables:
sgml-parent-document: ("book.xml" "chapter")
end:
-->
