From 4fd58d46def7aad5dd382cd20768c4cfcd51aba8 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 30 Sep 2007 00:51:14 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.3.3-114-g2a85 --- RelNotes-1.5.3.3.txt | 37 ++++++++++++++++++++++++++++++ core-tutorial.html | 5 ++-- core-tutorial.txt | 3 ++- git-bundle.html | 27 ++++++++++++++-------- git-bundle.txt | 8 +++++++ git-merge.html | 4 ++-- git-merge.txt | 2 +- git-remote.html | 12 +++++++++- git-remote.txt | 6 +++++ git-send-email.html | 12 +++++++++- git-send-email.txt | 5 ++++ git-submodule.html | 5 +++- git-submodule.txt | 3 +++ gitattributes.html | 17 ++++---------- gitattributes.txt | 20 ++++------------ gitignore.html | 4 ++-- gitignore.txt | 2 +- user-manual.html | 46 ++++++++++++++++++++++++++++--------- user-manual.txt | 54 ++++++++++++++++++++++++++++++++++---------- 19 files changed, 200 insertions(+), 72 deletions(-) create mode 100644 RelNotes-1.5.3.3.txt diff --git a/RelNotes-1.5.3.3.txt b/RelNotes-1.5.3.3.txt new file mode 100644 index 000000000..e91bd8416 --- /dev/null +++ b/RelNotes-1.5.3.3.txt @@ -0,0 +1,37 @@ +GIT v1.5.3.3 Release Notes +========================== + +Fixes since v1.5.3.2 +-------------------- + + * git-quiltimport did not like it when a patch described in the + series file does not exist. + + * p4 importer missed executable bit in some cases. + + * The default shell on some FreeBSD did not execute the + argument parsing code correctly and made git unusable. + + * git-svn incorrectly spawned pager even when the user user + explicitly asked not to. + + * sample post-receive hook overquoted the envelope sender + value. + + * git-am got confused when the patch contained a change that is + only about type and not contents. + + * git-mergetool did not show our and their version of the + conflicted file when started from a subdirectory of the + project. + + * git-mergetool did not pass correct options when invoking diff3. + + * git-log sometimes invoked underlying "diff" machinery + unnecessarily. + +-- +exec >/var/tmp/1 +O=v1.5.3.2-29-gb7bb760 +echo O=`git describe refs/heads/maint` +git shortlog --no-merges $O..refs/heads/maint diff --git a/core-tutorial.html b/core-tutorial.html index 67813694e..6b27fbccc 100644 --- a/core-tutorial.html +++ b/core-tutorial.html @@ -1689,7 +1689,8 @@ repositories every once in a while.

convenient to organize your project with an informal hierarchy of developers. Linux kernel development is run this way. There is a nice illustration (page 17, "Merges to Mainline") in -Randy Dunlap's presentation.

