Re: [PATCH] Clarify role of init command in git-submodules documentation
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Aug 20, 2007, 21:14 UTC
- Message-ID
- <7vd4xhsybm.fsf@gitster.siamese.dyndns.org>
- In-Reply-To
- <11875937841178-git-send-email-madduck@madduck.net>
"martin f. krafft" <madduck@madduck.net> writes:
> As per the discussion in this thread: > > http://marc.info/?t=118721709500008&r=1&w=2
I'd rather see you summarize the conclusion of the thread here. Having the URL as additional supporting reference is fine, but when one reviews the "git log" output, one is not necessarily online.
> this patch updates the git-submodules documentation to make the situation > a bit clearer and documents the intended workflow. > > Signed-off-by: martin f. krafft <madduck@madduck.net>
Thanks. Some comments.
Show 12 quoted lines
> --- > ... > init:: > - Initialize the submodules, i.e. register in .git/config each submodule > - name and url found in .gitmodules. The key used in .git/config is > - `submodule.$name.url`. This command does not alter existing information > - in .git/config. > + Initialize the submodules, i.e. register in $GIT_DIR/config each > + submodule name and url found in .gitmodules. The key used in > + $GIT_DIR/config is `submodule.$name.url`. This command does not alter > + existing information in $GIT_DIR/config, it only serves to initialise > + the local configuration from the defaults in .gitmodules.
s/initialise/initialize/;
Show 8 quoted lines
> FILES > ----- > -When initializing submodules, a .gitmodules file in the top-level directory > -of the containing repository is used to find the url of each submodule. > -This file should be formatted in the same way as $GIR_DIR/config. The key > -to each submodule url is "submodule.$name.url". > +To work with submodules, a user has to prepare a repository clone with the > +command `git-submodule init`.
Is it "a user _has_ to"? Or "a user can use 'git submodule init' to prepare?"
Another thing that bothers me with this description is this. Imagine you are a complete "git submodule" newbie (say, myself), and want to try applying this facility to your own project (say, git.git). So I first remove git-gui from git.git repository and then try to add git-gui.git from Shawn as a submodule. Surely, I am interested in the recipe "To work with submodules" at this point, right? Does that description apply to me? Not really.
So this is not about "_has_ to" at all. It is more like...
You may want to work on a project you cloned from somebody
else (we call that 'the superproject'), and find that the
superproject has .gitmodules file at the top. This file
lists the subprojects that can be checked out in the
superproject. To make a checkout of the subprojects of the
superproject you are interested in, you can use "git
submodule init" to help you prime data about submodules in
.git/config of the superproject.> .... This command copies the url of each submodule > +listed in the .gitmodules file in the top-level directory of the containing > +repository to $GIT_DIR/config. The key to each submodule url is > +"submodule.$name.url".
I think we've seen most of that description in the above 'init::'.
I've read Sven's description on two files. My suspicion is that instead of saying there are two files involved, it may be easier to understand if we tell the story like this:
- "git submodule" subcommands typically use data from the git configuration "submodule.$name.$key";
- Definition of $name (e.g. it is just a logical token, not necessarily the directory name, i.e. moving a subproject to another directory does not have to change the $name).
- Definition of possible $key (e.g. 'url'; others?)
- After the initial clone of the superproject, you would not have any of the necessary configuration variables in _your_ copy of the superproject. There is a facility to help you prime that information. The project gives you .gitmodules, and the tool gives you "git submodule init" to read from it. Here is what the subcommand does...