From: Junio C Hamano Date: Mon, 24 Sep 2007 01:05:34 +0000 (+0000) Subject: Autogenerated HTML docs for v1.5.3.2-91-g4f337 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=9810d63e3fcf38b02b3ccc9191b4807f7825982e;p=git.git Autogenerated HTML docs for v1.5.3.2-91-g4f337 --- diff --git a/git-lost-found.html b/git-lost-found.html index b265a2e6c..e4096b94a 100644 --- a/git-lost-found.html +++ b/git-lost-found.html @@ -326,7 +326,7 @@ $ git rev-parse not-lost-anymore

Author

-

Written by Junio C Hamano 濱野 純 <junkio@cox.net>

+

Written by Junio C Hamano <gitster@pobox.com>

Documentation

@@ -338,7 +338,7 @@ $ git rev-parse not-lost-anymore
diff --git a/git-lost-found.txt b/git-lost-found.txt index e48607f00..bc739117b 100644 --- a/git-lost-found.txt +++ b/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 -------------- diff --git a/git-pack-objects.html b/git-pack-objects.html index ed4a2ee1b..5048cf55b 100644 --- a/git-pack-objects.html +++ b/git-pack-objects.html @@ -286,14 +286,14 @@ between two repositories, and also is an archival format which 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.

@@ -563,7 +563,7 @@ base-name diff --git a/git-pack-objects.txt b/git-pack-objects.txt index 628f296ce..5237ab0c0 100644 --- a/git-pack-objects.txt +++ b/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. diff --git a/git-prune-packed.html b/git-prune-packed.html index 03af07e0b..ccd833773 100644 --- a/git-prune-packed.html +++ b/git-prune-packed.html @@ -276,7 +276,7 @@ git-prune-packed(1) Manual Page

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.

A pack is a collection of objects, individually compressed, with delta @@ -325,7 +325,7 @@ disk storage, etc.

diff --git a/git-prune-packed.txt b/git-prune-packed.txt index 3800edb7b..9f85f3833 100644 --- a/git-prune-packed.txt +++ b/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. diff --git a/user-manual.html b/user-manual.html index c57fa9aab..74fbf5152 100644 --- a/user-manual.html +++ b/user-manual.html @@ -1,4 +1,4 @@ -Git User's Manual (for version 1.5.3 or newer)

Git User's Manual (for version 1.5.3 or newer)

Table of Contents

Preface
1. Repositories and Branches
How to get a git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content
3. Developing with git
Telling git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by editing history
Checking out an old version of a file
Temporarily setting aside work in progress
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public git repositories
Setting up a public repository
Exporting a git repository via the git protocol
Exporting a git repository via http
Pushing changes to a public repository
Setting up a shared repository
Allowing web browsing of a repository
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git-rebase
Modifying a single commit
Reordering or selecting from a patch series
Other tools
Problems with rewriting history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote branches
7. Git concepts
The Object Database
Commit Object
Tree Object
Blob Object
Trust
Tag Object
How git stores objects efficiently: pack files
Dangling objects
The index
8. Low-level git operations
Object access and manipulation
The Workflow
working directory -> index
index -> object database
object database -> index
index -> working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
9. Hacking git
Object storage format
A birds-eye view of Git's source code
10. GIT Glossary
A. Git Quick Reference
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual

Preface

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic UNIX +Git User's Manual (for version 1.5.3 or newer)

Git User's Manual (for version 1.5.3 or newer)

Table of Contents

Preface
1. Repositories and Branches
How to get a git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content
3. Developing with git
Telling git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by editing history
Checking out an old version of a file
Temporarily setting aside work in progress
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public git repositories
Setting up a public repository
Exporting a git repository via the git protocol
Exporting a git repository via http
Pushing changes to a public repository
Setting up a shared repository
Allowing web browsing of a repository
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git-rebase
Modifying a single commit
Reordering or selecting from a patch series
Other tools
Problems with rewriting history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote branches
7. Git concepts
The Object Database
Commit Object
Tree Object
Blob Object
Trust
Tag Object
How git stores objects efficiently: pack files
Dangling objects
The index
8. Submodules
Pitfalls with submodules
9. Low-level git operations
Object access and manipulation
The Workflow
working directory -> index
index -> object database
object database -> index
index -> working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
10. Hacking git
Object storage format
A birds-eye view of Git's source code
11. GIT Glossary
A. Git Quick Reference
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual

Preface

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of git.

