Re: Submodules
Ok, this is my second try.
- Incorporated Sven's suggestion to give an example of
problematic situation on submodule after "git-checkout" at
the supermodule level;
- Describe semantic clean-up of specifying GIT_DIR that is
not strictly needed (because it is situated at the normal
place relative to the working tree).
---
diff --git a/Documentation/RelNotes-1.5.3.txt b/Documentation/RelNotes-1.5.3.txt
index 21bb1fc..bf7a341 100644
--- a/Documentation/RelNotes-1.5.3.txt
+++ b/Documentation/RelNotes-1.5.3.txt
@@ -9,6 +9,40 @@ Updates since v1.5.2
* The submodule support has Porcelain layer.
+ Note that the current submodule support is minimal and this is
+ deliberately so. A design decision we made is that operations
+ at the supermodule level do not recurse into submodules by
+ default. The expectation is that later we would add a
+ mechanism to tell git which submodules the user is interested
+ in, and this information might be used to determine the
+ recursive behaviour of certain commands (e.g. "git checkout"
+ and "git diff"), but currently we haven't agreed on what that
+ mechanism should look like. In particular, if you have any
+ submodules checked out, running a "git checkout" at the
+ supermodule level will not update these submodules. They will
+ therefore appear to be modified (to the state prior to the
+ checkout) to any subsequent git command, until they have been
+ updated explicitly using "git submodule update".
+
+* You can have a work tree not at the parent directory of .git
+ which is the repository. This is done with GIT_WORK_TREE
+ environment, or --work-tree option.
+
+ This support slightly changes the semantics of having GIT_DIR
+ environment variable. The rule used to be that when it is
+ given, you are supposed to be at the top level of the working
+ tree. However, if it names a .git directory at the top of the
+ working tree, you can be in a subdirectory of that directory
+ and git notices you are in the subdirectory. E.g. in t/
+ subdirectory of git.git project,
+
+ $ cd t
+ $ GIT_DIR=../.git/ git ls-files -s
+
+ will list the files in t/ (i.e. your current directory). It
+ used not to notice that you are in a subdirectory and listed
+ the files from the top-level of the working tree.
+
* There are a handful pack-objects changes to help you cope better
with repositories with pathologically large blobs in them.
Junio C Hamano <gitster@pobox.com>