From: "J. Bruce Fields" <bfields@fieldses.org>
To: Michael Smith <msmith@cbnco.com>
Cc: Miklos Vajna <vmiklos@frugalware.org>, git@vger.kernel.org
Subject: Re: [PATCH] user-manual: Explain what submodules are good for.
Date: Tue, 25 Sep 2007 12:09:05 -0400 [thread overview]
Message-ID: <20070925160905.GF30845@fieldses.org> (raw)
In-Reply-To: <1190724278-8586-1-git-send-email-msmith@cbnco.com>
On Tue, Sep 25, 2007 at 08:44:38AM -0400, Michael Smith wrote:
> Rework the introduction to the Submodules section to explain why
> someone would use them, and fix up submodule references from the
> tree-object and todo sections.
Looks good to me; thanks!
Acked-by: J. Bruce Fields <bfields@citi.umich.edu>
--b.
> Signed-off-by: Michael Smith <msmith@cbnco.com>
> ---
> Documentation/user-manual.txt | 54 +++++++++++++++++++++++++++++++---------
> 1 files changed, 42 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index a085ca1..c7fdf25 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/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 <<submodules>> 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
> --
> 1.5.3
>
prev parent reply other threads:[~2007-09-25 16:09 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2007-09-23 17:27 user-manual changes J. Bruce Fields
2007-09-24 3:14 ` [PATCH] user-manual: Explain what submodules are good for Michael Smith
2007-09-24 21:33 ` J. Bruce Fields
2007-09-25 12:44 ` Michael Smith
2007-09-25 12:44 ` Michael Smith
2007-09-25 16:09 ` J. Bruce Fields [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20070925160905.GF30845@fieldses.org \
--to=bfields@fieldses.org \
--cc=git@vger.kernel.org \
--cc=msmith@cbnco.com \
--cc=vmiklos@frugalware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).