From: Jonathan Tan <firstname.lastname@example.org> To: Stefan Beller <email@example.com> Cc: Git mailing list <firstname.lastname@example.org>, Brandon Williams <email@example.com>, Jonathan Nieder <firstname.lastname@example.org>, Junio C Hamano <email@example.com> Subject: Re: [PATCHv2] submodules: overhaul documentation Date: Tue, 20 Jun 2017 20:45:44 -0700 Message-ID: <CAGf8dg+f-RzcT15zofB9xbgEE6nTK+T7awjOHY+KEx7KZ-cPXg@mail.gmail.com> (raw) In-Reply-To: <firstname.lastname@example.org> Thanks, this looks like a good explanation. Some more nits, but overall I feel like I understand this and have learned something from it. On Tue, Jun 20, 2017 at 3:56 PM, Stefan Beller <email@example.com> wrote: > +A submodule is another Git repository tracked inside a repository. > +The tracked repository has its own history, which does not > +interfere with the history of the current repository. > + > +It consists of a tracking subdirectory in the working directory, > +a 'gitlink' in the working tree and an entry in the `.gitmodules` Probably should be `gitlink` (the special quotes), and (optional) s/`gitlink`/`gitlink` object/ because it might not be apparent that gitlink is a type of object. > +file (see linkgit:gitmodules) at the root of the source tree. After reading below, maybe we should mention the Git directory in $GIT_DIR/modules/<submodule name> as part of what a submodule consists of too. > +The tracking subdirectory appears in the main repositorys working s/repositorys/repository's/ (apostrophe is also missing in some other places below) > +tree at the point where the submodules gitlink is tracked in the > +tree. It is empty when the submodule is not populated, otherwise > +it contains the content of the submodule repository. > +The main repository is often referred to as superproject. > + > +The gitlink contains the object name of a particular commit > +of the submodule. > + > +The `.gitmodules` file establishes a relationship between the > +path, which is where the gitlink is in the tree, and the logical > +name, which is used for the location of the submodules git > +directory. The `.gitmodules` file has the same syntax as the > +$Git_DIR/config file and the mapping of path to name Capitalization of $GIT_DIR > +is done via setting `submodule.<name value>.path = <path value>`. (Optional) I would prefer <name> and <path> to be consistent with the following paragraph. > +The submodules git directory is found in in the main repositories > +'$GIT_DIR/modules/<name>' or inside the tracking subdirectory. > + > +Submodules can be used for at least two different use cases: > + > +1. Using another project while maintaining independent history. > + Submodules allow you to contain the working tree of another project > + within your own working tree while keeping the history of both > + projects separate. Also, since submodules are fixed to a an arbitrary > + version, the other project can be independently developed without > + affecting the superproject, allowing the superproject project to > + fix itself to new versions only whenever desired. > + > +2. Splitting a (logically single) project into multiple > + repositories and tying them back together. This can be used to > + overcome current limitations of Gits implementation to have > + finer grained access: > + > +* Size of the git repository > + In its current form Git scales up poorly for very large repositories that > + change a lot, as the history grows very large. > + However you can also use submodules to e.g. hold large binary assets > + and these repositories are then shallowly cloned such that you do not > + have a large history locally. > + > +* Transfer size > + In its current form Git requires the whole working tree present. It > + does not allow partial trees to be transferred in fetch or clone. > + > +* Access control > + By restricting user access to submodules, this can be used to implement > + read/write policies for different users. The bullet points should probably be indented more. [snip] > +Deleting a submodule > +-------------------- > + > +Deleting a submodule can happen on different levels: > + > +1) Removing it from the local working tree without tampering with > + the history of the superproject. > + > +You may no longer need the submodule, but still want to keep it recorded > +in the superproject history as others may have use for it. The command > +`git submodule deinit <submodule path>` will remove any configuration > +entries from the config file, such that the submodule becomes s=config=$GIT_DIR/config= (since there are multiple relevant config files) > +uninitialized. The tracking directory in the superprojects working > +tree that holds the submodules working directory is emptied. > +This step can be undone via `git submodule init`. > + > +2) Remove it from history: > +-- > + git rm <submodule path> > + git commit > +-- > +This removes the submodules gitlink from the superprojects tree, as well > +as removing the entries from the `.gitmodules` file, but keeps the > +local configuration for the submodule. This can be undone using `git revert`. > + > + > +3) Remove the submodules git directory: > + > +When you also want to free up the disk space that the submodules git > +directory uses, you have to delete it manually as this > +step cannot be undone using git tools. It is found in `$GIT_DIR/modules`.
next prev parent reply index Thread overview: 17+ messages in thread (expand / mbox.gz / Atom feed / [top]) 2017-06-07 18:53 [RFC/PATCH] " Stefan Beller 2017-06-13 19:29 ` Junio C Hamano 2017-06-13 21:06 ` Stefan Beller 2017-06-19 18:10 ` Brandon Williams 2017-06-20 21:42 ` Stefan Beller 2017-06-20 18:18 ` Jonathan Tan 2017-06-20 19:15 ` Stefan Beller 2017-06-20 22:56 ` [PATCHv2] " Stefan Beller 2017-06-21 3:45 ` Jonathan Tan [this message] 2017-06-21 17:25 ` Stefan Beller 2017-06-22 17:46 ` Brandon Williams 2017-06-22 18:54 ` Stefan Beller 2017-06-22 20:20 ` Junio C Hamano 2017-06-22 20:27 ` Stefan Beller 2017-06-22 21:03 ` Brandon Williams 2017-06-22 21:09 ` Stefan Beller 2017-06-22 21:01 ` [PATCHv3] " Stefan Beller
Reply instructions: You may reply publically 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 to all the recipients using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=CAGf8dg+f-RzcT15zofB9xbgEE6nTK+T7awjOHY+KEx7KZ-cPXg@mail.gmail.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ /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
firstname.lastname@example.org mailing list mirror (one of many) Archives are clonable: git clone --mirror https://public-inbox.org/git git clone --mirror http://ou63pmih66umazou.onion/git git clone --mirror http://czquwvybam4bgbro.onion/git git clone --mirror http://hjrcffqmbrq6wope.onion/git Newsgroups are available over NNTP: nntp://news.public-inbox.org/inbox.comp.version-control.git nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git nntp://news.gmane.org/gmane.comp.version-control.git note: .onion URLs require Tor: https://www.torproject.org/ or Tor2web: https://www.tor2web.org/ AGPL code for this site: git clone https://public-inbox.org/ public-inbox