Chapter 1, Repositories and Branches and Chapter 2, Exploring git history explain how to fetch and study a project using git—read these chapters to learn how to build and test a particular version of a software project, search for @@ -190,7 +190,10 @@ The tag "v2.6.18" is short for "refs/tags/v2.6.18".

  • "origin/master" is short for "refs/remotes/origin/master".

    • The full name is occasionally useful if, for example, there ever -exists a tag and a branch with the same name.

    As another useful shortcut, the "HEAD" of a repository can be referred +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 +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".

    For the complete list of paths which git checks for references, and the order it uses to decide which to choose when there are multiple @@ -849,9 +852,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
    @@ -872,11 +875,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)
    @@ -903,7 +905,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
    @@ -1230,7 +1232,7 @@ nLE/L9aUXdWeTFPron96DLA=
    -----END PGP SIGNATURE-----

    See the git-tag(1) command to learn how to create and verify tag objects. (Note that 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/).

    How git stores objects efficiently: pack files

    Newly created objects are initially created in a file named after the +references whose names begin with "refs/tags/").

    How git stores objects efficiently: pack files

    Newly created objects are initially created in a file named after the object's SHA1 hash (stored in .git/objects).

    Unfortunately this system becomes inefficient once a project has a lot of objects. Try this on an old project:

    $ git count-objects
    6930 objects, 47620 kilobytes

    The first number is the number of objects which are kept in @@ -1331,7 +1333,102 @@ column in the git-ls-files(1) outp number, and will take on values other than 0 for files with merge conflicts.

    The index is thus a sort of temporary staging area, which is filled with 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.

    Chapter 8. Low-level git operations

    Table of Contents

    Object access and manipulation
    The Workflow
    working directory -> index
    index -> object database
    object database -> index
    index -> working directory
    Tying it all together
    Examining the data
    Merging multiple trees
    Merging multiple trees, continued

    Many of the higher-level commands were originally implemented as shell +information as long as you have the name of the tree that it described.

    Chapter 8. Submodules

    Table of Contents

    Pitfalls with submodules

    This tutorial explains how to create and publish a repository with submodules +using the 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.

    Chapter 9. Low-level git operations

    Table of Contents

    Object access and manipulation
    The Workflow
    working directory -> index
    index -> object database
    object database -> index
    index -> working directory
    Tying it all together
    Examining the data
    Merging multiple trees
    Merging multiple trees, continued

    Many of the higher-level commands were originally implemented as shell scripts using a smaller core of low-level git commands. These can still be useful when doing unusual things with git, or just as a way to understand its inner workings.

    Object access and manipulation

    The git-cat-file(1) command can show the contents of any object, @@ -1497,7 +1594,7 @@ that path tells git to mark the path resolved.

    The above is the descriptio to help you understand what conceptually happens under the hood. In practice, nobody, not even git itself, uses three git-cat-file for this. There is git-merge-index program that extracts the -stages to temporary files and calls a "merge" script on it:

    $ git-merge-index git-merge-one-file hello.c

    and that is what higher level git merge -s resolve is implemented with.

    Chapter 9. Hacking git

    Table of Contents

    Object storage format
    A birds-eye view of Git's source code

    This chapter covers internal details of the git implementation which +stages to temporary files and calls a "merge" script on it:

    $ git-merge-index git-merge-one-file hello.c

    and that is what higher level git merge -s resolve is implemented with.

    Chapter 10. Hacking git

    Table of Contents

    Object storage format
    A birds-eye view of Git's source code

    This chapter covers internal details of the git implementation which probably only git developers need to understand.

    Object storage format

    All objects have a statically determined "type" which identifies the format of the object (i.e. how it is used, and how it can refer to other objects). There are currently four different object types: "blob", @@ -1615,7 +1712,7 @@ does not illustrate the point!):

    $ git log - and see that it is in commit 18449ab0… Now just copy this object name, and paste it into the command line

    $ git show 18449ab0

    Voila.

    Another example: Find out what to do in order to make some script a builtin:

    $ git log --no-merges --diff-filter=A builtin-*.c

    You see, Git is actually the best tool to find out about the source of Git -itself!

    Chapter 10. GIT Glossary

    +itself!

    Chapter 11. GIT Glossary

    alternate object database
    Via the alternates mechanism, a repository diff --git a/user-manual.txt b/user-manual.txt index ecb2bf93f..a085ca1d3 100644 --- a/user-manual.txt +++ b/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 @@ -3155,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 ========================