Documentation: describe the "repository" in repository-layout
Update the introductory part and concisely explain how gitfile is handled, what it is used for and for what effect. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Feb 1, 2013 at 11:26 UTC
7a7d05b62e7d438582395d3d149ecbbebbaa6062
1 file changed
+18
-6
Documentation/gitrepository-layout.txt
+18
-6
@@ -12,12 +12,24 @@ $GIT_DIR/*
12
DESCRIPTION
13
-----------
14
15
-You may find these things in your Git repository (`.git`
16
-directory for a repository associated with your working tree, or
17
-`<project>.git` directory for a public 'bare' repository. It is
18
-also possible to have a working tree where `.git` is a plain
19
-ASCII file containing `gitdir: <path>`, i.e. the path to the
20
-real Git repository).
15
+A Git repository comes in two different flavours:
16
+
17
+ * a `.git` directory at the root of the working tree;
18
+
19
+ * a `<project>.git` directory that is a 'bare' repository
20
+ (i.e. without its own working tree), that is typically used for
21
+ exchanging histories with others by pushing into it and fetching
22
+ from it.
23
+
24
+*Note*: Also you can have a plain text file `.git` at the root of
25
+your working tree, containing `gitdir: <path>` to point at the real
26
+directory that has the repository. This mechanism is often used for
27
+a working tree of a submodule checkout, to allow you in the
28
+containing superproject to `git checkout` a branch that does not
29
+have the submodule. The `checkout` has to remove the entire
30
+submodule working tree, without losing the submodule repository.
31
+
32
+These things may exist in a Git repository.
33
34
objects::
35
Object store associated with this repository. Usually