Re: [PATCH v2 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax
On Tue, Jan 9, 2018 at 10:49 PM, Kaartic Sivaraam wrote: > * Only mention porcelain commands in examples > > * Split a sentence for better readability > > * Add missing apostrophes > > * Clearly specify the advantages of using submodules > > * Avoid abbreviations > > * Use "Git" consistently > > * Improve readability of certain lines > > * Clarify when a submodule is considered active > > Helped-by: Eric Sunshine > Helped-by: Stefan Beller > Signed-off-by: Kaartic Sivaraam > --- Thanks for sending it in one patch, Stefan > Documentation/gitsubmodules.txt | 93 > +++-- > 1 file changed, 72 insertions(+), 21 deletions(-) > > diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt > index 46cf120f6..ce2369c2d 100644 > --- a/Documentation/gitsubmodules.txt > +++ b/Documentation/gitsubmodules.txt > @@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit > that the > superproject expects the submodule’s working directory to be at. > > The section `submodule.foo.*` in the `.gitmodules` file gives additional > -hints to Gits porcelain layer such as where to obtain the submodule via > -the `submodule.foo.url` setting. > +hints to Git's porcelain layer. For example, the `submodule.foo.url` > +setting specifies where to obtain the submodule. > > Submodules can be used for at least two different use cases: > > @@ -51,18 +51,21 @@ Submodules can be used for at least two different use > cases: > > 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 > + overcome current limitations of Git's implementation to have > finer grained access: > > -* Size of the git repository: > +* Size of the Git repository: >In its current form Git scales up poorly for large repositories > containing >content that is not compressed by delta computation between trees. > - 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 > + For example, you can use submodules to hold large binary assets > + and these repositories can be 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. > + If the project you work on consists of multiple repositories tied > + together as submodules in a superproject, you can avoid fetching the > + working trees of the repositories you are not interested in. > * Access control: >By restricting user access to submodules, this can be used to implement >read/write policies for different users. > @@ -73,9 +76,10 @@ The configuration of submodules > Submodule operations can be configured using the following mechanisms > (from highest to lowest precedence): > > - * The command line for those commands that support taking submodule specs. > - Most commands have a boolean flag '--recurse-submodules' whether to > - recurse into submodules. Examples are `ls-files` or `checkout`. > + * The command line for those commands that support taking submodules > + as part of their pathspecs. Most commands have a boolean flag > + `--recurse-submodules` which specify whether to recurse into submodules. > + Examples are `grep` and `checkout`. > Some commands take enums, such as `fetch` and `push`, where you can > specify how submodules are affected. > > @@ -87,8 +91,8 @@ Submodule operations can be configured using the following > mechanisms > For example an effect from the submodule's `.gitignore` file > would be observed when you run `git status --ignore-submodules=none` in > the superproject. This collects information from the submodule's working > -directory by running `status` in the submodule, which does pay attention > -to its `.gitignore` file. > +directory by running `status` in the submodule while paying attention > +to the `.gitignore` file of the submodule. > + > The submodule's `$GIT_DIR/config` file would come into play when running > `git push --recurse-submodules=check` in the superproject, as this would > @@ -97,20 +101,20 @@ remotes are configured in the submodule as usual in the > `$GIT_DIR/config` > file. > > * The configuration file `$GIT_DIR/config` in the superproject. > - Typical configuration at this place is controlling if a submodule > - is recursed into at all via the `active` flag for example. > + Git only recurses into active submodules (see 'ACTIVE SUBMODULES' > + section below). The section below is capitalized differently? > + > If the submodule is not yet initialized, then the configuration > -inside the submodule does not exist yet, so configuration where to > +inside
[PATCH v2 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax
* Only mention porcelain commands in examples * Split a sentence for better readability * Add missing apostrophes * Clearly specify the advantages of using submodules * Avoid abbreviations * Use "Git" consistently * Improve readability of certain lines * Clarify when a submodule is considered active Helped-by: Eric Sunshine Helped-by: Stefan Beller Signed-off-by: Kaartic Sivaraam --- Documentation/gitsubmodules.txt | 93 +++-- 1 file changed, 72 insertions(+), 21 deletions(-) diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index 46cf120f6..ce2369c2d 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the superproject expects the submodule’s working directory to be at. The section `submodule.foo.*` in the `.gitmodules` file gives additional -hints to Gits porcelain layer such as where to obtain the submodule via -the `submodule.foo.url` setting. +hints to Git's porcelain layer. For example, the `submodule.foo.url` +setting specifies where to obtain the submodule. Submodules can be used for at least two different use cases: @@ -51,18 +51,21 @@ Submodules can be used for at least two different use cases: 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 + overcome current limitations of Git's implementation to have finer grained access: -* Size of the git repository: +* Size of the Git repository: In its current form Git scales up poorly for large repositories containing content that is not compressed by delta computation between trees. - 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 + For example, you can use submodules to hold large binary assets + and these repositories can be 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. + If the project you work on consists of multiple repositories tied + together as submodules in a superproject, you can avoid fetching the + working trees of the repositories you are not interested in. * Access control: By restricting user access to submodules, this can be used to implement read/write policies for different users. @@ -73,9 +76,10 @@ The configuration of submodules Submodule operations can be configured using the following mechanisms (from highest to lowest precedence): - * The command line for those commands that support taking submodule specs. - Most commands have a boolean flag '--recurse-submodules' whether to - recurse into submodules. Examples are `ls-files` or `checkout`. + * The command line for those commands that support taking submodules + as part of their pathspecs. Most commands have a boolean flag + `--recurse-submodules` which specify whether to recurse into submodules. + Examples are `grep` and `checkout`. Some commands take enums, such as `fetch` and `push`, where you can specify how submodules are affected. @@ -87,8 +91,8 @@ Submodule operations can be configured using the following mechanisms For example an effect from the submodule's `.gitignore` file would be observed when you run `git status --ignore-submodules=none` in the superproject. This collects information from the submodule's working -directory by running `status` in the submodule, which does pay attention -to its `.gitignore` file. +directory by running `status` in the submodule while paying attention +to the `.gitignore` file of the submodule. + The submodule's `$GIT_DIR/config` file would come into play when running `git push --recurse-submodules=check` in the superproject, as this would @@ -97,20 +101,20 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config` file. * The configuration file `$GIT_DIR/config` in the superproject. - Typical configuration at this place is controlling if a submodule - is recursed into at all via the `active` flag for example. + Git only recurses into active submodules (see 'ACTIVE SUBMODULES' + section below). + If the submodule is not yet initialized, then the configuration -inside the submodule does not exist yet, so configuration where to +inside the submodule does not exist yet, so where to obtain the submodule from is configured here for example. - * the `.gitmodules` file inside the superproject. Additionally to the - required mapping between submodule's name and path, a project usually + * The `.gitmodules` file inside the superproject. A project usually uses this file t