+link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf +[Randy Dunlap's presentation].

It should be stressed that this hierarchy is purely informal. There is nothing fundamental in git that enforces the "chain of patch flow" this hierarchy implies. You do not have to pull @@ -1953,7 +1954,7 @@ to follow, not easier.

diff --git a/core-tutorial.txt b/core-tutorial.txt index 4b4fd9a50..6b2590d07 100644 --- a/core-tutorial.txt +++ b/core-tutorial.txt @@ -1459,7 +1459,8 @@ Although git is a truly distributed system, it is often convenient to organize your project with an informal hierarchy of developers. Linux kernel development is run this way. There is a nice illustration (page 17, "Merges to Mainline") in -link:http://tinyurl.com/a2jdg[Randy Dunlap's presentation]. +link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf +[Randy Dunlap's presentation]. It should be stressed that this hierarchy is purely *informal*. There is nothing fundamental in git that enforces the "chain of diff --git a/git-bundle.html b/git-bundle.html index 488544266..81b8a827f 100644 --- a/git-bundle.html +++ b/git-bundle.html @@ -392,13 +392,19 @@ but we can move data from A to B via some mechanism (CD, email, etc). We want to update R2 with developments made on branch master in R1. We set a tag in R1 (lastR2bundle) after the previous such transport, and move it afterwards to help build the bundle.

-

in R1 on A: -$ git-bundle create mybundle master ^lastR2bundle -$ git tag -f lastR2bundle master

+

in R1 on A:

+
+
+
$ git-bundle create mybundle master ^lastR2bundle
+$ git tag -f lastR2bundle master
+

(move mybundle from A to B by some mechanism)

-

in R2 on B: -$ git-bundle verify mybundle -$ git-fetch mybundle refspec

+

in R2 on B:

+
+
+
$ git-bundle verify mybundle
+$ git-fetch mybundle  refspec
+

where refspec is refInBundle:localRef

Also, with something like this in your config:

@@ -408,9 +414,12 @@ fetch = refs/heads/*:refs/remotes/origin/*

You can first sneakernet the bundle file to ~/tmp/file.bdl and then these commands:

-

$ git ls-remote bundle +

+
+
$ git ls-remote bundle
 $ git fetch bundle
-$ git pull bundle

+$ git pull bundle
+

would treat it as if it is talking with a remote side over the network.

@@ -424,7 +433,7 @@ network.

diff --git a/git-bundle.txt b/git-bundle.txt index 5051e2bad..0cc6511bd 100644 --- a/git-bundle.txt +++ b/git-bundle.txt @@ -103,14 +103,20 @@ We set a tag in R1 (lastR2bundle) after the previous such transport, and move it afterwards to help build the bundle. in R1 on A: + +------------ $ git-bundle create mybundle master ^lastR2bundle $ git tag -f lastR2bundle master +------------ (move mybundle from A to B by some mechanism) in R2 on B: + +------------ $ git-bundle verify mybundle $ git-fetch mybundle refspec +------------ where refspec is refInBundle:localRef @@ -124,9 +130,11 @@ Also, with something like this in your config: You can first sneakernet the bundle file to ~/tmp/file.bdl and then these commands: +------------ $ git ls-remote bundle $ git fetch bundle $ git pull bundle +------------ would treat it as if it is talking with a remote side over the network. diff --git a/git-merge.html b/git-merge.html index 888d57bc6..ea8855106 100644 --- a/git-merge.html +++ b/git-merge.html @@ -451,7 +451,7 @@ merge.verbosity message if conflicts were detected. Level 1 outputs only conflicts, 2 outputs conflicts and file changes. Level 5 and above outputs debugging information. The default is level 2. - Can be overriden by GIT_MERGE_VERBOSITY environment variable. + Can be overridden by GIT_MERGE_VERBOSITY environment variable.

@@ -606,7 +606,7 @@ Resolve the conflicts. git-diff would report only the diff --git a/git-merge.txt b/git-merge.txt index 144bc16ff..eae49c487 100644 --- a/git-merge.txt +++ b/git-merge.txt @@ -56,7 +56,7 @@ merge.verbosity:: message if conflicts were detected. Level 1 outputs only conflicts, 2 outputs conflicts and file changes. Level 5 and above outputs debugging information. The default is level 2. - Can be overriden by 'GIT_MERGE_VERBOSITY' environment variable. + Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. HOW MERGE WORKS diff --git a/git-remote.html b/git-remote.html index 4aab497aa..67017358d 100644 --- a/git-remote.html +++ b/git-remote.html @@ -275,6 +275,7 @@ git-remote(1) Manual Page
git-remote git-remote add [-t <branch>] [-m <branch>] [-f] [--mirror] <name> <url> +git-remote rm <name> git-remote show <name> git-remote prune <name> git-remote update [group]
@@ -312,6 +313,15 @@ in the refs/remotes/ namespace, but in refs/heads/. This opti only makes sense in bare repositories.

+rm +
+
+

+Remove the remote named <name>. All remote tracking branches and +configuration settings for the remote are removed. +

+
+
show
@@ -418,7 +428,7 @@ $ git merge origin diff --git a/git-remote.txt b/git-remote.txt index 94b9f1777..027ba11bd 100644 --- a/git-remote.txt +++ b/git-remote.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git-remote' 'git-remote' add [-t ] [-m ] [-f] [--mirror] +'git-remote' rm 'git-remote' show 'git-remote' prune 'git-remote' update [group] @@ -50,6 +51,11 @@ In mirror mode, enabled with `--mirror`, the refs will not be stored in the 'refs/remotes/' namespace, but in 'refs/heads/'. This option only makes sense in bare repositories. +'rm':: + +Remove the remote named . All remote tracking branches and +configuration settings for the remote are removed. + 'show':: Gives some information about the remote . diff --git a/git-send-email.html b/git-send-email.html index 6fe4fe342..45cfbcab1 100644 --- a/git-send-email.html +++ b/git-send-email.html @@ -406,6 +406,16 @@ enabled interface to provide the necessary information.

+--smtp-server-port +
+
+

+ Specifies a port different from the default port (SMTP + servers typically listen to smtp port 25 and ssmtp port + 465). +

+
+
--smtp-user, --smtp-pass
@@ -599,7 +609,7 @@ send_lots_of_email.pl by Greg Kroah-Hartman.

diff --git a/git-send-email.txt b/git-send-email.txt index 1ec61affa..3727776a0 100644 --- a/git-send-email.txt +++ b/git-send-email.txt @@ -91,6 +91,11 @@ The --cc option must be repeated for each user you want on the cc list. `/usr/lib/sendmail` if such program is available, or `localhost` otherwise. +--smtp-server-port:: + Specifies a port different from the default port (SMTP + servers typically listen to smtp port 25 and ssmtp port + 465). + --smtp-user, --smtp-pass:: Username and password for SMTP-AUTH. Defaults are the values of the configuration values 'sendemail.smtpuser' and diff --git a/git-submodule.html b/git-submodule.html index 2474a6d50..cd645cd4f 100644 --- a/git-submodule.html +++ b/git-submodule.html @@ -289,6 +289,9 @@ add repository is cloned at the specified path, added to the changeset and registered in .gitmodules. If no path is specified, the path is deduced from the repository specification. + If the repository url begins with ./ or ../, it is stored as + given but resolved as a relative path from the main project's + url when cloning.

@@ -385,7 +388,7 @@ to each submodule url is "submodule.$name.url".

diff --git a/git-submodule.txt b/git-submodule.txt index 2c48936fc..335e973a6 100644 --- a/git-submodule.txt +++ b/git-submodule.txt @@ -21,6 +21,9 @@ add:: repository is cloned at the specified path, added to the changeset and registered in .gitmodules. If no path is specified, the path is deduced from the repository specification. + If the repository url begins with ./ or ../, it is stored as + given but resolved as a relative path from the main project's + url when cloning. status:: Show the status of the submodules. This will print the SHA-1 of the diff --git a/gitattributes.html b/gitattributes.html index 5426ddf13..b9f30121d 100644 --- a/gitattributes.html +++ b/gitattributes.html @@ -419,12 +419,6 @@ upon checkout.

sign $ upon checkout. Any byte sequence that begins with $Id: and ends with $ in the worktree file is replaced with $Id$ upon check-in.

-

Interaction between checkin/checkout attributes

-

In the check-in codepath, the worktree file is first converted -with ident (if specified), and then with crlf (again, if -specified and applicable).

-

In the check-out codepath, the blob content is first converted -with crlf, and then ident.

filter

A filter attribute can be set to a string value. This names filter driver specified in the configuration.

@@ -439,11 +433,10 @@ but makes the filter a no-op passthru.

The content filtering is done to massage the content into a shape that is more convenient for the platform, filesystem, and the user to use. The keyword here is "more convenient" and not -"turning something unusable into usable". In other words, it is -"hanging yourself because we gave you a long rope" if your -project uses filtering mechanism in such a way that it makes -your project unusable unless the checkout is done with a -specific filter in effect.

+"turning something unusable into usable". In other words, the +intent is that if someone unsets the filter driver definition, +or does not have the appropriate filter program, the project +should still be usable.

Interaction between checkin/checkout attributes

In the check-in codepath, the worktree file is first converted with filter driver (if specified and corresponding driver @@ -709,7 +702,7 @@ commit hash.

diff --git a/gitattributes.txt b/gitattributes.txt index d0e951ee6..20cf8ff81 100644 --- a/gitattributes.txt +++ b/gitattributes.txt @@ -145,17 +145,6 @@ sign `$` upon checkout. Any byte sequence that begins with with `$Id$` upon check-in. -Interaction between checkin/checkout attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the check-in codepath, the worktree file is first converted -with `ident` (if specified), and then with `crlf` (again, if -specified and applicable). - -In the check-out codepath, the blob content is first converted -with `crlf`, and then `ident`. - - `filter` ^^^^^^^^ @@ -175,11 +164,10 @@ but makes the filter a no-op passthru. The content filtering is done to massage the content into a shape that is more convenient for the platform, filesystem, and the user to use. The keyword here is "more convenient" and not -"turning something unusable into usable". In other words, it is -"hanging yourself because we gave you a long rope" if your -project uses filtering mechanism in such a way that it makes -your project unusable unless the checkout is done with a -specific filter in effect. +"turning something unusable into usable". In other words, the +intent is that if someone unsets the filter driver definition, +or does not have the appropriate filter program, the project +should still be usable. Interaction between checkin/checkout attributes diff --git a/gitignore.html b/gitignore.html index 33da1ff3b..081751682 100644 --- a/gitignore.html +++ b/gitignore.html @@ -294,7 +294,7 @@ Patterns read from the command line for those commands that support

Patterns read from a .gitignore file in the same directory as the path, or in any parent directory, with patterns in the - higher level files (up to the root) being overriden by those in + higher level files (up to the root) being overridden by those in lower level files down to the directory containing the file. These patterns match relative to the location of the .gitignore file. A project normally includes such @@ -412,7 +412,7 @@ Frank Lichtenheld, and the git-list <git@vger.kernel.org>.

diff --git a/gitignore.txt b/gitignore.txt index 9c8309569..e8b8581f5 100644 --- a/gitignore.txt +++ b/gitignore.txt @@ -26,7 +26,7 @@ precedence, the last matching pattern decides the outcome): * Patterns read from a `.gitignore` file in the same directory as the path, or in any parent directory, with patterns in the - higher level files (up to the root) being overriden by those in + higher level files (up to the root) being overridden by those in lower level files down to the directory containing the file. These patterns match relative to the location of the `.gitignore` file. A project normally includes such diff --git a/user-manual.html b/user-manual.html index 74fbf5152..0cd9d452f 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. 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 +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 @@ -1182,8 +1182,7 @@ contents (including, recursively, the contents of all subdirectories) are identical. This allows git to quickly determine the differences between two related tree objects, since it can ignore any entries with identical object names.

(Note: in the presence of submodules, trees may also have commits as -entries. See git-submodule(1) and gitmodules.txt(1) -for partial documentation.)

Note that the files all have mode 644 or 755: git actually only pays +entries. See Chapter 8, Submodules for documentation.)

Note that the files all have mode 644 or 755: git actually only pays attention to the executable bit.

Blob Object

You can use git-show(1) to examine the contents of a blob; take, for example, the blob in the entry for "COPYING" from the tree above:

$ git show 6ff87c4664

@@ -1333,10 +1332,35 @@ 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. 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 +information as long as you have the name of the tree that it described.

Chapter 8. Submodules

Table of Contents

Pitfalls with submodules

Large projects are often composed of smaller, self-contained modules. For +example, an embedded Linux distribution's source tree would include every +piece of software in the distribution with some local modifications; a movie +player might need to build against a specific, known-working version of a +decompression library; several independent programs might all share the same +build scripts.

With centralized revision control systems this is often accomplished by +including every module in one single repository. Developers can check out +all modules or only the modules they need to work with. They can even modify +files across several modules in a single commit while moving things around +or updating APIs and translations.

Git does not allow partial checkouts, so duplicating this approach in Git +would force developers to keep a local copy of modules they are not +interested in touching. Commits in an enormous checkout would be slower +than you'd expect as Git would have to scan every directory for changes. +If modules have a lot of local history, clones would take forever.

On the plus side, distributed revision control systems can much better +integrate with external sources. In a centralized model, a single arbitrary +snapshot of the external project is exported from its own revision control +and then imported into the local revision control on a vendor branch. All +the history is hidden. With distributed revision control you can clone the +entire external history and much more easily follow development and re-merge +local changes.

Git's submodule support allows a repository to contain, as a subdirectory, a +checkout of an external project. Submodules maintain their own identity; +the submodule support just stores the submodule repository location and +commit ID, so other developers who clone the containing project +("superproject") can easily clone all the submodules at the same revision. +Partial checkouts of the superproject are possible: you can tell Git to +clone none, some or all of the submodules.

The git-submodule(1) command is available since Git 1.5.3. Users +with Git 1.5.2 can look up the submodule commits in the repository and +manually check them out; earlier versions won't recognize the submodules at +all.

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
@@ -1359,8 +1383,8 @@ done

  • -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 clone path to the gitmodules(5) 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. @@ -1402,7 +1426,7 @@ index d266b98..261dfac 160000
    $ 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 +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
    @@ -2326,4 +2350,4 @@ temporary branch creation?

    Add more good examples. Entire sections of jus might be a good idea; maybe make an "advanced examples" section a standard end-of-chapter section?

    Include cross-references to the glossary, where appropriate.

    Document shallow clones? See draft 1.5.0 release notes for some documentation.

    Add a section on working with other version control systems, including -CVS, Subversion, and just imports of series of release tarballs.

    More details on gitweb?

    Write a chapter on using plumbing and writing scripts.

    Alternates, clone -reference, etc.

    git unpack-objects -r for recovery

    submodules

    +CVS, Subversion, and just imports of series of release tarballs.

    More details on gitweb?

    Write a chapter on using plumbing and writing scripts.

    Alternates, clone -reference, etc.

    git unpack-objects -r for recovery

    diff --git a/user-manual.txt b/user-manual.txt index a085ca1d3..c7fdf25e2 100644 --- a/user-manual.txt +++ b/user-manual.txt @@ -2856,8 +2856,7 @@ between two related tree objects, since it can ignore any entries with identical object names. (Note: in the presence of submodules, trees may also have commits as -entries. See gitlink:git-submodule[1] and gitlink:gitmodules.txt[1] -for partial documentation.) +entries. See <> for documentation.) Note that the files all have mode 644 or 755: git actually only pays attention to the executable bit. @@ -3163,12 +3162,45 @@ information as long as you have the name of the tree that it described. 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. +Large projects are often composed of smaller, self-contained modules. For +example, an embedded Linux distribution's source tree would include every +piece of software in the distribution with some local modifications; a movie +player might need to build against a specific, known-working version of a +decompression library; several independent programs might all share the same +build scripts. + +With centralized revision control systems this is often accomplished by +including every module in one single repository. Developers can check out +all modules or only the modules they need to work with. They can even modify +files across several modules in a single commit while moving things around +or updating APIs and translations. + +Git does not allow partial checkouts, so duplicating this approach in Git +would force developers to keep a local copy of modules they are not +interested in touching. Commits in an enormous checkout would be slower +than you'd expect as Git would have to scan every directory for changes. +If modules have a lot of local history, clones would take forever. + +On the plus side, distributed revision control systems can much better +integrate with external sources. In a centralized model, a single arbitrary +snapshot of the external project is exported from its own revision control +and then imported into the local revision control on a vendor branch. All +the history is hidden. With distributed revision control you can clone the +entire external history and much more easily follow development and re-merge +local changes. + +Git's submodule support allows a repository to contain, as a subdirectory, a +checkout of an external project. Submodules maintain their own identity; +the submodule support just stores the submodule repository location and +commit ID, so other developers who clone the containing project +("superproject") can easily clone all the submodules at the same revision. +Partial checkouts of the superproject are possible: you can tell Git to +clone none, some or all of the submodules. + +The gitlink:git-submodule[1] command is available since Git 1.5.3. Users +with Git 1.5.2 can look up the submodule commits in the repository and +manually check them out; earlier versions won't recognize the submodules at +all. To see how submodule support works, create (for example) four example repositories that can be used later as a submodule: @@ -3213,8 +3245,8 @@ 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 clone path to the gitlink:gitmodules[5] 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. @@ -4277,5 +4309,3 @@ Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. git unpack-objects -r for recovery - -submodules -- 2.26.2