| blob | 95da1c78c8ca045cd5daf4beac62177ef08c3ead |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE chapter SYSTEM "../../dtd/dblite.dtd">\r
3 <!-- This chapter is copied over from the Git book and slightly\r
4 modified for the TortoiseGit client.\r
5 -->\r
6 <chapter id="tsvn-basics">\r
7 <title>Basic Concepts</title>\r
8 <simplesect>\r
9 <indexterm>\r
10 <primary>Git book</primary>\r
11 </indexterm>\r
12 <para>\r
13 This chapter is a slightly modified version of the same chapter\r
14 in the Git book. An online version of the Git book is \r
15 available here:\r
16 <ulink url="http://svnbook.red-bean.com/">\r
17 <citetitle>http://svnbook.red-bean.com/</citetitle>\r
18 </ulink>.\r
19 </para>\r
20 <para>\r
21 This chapter is a short, casual introduction to Git.\r
22 If you're new to version control, this chapter is definitely for\r
23 you. We begin with a discussion of general version control\r
24 concepts, work our way into the specific ideas behind\r
25 Git, and show some simple examples of Git in\r
26 use.\r
27 </para>\r
28 <para>\r
29 Even though the examples in this chapter show people sharing\r
30 collections of program source code, keep in mind that Git\r
31 can manage any sort of file collection - it's not limited to\r
32 helping computer programmers.\r
33 </para>\r
34 </simplesect>\r
35 <sect1 id="tsvn-basics-repository">\r
36 <title>The Repository</title>\r
37 <indexterm>\r
38 <primary>repository</primary>\r
39 </indexterm>\r
40 <para>\r
41 Git is a centralized system for sharing information.\r
42 At its core is a <firstterm>repository</firstterm>, which is a\r
43 central store of data. The repository stores information in the\r
44 form of a <firstterm>filesystem tree</firstterm> - a typical\r
45 hierarchy of files and directories. Any number of\r
46 <firstterm>clients</firstterm> connect to the repository, and\r
47 then read or write to these files. By writing data, a client\r
48 makes the information available to others; by reading data, the\r
49 client receives information from others.\r
50 </para>\r
51 <figure id="tsvn-basics-dia1">\r
52 <title>A Typical Client/Server System</title>\r
53 <graphic fileref="images/ch02dia1.png"/>\r
54 </figure>\r
55 <para>\r
56 So why is this interesting? So far, this sounds like the\r
57 definition of a typical file server. And indeed, the repository\r
58 <emphasis>is</emphasis> a kind of file server, but it's not your\r
59 usual breed. What makes the Git repository special is\r
60 that <emphasis>it remembers every change</emphasis> ever written\r
61 to it: every change to every file, and even changes to the\r
62 directory tree itself, such as the addition, deletion, and\r
63 rearrangement of files and directories.\r
64 </para>\r
65 <para>\r
66 When a client reads data from the repository, it normally\r
67 sees only the latest version of the filesystem tree. But the\r
68 client also has the ability to view\r
69 <emphasis>previous</emphasis> states of the filesystem. For\r
70 example, a client can ask historical questions like, <quote>what did\r
71 this directory contain last Wednesday?</quote>, or <quote>who was the last\r
72 person to change this file, and what changes did they make?</quote>\r
73 These are the sorts of questions that are at the heart of any\r
74 <firstterm>version control system</firstterm>: systems that are\r
75 designed to record and track changes to data over time.\r
76 </para>\r
77 </sect1>\r
78 <!-- the philosophical section -->\r
79 <sect1 id="tsvn-basics-versioning">\r
80 <title>Versioning Models</title>\r
81 <para>\r
82 All version control systems have to solve the same\r
83 fundamental problem: how will the system allow users to share\r
84 information, but prevent them from accidentally stepping on\r
85 each other's feet? It's all too easy for users to\r
86 accidentally overwrite each other's changes in the\r
87 repository.\r
88 </para>\r
89 <sect2 id="tsvn-basics-versioning-filesharing">\r
90 <title>The Problem of File-Sharing</title>\r
91 <para>\r
92 Consider this scenario: suppose we have two co-workers,\r
93 Harry and Sally. They each decide to edit the same repository\r
94 file at the same time. If Harry saves his changes to the\r
95 repository first, then it's possible that (a few moments\r
96 later) Sally could accidentally overwrite them with her own\r
97 new version of the file. While Harry's version of the file\r
98 won't be lost forever (because the system remembers every\r
99 change), any changes Harry made <emphasis>won't</emphasis> be\r
100 present in Sally's newer version of the file, because she\r
101 never saw Harry's changes to begin with. Harry's work is\r
102 still effectively lost - or at least missing from the\r
103 latest version of the file - and probably by accident.\r
104 This is definitely a situation we want to avoid!\r
105 </para>\r
106 <figure id="tsvn-basics-dia2">\r
107 <title>The Problem to Avoid</title>\r
108 <graphic fileref="images/ch02dia2.png"/>\r
109 </figure>\r
110 </sect2>\r
111 <sect2 id="tsvn-basics-versioning-lockmodifyunlock">\r
112 <title>The Lock-Modify-Unlock Solution</title>\r
113 <para>\r
114 Many version control systems use a\r
115 <firstterm>lock-modify-unlock</firstterm> model to address\r
116 this problem, which is a very simple solution. In such a\r
117 system, the repository allows only one person to change a file\r
118 at a time. First Harry must <emphasis>lock</emphasis> the file before he can begin\r
119 making changes to it. Locking a file is a lot like borrowing\r
120 a book from the library; if Harry has locked a file, then Sally\r
121 cannot make any changes to it. If she tries to lock the file,\r
122 the repository will deny the request. All she can do is read\r
123 the file, and wait for Harry to finish his changes and release\r
124 his lock. After Harry unlocks the file, his turn is over, and\r
125 now Sally can take her turn by locking and editing.\r
126 </para>\r
127 <figure id="tsvn-basics-dia3">\r
128 <title>The Lock-Modify-Unlock Solution</title>\r
129 <graphic fileref="images/ch02dia3.png"/>\r
130 </figure>\r
131 <para>\r
132 The problem with the lock-modify-unlock model is that it's\r
133 a bit restrictive, and often becomes a roadblock for\r
134 users:\r
135 </para>\r
136 <itemizedlist>\r
137 <listitem>\r
138 <para>\r
139 <emphasis>Locking may cause administrative problems.</emphasis>\r
140 Sometimes Harry will lock a file and then forget about it.\r
141 Meanwhile, because Sally is still waiting to edit the file,\r
142 her hands are tied. And then Harry goes on vacation. Now\r
143 Sally has to get an administrator to release Harry's lock.\r
144 The situation ends up causing a lot of unnecessary delay\r
145 and wasted time.\r
146 </para>\r
147 </listitem>\r
148 <listitem>\r
149 <para>\r
150 <emphasis>Locking may cause unnecessary serialization.</emphasis>\r
151 What if Harry is editing the beginning of a text file,\r
152 and Sally simply wants to edit the end of the same file?\r
153 These changes don't overlap at all. They could easily\r
154 edit the file simultaneously, and no great harm would\r
155 come, assuming the changes were properly merged together.\r
156 There's no need for them to take turns in this\r
157 situation.\r
158 </para>\r
159 </listitem>\r
160 <listitem>\r
161 <para>\r
162 <emphasis>Locking may create a false sense of security.</emphasis>\r
163 Pretend that Harry locks and edits file A, while\r
164 Sally simultaneously locks and edits file B. But suppose\r
165 that A and B depend on one another, and the changes made\r
166 to each are semantically incompatible. Suddenly A and B\r
167 don't work together anymore. The locking system was\r
168 powerless to prevent the problem - yet it somehow\r
169 provided a sense of false security. It's easy for Harry and\r
170 Sally to imagine that by locking files, each is beginning a\r
171 safe, insulated task, and thus inhibits them from\r
172 discussing their incompatible changes early\r
173 on.\r
174 </para>\r
175 </listitem>\r
176 </itemizedlist>\r
177 </sect2>\r
178 <sect2 id="tsvn-basics-versioning-copymodifymerge">\r
179 <title>The Copy-Modify-Merge Solution</title>\r
180 <para>\r
181 Git, CVS, and other version control systems use a\r
182 <firstterm>copy-modify-merge</firstterm> model as an\r
183 alternative to locking. In this model, each user's client\r
184 reads the repository and creates a personal <firstterm>working\r
185 copy</firstterm> of the file or project. Users then work in\r
186 parallel, modifying their private copies. Finally, the\r
187 private copies are merged together into a new, final version.\r
188 The version control system often assists with the merging, but\r
189 ultimately a human being is responsible for making it happen\r
190 correctly.\r
191 </para>\r
192 <para>\r
193 Here's an example. Say that Harry and Sally each create\r
194 working copies of the same project, copied from the\r
195 repository. They work concurrently, and make changes to the\r
196 same file <filename>A</filename> within their copies. Sally saves her changes to\r
197 the repository first. When Harry attempts to save his changes\r
198 later, the repository informs him that his file A is\r
199 <firstterm>out-of-date</firstterm>. In other words, that file\r
200 A in the repository has somehow changed since he last copied\r
201 it. So Harry asks his client to <firstterm>merge</firstterm>\r
202 any new changes from the repository into his working copy of\r
203 file A. Chances are that Sally's changes don't overlap with\r
204 his own; so once he has both sets of changes integrated, he\r
205 saves his working copy back to the repository.</para>\r
206 <figure id="tsvn-basics-dia4">\r
207 <title>The Copy-Modify-Merge Solution</title>\r
208 <graphic fileref="images/ch02dia4.png"/>\r
209 </figure>\r
210 <figure id="tsvn-basics-dia5">\r
211 <title>...Copy-Modify-Merge Continued</title>\r
212 <graphic fileref="images/ch02dia5.png"/>\r
213 </figure>\r
214 <indexterm>\r
215 <primary>conflict</primary>\r
216 </indexterm>\r
217 <para>\r
218 But what if Sally's changes <emphasis>do</emphasis> overlap\r
219 with Harry's changes? What then? This situation is called a\r
220 <firstterm>conflict</firstterm>, and it's usually not much of\r
221 a problem. When Harry asks his client to merge the latest\r
222 repository changes into his working copy, his copy of file A\r
223 is somehow flagged as being in a state of conflict: he'll be\r
224 able to see both sets of conflicting changes, and manually\r
225 choose between them. Note that software can't automatically\r
226 resolve conflicts; only humans are capable of understanding\r
227 and making the necessary intelligent choices. Once Harry has\r
228 manually resolved the overlapping changes (perhaps by\r
229 discussing the conflict with Sally!), he can safely save the\r
230 merged file back to the repository.\r
231 </para>\r
232 <para>\r
233 The copy-modify-merge model may sound a bit chaotic, but\r
234 in practice, it runs extremely smoothly. Users can work in\r
235 parallel, never waiting for one another. When they work on\r
236 the same files, it turns out that most of their concurrent\r
237 changes don't overlap at all; conflicts are infrequent. And\r
238 the amount of time it takes to resolve conflicts is far less\r
239 than the time lost by a locking system.\r
240 </para>\r
241 <para>\r
242 In the end, it all comes down to one critical factor: user\r
243 communication. When users communicate poorly, both syntactic\r
244 and semantic conflicts increase. No system can force users to\r
245 communicate perfectly, and no system can detect semantic\r
246 conflicts. So there's no point in being lulled into a false\r
247 promise that a locking system will somehow prevent conflicts;\r
248 in practice, locking seems to inhibit productivity more than\r
249 anything else.\r
250 </para>\r
251 <para>\r
252 There is one common situation where the lock-modify-unlock\r
253 model comes out better, and that is where you have unmergeable\r
254 files. For example if your repository contains some graphic\r
255 images, and two people change the image at the same time, there\r
256 is no way for those changes to be merged together. Either Harry\r
257 or Sally will lose their changes.\r
258 </para>\r
259 </sect2>\r
260 <sect2 id="tsvn-basics-versioning-4">\r
261 <title>What does Git Do?</title>\r
262 <para>\r
263 Git uses the copy-modify-merge solution by default,\r
264 and in many cases this is all you will ever need. However,\r
265 as of Version 1.2, Git also supports file locking,\r
266 so if you have unmergeable files, or if you are simply\r
267 forced into a locking policy by management, Git\r
268 will still provide the features you need.\r
269 </para>\r
270 </sect2>\r
271 </sect1>\r
272 <!-- How svn implements the philosophy -->\r
273 <sect1 id="tsvn-basics-svn">\r
274 <title>Git in Action</title>\r
275 <sect2 id="tsvn-basics-svn-workingcopy">\r
276 <title>Working Copies</title>\r
277 <indexterm>\r
278 <primary>working copy</primary>\r
279 </indexterm>\r
280 <para>\r
281 You've already read about working copies; now we'll\r
282 demonstrate how the Git client creates and uses\r
283 them.\r
284 </para>\r
285 <para>\r
286 A Git working copy is an ordinary directory tree on\r
287 your local system, containing a collection of files. You can\r
288 edit these files however you wish, and if they're source code\r
289 files, you can compile your program from them in the usual\r
290 way. Your working copy is your own private work area:\r
291 Git will never incorporate other people's changes, nor\r
292 make your own changes available to others, until you\r
293 explicitly tell it to do so.\r
294 </para>\r
295 <para>\r
296 After you've made some changes to the files in your\r
297 working copy and verified that they work properly, Git\r
298 provides you with commands to <emphasis>publish</emphasis> your changes to the\r
299 other people working with you on your project (by writing to\r
300 the repository). If other people publish their own changes,\r
301 Git provides you with commands to merge those changes\r
302 into your working directory (by reading from the\r
303 repository).\r
304 </para>\r
305 <para>\r
306 A working copy also contains some extra files, created and\r
307 maintained by Git, to help it carry out these commands.\r
308 In particular, each directory in your working copy contains a\r
309 subdirectory named <filename>.svn</filename>, also known as\r
310 the working copy <firstterm>administrative\r
311 directory</firstterm>. The files in each administrative\r
312 directory help Git recognize which files contain\r
313 unpublished changes, and which files are out-of-date with\r
314 respect to others' work.\r
315 </para>\r
316 <para>\r
317 A typical Git repository often holds the files (or\r
318 source code) for several projects; usually, each project is a\r
319 subdirectory in the repository's filesystem tree. In this\r
320 arrangement, a user's working copy will usually correspond to\r
321 a particular subtree of the repository.\r
322 </para>\r
323 <para>\r
324 For example, suppose you have a repository that contains\r
325 two software projects.\r
326 </para>\r
327 <figure id="tsvn-basics-dia6">\r
328 <title>The Repository's Filesystem</title>\r
329 <graphic fileref="images/ch02dia6.png"/>\r
330 </figure>\r
331 <para>\r
332 In other words, the repository's root directory has two\r
333 subdirectories: <filename>paint</filename> and\r
334 <filename>calc</filename>.\r
335 </para>\r
336 <para>\r
337 To get a working copy, you must <firstterm>check\r
338 out</firstterm> some subtree of the repository. (The term\r
339 <emphasis>check out</emphasis> may sound like it has something to do with locking\r
340 or reserving resources, but it doesn't; it simply creates a\r
341 private copy of the project for you).\r
342 </para>\r
343 <para>\r
344 Suppose you make changes to <filename>button.c</filename>.\r
345 Since the <filename>.svn</filename> directory remembers the\r
346 file's modification date and original contents, Git can\r
347 tell that you've changed the file. However, Git does\r
348 not make your changes public until you explicitly tell it to.\r
349 The act of publishing your changes is more commonly known as\r
350 <firstterm>committing</firstterm> (or <firstterm>checking\r
351 in</firstterm>) changes to the repository.\r
352 </para>\r
353 <para>\r
354 To publish your changes to others, you can use\r
355 Git's <command>commit</command> command.\r
356 </para>\r
357 <para>\r
358 Now your changes to <filename>button.c</filename> have\r
359 been committed to the repository; if another user checks out a\r
360 working copy of <filename>/calc</filename>, they will see\r
361 your changes in the latest version of the file.\r
362 </para>\r
363 <para>\r
364 Suppose you have a collaborator, Sally, who checked out a\r
365 working copy of <filename>/calc</filename> at the same time\r
366 you did. When you commit your change to\r
367 <filename>button.c</filename>, Sally's working copy is left\r
368 unchanged; Git only modifies working copies at the\r
369 user's request.\r
370 </para>\r
371 <para>\r
372 To bring her project up to date, Sally can ask\r
373 Git to <firstterm>update</firstterm> her working copy,\r
374 by using the Git <command>update</command> command.\r
375 This will incorporate your changes into her working copy, as\r
376 well as any others that have been committed since she checked\r
377 it out.\r
378 </para>\r
379 <para>\r
380 Note that Sally didn't need to\r
381 specify which files to update; Git uses the information\r
382 in the <filename>.svn</filename> directory, and further\r
383 information in the repository, to decide which files need to\r
384 be brought up to date.\r
385 </para>\r
386 </sect2>\r
387 <sect2 id="tsvn-basics-svn-urls">\r
388 <title>Repository URLs</title>\r
389 <para>\r
390 Git repositories can be accessed through many\r
391 different methods - on local disk, or through various\r
392 network protocols. A repository location, however, is\r
393 always a URL. The URL schema indicates the access\r
394 method:\r
395 </para>\r
396 <table id="tsvn-basics-svn-table-1">\r
397 <title>Repository Access URLs</title>\r
398 <tgroup cols="2">\r
399 <colspec colnum="1" colwidth="2*"/>\r
400 <colspec colnum="2" colwidth="5*"/>\r
401 <thead>\r
402 <row>\r
403 <entry>Schema</entry>\r
404 <entry>Access Method</entry>\r
405 </row>\r
406 </thead>\r
407 <tbody>\r
408 <row>\r
409 <entry>\r
410 <literal>file://</literal>\r
411 </entry>\r
412 <entry>\r
413 Direct repository access on local or network drive.\r
414 </entry>\r
415 </row>\r
416 <row>\r
417 <entry>\r
418 <literal>http://</literal>\r
419 </entry>\r
420 <entry>\r
421 Access via WebDAV protocol to Git-aware Apache server.\r
422 </entry>\r
423 </row>\r
424 <row>\r
425 <entry>\r
426 <literal>https://</literal>\r
427 </entry>\r
428 <entry>\r
429 Same as <literal>http://</literal>, but with SSL encryption.\r
430 </entry>\r
431 </row>\r
432 <row>\r
433 <entry>\r
434 <literal>svn://</literal>\r
435 </entry>\r
436 <entry>\r
437 Unauthenticated TCP/IP access via custom protocol\r
438 to a <literal>svnserve</literal> server.\r
439 </entry>\r
440 </row>\r
441 <row>\r
442 <entry>\r
443 <literal>svn+ssh://</literal>\r
444 </entry>\r
445 <entry>\r
446 authenticated, encrypted TCP/IP access via custom protocol\r
447 to a <literal>svnserve</literal> server.\r
448 </entry>\r
449 </row>\r
450 </tbody>\r
451 </tgroup>\r
452 </table>\r
453 <para>\r
454 For the most part, Git's URLs use the standard\r
455 syntax, allowing for server names and port numbers to be\r
456 specified as part of the URL.\r
457 The <literal>file://</literal> access method is normally used\r
458 for local access, although it can be used with UNC paths to\r
459 a networked host. The URL therefore takes the form\r
460 <systemitem class="url">file://hostname/path/to/repos</systemitem>. For the\r
461 local machine, the <literal>hostname</literal> portion of the URL is required\r
462 to be either absent or <literal>localhost</literal>. For\r
463 this reason, local paths normally appear with three slashes,\r
464 <systemitem class="url">file:///path/to/repos</systemitem>.\r
465 </para>\r
466 <para>\r
467 Also, users of the <literal>file://</literal> scheme on\r
468 Windows platforms will need to use an unofficially\r
469 <quote>standard</quote> syntax for accessing repositories\r
470 that are on the same machine, but on a different drive than\r
471 the client's current working drive. Either of the two\r
472 following URL path syntaxes will work where\r
473 <literal>X</literal> is the drive on which the repository\r
474 resides:\r
475 </para>\r
476 <screen>\r
477 file:///X:/path/to/repos\r
478 ...\r
479 file:///X|/path/to/repos\r
480 ...\r
481 </screen>\r
482 <para>\r
483 Note that a URL uses ordinary slashes even though the native\r
484 (non-URL) form of a path on Windows uses backslashes.\r
485 </para>\r
486 <para>\r
487 You can safely access a FSFS repository via a network share,\r
488 but you <emphasis>cannot</emphasis> access a BDB repository\r
489 in this way.\r
490 </para>\r
491 <warning>\r
492 <para>\r
493 Do not create or access a Berkeley DB repository on a network share.\r
494 It <emphasis>cannot</emphasis> exist on a remote filesystem.\r
495 Not even if you have the network drive mapped to a drive letter.\r
496 If you attempt to use Berkeley DB on a network share,\r
497 the results are unpredictable - you may see mysterious errors\r
498 right away, or it may be months before you discover that your\r
499 repository database is subtly corrupted.\r
500 </para>\r
501 </warning>\r
502 </sect2>\r
503 <sect2 id="tsvn-basics-svn-revisions">\r
504 <title>Revisions</title>\r
505 <indexterm>\r
506 <primary>revision</primary>\r
507 </indexterm>\r
508 <para>\r
509 A <command>svn commit</command> operation can publish\r
510 changes to any number of files and directories as a single\r
511 atomic transaction. In your working copy, you can change\r
512 files' contents, create, delete, rename and copy files and\r
513 directories, and then commit the complete set of changes as a\r
514 unit.\r
515 </para>\r
516 <para>\r
517 In the repository, each commit is treated as an atomic\r
518 transaction: either all the commits changes take place, or\r
519 none of them take place. Git retains this\r
520 atomicity in the face of program crashes, system crashes,\r
521 network problems, and other users' actions.\r
522 </para>\r
523 <para>\r
524 Each time the repository accepts a commit, this creates a\r
525 new state of the filesystem tree, called a\r
526 <firstterm>revision</firstterm>. Each revision is assigned a\r
527 unique natural number, one greater than the number of the\r
528 previous revision. The initial revision of a freshly created\r
529 repository is numbered zero, and consists of nothing but an\r
530 empty root directory.\r
531 </para>\r
532 <para>\r
533 A nice way to visualize the repository is as a series of\r
534 trees. Imagine an array of revision numbers, starting at 0,\r
535 stretching from left to right. Each revision number has a\r
536 filesystem tree hanging below it, and each tree is a\r
537 <quote>snapshot</quote> of the way the repository looked after\r
538 each commit.\r
539 </para>\r
540 <figure id="tsvn-basics-dia7">\r
541 <title>The Repository</title>\r
542 <graphic fileref="images/ch02dia7.png"/>\r
543 </figure>\r
544 <sidebar>\r
545 <title>Global Revision Numbers</title>\r
546 <para>\r
547 Unlike those of many other version control systems,\r
548 Git's revision numbers apply to <emphasis>entire\r
549 trees</emphasis>, not individual files. Each revision\r
550 number selects an entire tree, a particular state of the\r
551 repository after some committed change. Another way to\r
552 think about it is that revision N represents the state of\r
553 the repository filesystem after the Nth commit. When a\r
554 Git user talks about ``revision 5 of\r
555 <filename>foo.c</filename>'', they really mean\r
556 ``<filename>foo.c</filename> as it appears in revision 5.''\r
557 Notice that in general, revisions N and M of a file do\r
558 <emphasis>not</emphasis> necessarily differ!\r
559 </para>\r
560 </sidebar>\r
561 <para>\r
562 It's important to note that working copies do not always\r
563 correspond to any single revision in the repository; they may\r
564 contain files from several different revisions. For example,\r
565 suppose you check out a working copy from a repository whose\r
566 most recent revision is 4:\r
567 </para>\r
568 <screen>\r
569 calc/Makefile:4\r
570 integer.c:4\r
571 button.c:4\r
572 </screen>\r
573 <para>\r
574 At the moment, this working directory corresponds exactly\r
575 to revision 4 in the repository. However, suppose you make a\r
576 change to <filename>button.c</filename>, and commit that\r
577 change. Assuming no other commits have taken place, your\r
578 commit will create revision 5 of the repository, and your\r
579 working copy will now look like this:\r
580 </para>\r
581 <screen>\r
582 calc/Makefile:4\r
583 integer.c:4\r
584 button.c:5\r
585 </screen>\r
586 <para>\r
587 Suppose that, at this point, Sally commits a change to\r
588 <filename>integer.c</filename>, creating revision 6. If you\r
589 use <command>svn update</command> to bring your working copy\r
590 up to date, then it will look like this:\r
591 </para>\r
592 <screen>\r
593 calc/Makefile:6\r
594 integer.c:6\r
595 button.c:6\r
596 </screen>\r
597 <para>\r
598 Sally's changes to <filename>integer.c</filename> will\r
599 appear in your working copy, and your change will still be\r
600 present in <filename>button.c</filename>. In this example,\r
601 the text of <filename>Makefile</filename> is identical in\r
602 revisions 4, 5, and 6, but Git will mark your working\r
603 copy of <filename>Makefile</filename> with revision 6 to\r
604 indicate that it is still current. So, after you do a clean\r
605 update at the top of your working copy, it will generally\r
606 correspond to exactly one revision in the repository.\r
607 </para>\r
608 </sect2>\r
609 <sect2 id="tsvn-basics-svn-wcrepository">\r
610 <title>How Working Copies Track the Repository</title>\r
611 <para>\r
612 For each file in a working directory, Git records\r
613 two essential pieces of information in the\r
614 <filename>.svn/</filename> administrative area:</para>\r
615 <itemizedlist>\r
616 <listitem>\r
617 <para>\r
618 what revision your working file is based on\r
619 (this is called the file's <firstterm>working\r
620 revision</firstterm>), and\r
621 </para>\r
622 </listitem>\r
623 <listitem>\r
624 <para>\r
625 a timestamp recording when the local copy was\r
626 last updated by the repository.\r
627 </para>\r
628 </listitem>\r
629 </itemizedlist>\r
630 <para>\r
631 Given this information, by talking to the repository,\r
632 Git can tell which of the following four states a\r
633 working file is in:\r
634 </para>\r
635 <variablelist>\r
636 <varlistentry>\r
637 <term>Unchanged, and current</term>\r
638 <listitem>\r
639 <para>\r
640 The file is unchanged in the working\r
641 directory, and no changes to that file have been committed\r
642 to the repository since its working revision. A\r
643 <command>commit</command> of the file will do nothing,\r
644 and an <command>update</command> of the file will do\r
645 nothing.\r
646 </para>\r
647 </listitem>\r
648 </varlistentry>\r
649 <varlistentry>\r
650 <term>Locally changed, and current</term>\r
651 <listitem>\r
652 <para>\r
653 The file has been changed in the working\r
654 directory, and no changes to that file have been committed\r
655 to the repository since its base revision. There are local\r
656 changes that have not been committed to the repository, thus\r
657 a <command>commit</command> of the file will succeed in\r
658 publishing your changes, and an <command>update</command>\r
659 of the file will do nothing.\r
660 </para>\r
661 </listitem>\r
662 </varlistentry>\r
663 <varlistentry>\r
664 <term>Unchanged, and out-of-date</term>\r
665 <listitem>\r
666 <para>\r
667 The file has not been changed in the working\r
668 directory, but it has been changed in the repository. The\r
669 file should eventually be updated, to make it current with\r
670 the public revision. A <command>commit</command> of the\r
671 file will do nothing, and an <command>update</command> of\r
672 the file will fold the latest changes into your working\r
673 copy.\r
674 </para>\r
675 </listitem>\r
676 </varlistentry>\r
677 <varlistentry>\r
678 <term>Locally changed, and out-of-date</term>\r
679 <listitem>\r
680 <para>\r
681 The file has been changed both in the\r
682 working directory, and in the repository. A <command>commit</command>\r
683 of the file will fail with an <emphasis>out-of-date</emphasis>\r
684 error. The file should be updated first; an <command>update</command>\r
685 command will attempt to merge the public\r
686 changes with the local changes. If Git can't\r
687 complete the merge in a plausible way automatically, it\r
688 leaves it to the user to resolve the\r
689 conflict.\r
690 </para>\r
691 </listitem>\r
692 </varlistentry>\r
693 </variablelist>\r
694 </sect2>\r
695 </sect1>\r
696 <sect1 id="tsvn-basics-summary">\r
697 <title>Summary</title>\r
698 <para>\r
699 We've covered a number of fundamental Git concepts in\r
700 this chapter:\r
701 </para>\r
702 <itemizedlist>\r
703 <listitem>\r
704 <para>\r
705 We've introduced the notions of the central repository,\r
706 the client working copy, and the array of repository\r
707 revision trees.</para>\r
708 </listitem>\r
709 <listitem>\r
710 <para>\r
711 We've seen some simple examples of how two collaborators\r
712 can use Git to publish and receive changes from one\r
713 another, using the 'copy-modify-merge' model.\r
714 </para>\r
715 </listitem>\r
716 <listitem>\r
717 <para>\r
718 We've talked a bit about the way Git tracks and\r
719 manages information in a working copy.\r
720 </para>\r
721 </listitem>\r
722 </itemizedlist>\r
723 </sect1>\r
724 </chapter>\r
725 <!--\r
726 local variables:\r
727 sgml-parent-document: ("book.xml" "chapter")\r
728 end:\r
729 -->\r