From 8fceacee676ba9595a4dfdbe7b9726781bfd3ef9 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 21 Sep 2007 12:52:30 -0700 Subject: Documentation/git-lost-found.txt: drop unnecessarily duplicated name. I only did this back when I wanted to make sure git-log and gitk work properly with non Occidental characters. There is really no reason to keep it around. Signed-off-by: Junio C Hamano --- Documentation/git-lost-found.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index e48607f008..bc739117be 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -65,7 +65,7 @@ $ git rev-parse not-lost-anymore Author ------ -Written by Junio C Hamano 濱野 純 +Written by Junio C Hamano Documentation -------------- -- cgit v1.2.3 From 1e6ab5de4fc4ae2902a09f18fe43249c4d012a35 Mon Sep 17 00:00:00 2001 From: Matt Kraai Date: Fri, 21 Sep 2007 06:43:44 -0700 Subject: Move the paragraph specifying where the .idx and .pack files should be Signed-off-by: Matt Kraai Signed-off-by: Junio C Hamano --- Documentation/git-pack-objects.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index f8a0be3511..d18259d93f 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -25,16 +25,16 @@ is efficient to access. The packed archive format (.pack) is designed to be unpackable without having anything else, but for random access, accompanied with the pack index file (.idx). +Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or +any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) +enables git to read from such an archive. + 'git-unpack-objects' command can read the packed archive and expand the objects contained in the pack into "one-file one-object" format; this is typically done by the smart-pull commands when a pack is created on-the-fly for efficient network transport by their peers. -Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or -any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) -enables git to read from such an archive. - In a packed archive, an object is either stored as a compressed whole, or as a difference from some other object. The latter is often called a delta. -- cgit v1.2.3 From 9c2d28c74e374174de01901238159b63a96a04ba Mon Sep 17 00:00:00 2001 From: Matt Kraai Date: Fri, 21 Sep 2007 07:37:18 -0700 Subject: Conjugate "search" correctly in the git-prune-packed man page. Signed-off-by: Matt Kraai Signed-off-by: Junio C Hamano --- Documentation/git-prune-packed.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 3800edb7bb..9f85f3833e 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION ----------- -This program search the `$GIT_OBJECT_DIR` for all objects that currently +This program searches the `$GIT_OBJECT_DIR` for all objects that currently exist in a pack file as well as the independent object directories. All such extra objects are removed. -- cgit v1.2.3 From fc74ecc12cd339c6d8abd1c363733e67eb50945c Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 9 Sep 2007 22:07:02 -0400 Subject: user-manual: don't assume refs are stored under .git/refs The scripts taken from Tony Luck's howto assume all refs can be found under .git/refs, but this is not necessarily true, especially since git-gc runs git-pack-refs. Also add a note warning of this in the chapter that introduces refs, and fix the same incorrect assumption in one other spot. Signed-off-by: J. Bruce Fields --- Documentation/user-manual.txt | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index ecb2bf93f2..cf02e14ed0 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -369,6 +369,11 @@ shorthand: The full name is occasionally useful if, for example, there ever exists a tag and a branch with the same name. +(Newly created refs are actually stored in the .git/refs directory, +under the path given by their name. However, for efficiency reasons +they may also be packed together in a single file; see +gitlink:git-pack-refs[1]). + As another useful shortcut, the "HEAD" of a repository can be referred to just using the name of that repository. So, for example, "origin" is usually a shortcut for the HEAD branch in the repository "origin". @@ -2189,9 +2194,9 @@ test|release) git checkout $1 && git pull . origin ;; origin) - before=$(cat .git/refs/remotes/origin/master) + before=$(git rev-parse refs/remotes/origin/master) git fetch origin - after=$(cat .git/refs/remotes/origin/master) + after=$(git rev-parse refs/remotes/origin/master) if [ $before != $after ] then git log $before..$after | git shortlog @@ -2216,11 +2221,10 @@ usage() exit 1 } -if [ ! -f .git/refs/heads/"$1" ] -then +git show-ref -q --verify -- refs/heads/"$1" || { echo "Can't see branch <$1>" 1>&2 usage -fi +} case "$2" in test|release) @@ -2251,7 +2255,7 @@ then git log test..release fi -for branch in `ls .git/refs/heads` +for branch in `git show-ref --heads | sed 's|^.*/||'` do if [ $branch = test -o $branch = release ] then @@ -2946,7 +2950,7 @@ nLE/L9aUXdWeTFPron96DLA= See the gitlink:git-tag[1] command to learn how to create and verify tag objects. (Note that gitlink:git-tag[1] can also be used to create "lightweight tags", which are not tag objects at all, but just simple -references in .git/refs/tags/). +references whose names begin with "refs/tags/"). [[pack-files]] How git stores objects efficiently: pack files -- cgit v1.2.3 From 38a457baae8202e43b092dbb71dca736f6e45600 Mon Sep 17 00:00:00 2001 From: Miklos Vajna Date: Thu, 20 Sep 2007 02:34:14 +0200 Subject: User Manual: add a chapter for submodules Signed-off-by: Michael Smith Signed-off-by: Miklos Vajna Signed-off-by: J. Bruce Fields --- Documentation/user-manual.txt | 202 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) (limited to 'Documentation') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index cf02e14ed0..a085ca1d39 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -3159,6 +3159,208 @@ a tree which you are in the process of working on. If you blow the index away entirely, you generally haven't lost any information as long as you have the name of the tree that it described. +[[submodules]] +Submodules +========== + +This tutorial explains how to create and publish a repository with submodules +using the gitlink:git-submodule[1] command. + +Submodules maintain their own identity; the submodule support just stores the +submodule repository location and commit ID, so other developers who clone the +superproject can easily clone all the submodules at the same revision. + +To see how submodule support works, create (for example) four example +repositories that can be used later as a submodule: + +------------------------------------------------- +$ mkdir ~/git +$ cd ~/git +$ for i in a b c d +do + mkdir $i + cd $i + git init + echo "module $i" > $i.txt + git add $i.txt + git commit -m "Initial commit, submodule $i" + cd .. +done +------------------------------------------------- + +Now create the superproject and add all the submodules: + +------------------------------------------------- +$ mkdir super +$ cd super +$ git init +$ for i in a b c d +do + git submodule add ~/git/$i +done +------------------------------------------------- + +NOTE: Do not use local URLs here if you plan to publish your superproject! + +See what files `git submodule` created: + +------------------------------------------------- +$ ls -a +. .. .git .gitmodules a b c d +------------------------------------------------- + +The `git submodule add` command does a couple of things: + +- It clones the submodule under the current directory and by default checks out + the master branch. +- It adds the submodule's clone path to the `.gitmodules` file and adds this + file to the index, ready to be committed. +- It adds the submodule's current commit ID to the index, ready to be + committed. + +Commit the superproject: + +------------------------------------------------- +$ git commit -m "Add submodules a, b, c and d." +------------------------------------------------- + +Now clone the superproject: + +------------------------------------------------- +$ cd .. +$ git clone super cloned +$ cd cloned +------------------------------------------------- + +The submodule directories are there, but they're empty: + +------------------------------------------------- +$ ls -a a +. .. +$ git submodule status +-d266b9873ad50488163457f025db7cdd9683d88b a +-e81d457da15309b4fef4249aba9b50187999670d b +-c1536a972b9affea0f16e0680ba87332dc059146 c +-d96249ff5d57de5de093e6baff9e0aafa5276a74 d +------------------------------------------------- + +NOTE: The commit object names shown above would be different for you, but they +should match the HEAD commit object names of your repositories. You can check +it by running `git ls-remote ../a`. + +Pulling down the submodules is a two-step process. First run `git submodule +init` to add the submodule repository URLs to `.git/config`: + +------------------------------------------------- +$ git submodule init +------------------------------------------------- + +Now use `git submodule update` to clone the repositories and check out the +commits specified in the superproject: + +------------------------------------------------- +$ git submodule update +$ cd a +$ ls -a +. .. .git a.txt +------------------------------------------------- + +One major difference between `git submodule update` and `git submodule add` is +that `git submodule update` checks out a specific commit, rather than the tip +of a branch. It's like checking out a tag: the head is detached, so you're not +working on a branch. + +------------------------------------------------- +$ git branch +* (no branch) + master +------------------------------------------------- + +If you want to make a change within a submodule and you have a detached head, +then you should create or checkout a branch, make your changes, publish the +change within the submodule, and then update the superproject to reference the +new commit: + +------------------------------------------------- +$ git checkout master +------------------------------------------------- + +or + +------------------------------------------------- +$ git checkout -b fix-up +------------------------------------------------- + +then + +------------------------------------------------- +$ echo "adding a line again" >> a.txt +$ git commit -a -m "Updated the submodule from within the superproject." +$ git push +$ cd .. +$ git diff +diff --git a/a b/a +index d266b98..261dfac 160000 +--- a/a ++++ b/a +@@ -1 +1 @@ +-Subproject commit d266b9873ad50488163457f025db7cdd9683d88b ++Subproject commit 261dfac35cb99d380eb966e102c1197139f7fa24 +$ git add a +$ git commit -m "Updated submodule a." +$ git push +------------------------------------------------- + +You have to run `git submodule update` after `git pull` if you want to update +submodules, too. + +Pitfalls with submodules +------------------------ + +Always publish the submodule change before publishing the change to the +superproject that references it. If you forget to publish the submodule change, +others won't be able to clone the repository: + +------------------------------------------------- +$ cd ~/git/super/a +$ echo i added another line to this file >> a.txt +$ git commit -a -m "doing it wrong this time" +$ cd .. +$ git add a +$ git commit -m "Updated submodule a again." +$ git push +$ cd ~/git/cloned +$ git pull +$ git submodule update +error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git. +Did you forget to 'git add'? +Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a' +------------------------------------------------- + +You also should not rewind branches in a submodule beyond commits that were +ever recorded in any superproject. + +It's not safe to run `git submodule update` if you've made and committed +changes within a submodule without checking out a branch first. They will be +silently overwritten: + +------------------------------------------------- +$ cat a.txt +module a +$ echo line added from private2 >> a.txt +$ git commit -a -m "line added inside private2" +$ cd .. +$ git submodule update +Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b' +$ cd a +$ cat a.txt +module a +------------------------------------------------- + +NOTE: The changes are still visible in the submodule's reflog. + +This is not the case if you did not commit your changes. + [[low-level-operations]] Low-level git operations ======================== -- cgit v1.2.3