git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
* [PATCH 0/8] Doc/submodules: a few updates
@ 2018-01-06 18:46 Kaartic Sivaraam
  2018-01-08 19:08 ` Stefan Beller
  0 siblings, 1 reply; 4+ messages in thread
From: Kaartic Sivaraam @ 2018-01-06 18:46 UTC (permalink / raw)
  To: Git mailing list, Stefan Beller

These are just a few improvements that I thought would make the documentation
related to submodules a little better in various way such as readability,
consistency etc., These were things I noticed while reading thise documents.

Sorry, for the highly granular patches. I did the commits as and when I was
reading them and tried to keep them focused to one particular change by rebasing
them as needed. In case they need some change, let me know. 

I based these patches on top of 'master'.

Apart from the changes, I saw a few things that needed improvement/clarification
but wasn't able to do that myself due to my limited knowledge of submodules. They
are listed below. I'll add in patches for them if they are correctly clarified.


1.

 man gitsubmodules

       ·   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.

           If the submodule is not yet initialized, then the configuration inside the submodule does not exist yet, so configuration where to
           obtain the submodule from is configured here for example.

What's the "active flag" mentioned above? Also I find the phrase "is recursed into at all"
to be a little slippery. How could it be improved?


2.

 man git submodule

       update
           ...

           checkout
               ....

               If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit
               specified in the index of the containing repository already matches the commit checked out in the submodule.

I'm not sure this is conveying all the information it should be conveying.
It seems to making the user wonder, "How at all does 'git submodule update --force'
differs from 'git submodule update'?" also "using git checkout --force if appropriate"
seems to be invoking all sorts confusion as "appropriate" is superfluous.

How could these confusions be clarified?


---
Kaartic


Kaartic Sivaraam (8):
  Doc/gitsubmodules: split a sentence for better readability
  Doc/gitsubmodules: clearly specify advantage of submodule
  Doc/gitsubmodules: specify how submodules help in reduced size
  Doc/gitsubmodules: avoid abbreviations
  Doc/gitsubmodules: use "Git directory" consistently
  Doc/gitsubmodules: improve readability of certain lines
  Doc/git-submodule: improve readability and grammar of a sentence
  Doc/git-submodule: correctly quote important words

 Documentation/git-submodule.txt | 10 +++++-----
 Documentation/gitsubmodules.txt | 28 ++++++++++++++++------------
 2 files changed, 21 insertions(+), 17 deletions(-)

-- 
2.16.0.rc0.223.g4a4ac8367


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH 0/8] Doc/submodules: a few updates
  2018-01-06 18:46 [PATCH 0/8] Doc/submodules: a few updates Kaartic Sivaraam
@ 2018-01-08 19:08 ` Stefan Beller
  2018-01-09 17:06   ` Kaartic Sivaraam
  0 siblings, 1 reply; 4+ messages in thread
From: Stefan Beller @ 2018-01-08 19:08 UTC (permalink / raw)
  To: Kaartic Sivaraam, Brandon Williams; +Cc: Git mailing list

On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> These are just a few improvements that I thought would make the documentation
> related to submodules a little better in various way such as readability,
> consistency etc., These were things I noticed while reading thise documents.
>
> Sorry, for the highly granular patches. I did the commits as and when I was
> reading them and tried to keep them focused to one particular change by rebasing
> them as needed. In case they need some change, let me know.

While small patches are really appreciated for code (bisect, automated
testing, and
the general difficulty to reason about code, as a very small change
may affect the whole
code base), I am not sure if they benefit in documentation.
Documentation is a rather
local human readable thing, so by changing one sentence we don't
affect the understanding
of documentation at a completely unrelated place.

Also it helps to read more than just sentence fragments, i.e. I tried
looking at the
whole paragraph for review. May I suggest to squash them all and
resend as one patch?


>
> I based these patches on top of 'master'.

I am not aware of other submodule patches affecting documentation in master..pu,
so this should be easy to merge.

>
> Apart from the changes, I saw a few things that needed improvement/clarification
> but wasn't able to do that myself due to my limited knowledge of submodules. They
> are listed below. I'll add in patches for them if they are correctly clarified.
>
>
> 1.
>
>  man gitsubmodules
>
>        ·   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.
>
>            If the submodule is not yet initialized, then the configuration inside the submodule does not exist yet, so configuration where to
>            obtain the submodule from is configured here for example.
>
> What's the "active flag" mentioned above? Also I find the phrase "is recursed into at all"
> to be a little slippery. How could it be improved?

There are multiple ways to indicate if a submodule is "active", i.e. if Git is
supposed to pay attention. Historically we had to set the
submodule.<name>.url flag in the config, but last year Brandon added
submodule.active as well as submodule.<name>.active which supersede
the .url flag.

(See is_submodule_active() in submodule.c to see the definitive answer to
"should Git pay attention?")
https://github.com/git/git/blob/master/submodule.c#L224

I wonder if this indicates a lack of documentation when the active
flags were introduced.
They are found in 'man git config', but maybe we need to spell them
out explicitly
in the submodule related docs.

> 2.
>
>  man git submodule
>
>        update
>            ...
>
>            checkout
>                ....
>
>                If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit
>                specified in the index of the containing repository already matches the commit checked out in the submodule.
>
> I'm not sure this is conveying all the information it should be conveying.
> It seems to making the user wonder, "How at all does 'git submodule update --force'
> differs from 'git submodule update'?" also "using git checkout --force if appropriate"
> seems to be invoking all sorts confusion as "appropriate" is superfluous.

When "submodule update" is invoked with the `--force` flag, that flag is passed
on to the 'checkout' operation. If you do not give the --force, then
the checkout
will also be done without --force.

>
> How could these confusions be clarified?

I tried giving an alternative snippet above, not sure how else to tell.

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH 0/8] Doc/submodules: a few updates
  2018-01-08 19:08 ` Stefan Beller
@ 2018-01-09 17:06   ` Kaartic Sivaraam
  2018-01-09 18:50     ` Stefan Beller
  0 siblings, 1 reply; 4+ messages in thread
From: Kaartic Sivaraam @ 2018-01-09 17:06 UTC (permalink / raw)
  To: Stefan Beller, Brandon Williams; +Cc: Git mailing list

[-- Attachment #1.1: Type: text/plain, Size: 4930 bytes --]

On Tuesday 09 January 2018 12:38 AM, Stefan Beller wrote:
> On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam
> <kaartic.sivaraam@gmail.com> wrote:
> 
> While small patches are really appreciated for code (bisect, automated
> testing, and
> the general difficulty to reason about code, as a very small change
> may affect the whole
> code base), I am not sure if they benefit in documentation.
> Documentation is a rather
> local human readable thing, so by changing one sentence we don't
> affect the understanding
> of documentation at a completely unrelated place.
> 
> Also it helps to read more than just sentence fragments, i.e. I tried
> looking at the
> whole paragraph for review. May I suggest to squash them all and
> resend as one patch?
> 

I wouldn't mind that. I thought it might be easy to find to find the
parts I changed when the patches are small. So, I sent them without
squashing them together. In case you feel it's not worth, let me know so
I'll squash them in.

BTW, in case I did squash them in, would it be nice to keep the commit
subjects of the current patch series as bullet points in the unified
commit message?


> 
>>
>> I based these patches on top of 'master'.
> 
> I am not aware of other submodule patches affecting documentation in master..pu,
> so this should be easy to merge.
> 
>>
>> Apart from the changes, I saw a few things that needed improvement/clarification
>> but wasn't able to do that myself due to my limited knowledge of submodules. They
>> are listed below. I'll add in patches for them if they are correctly clarified.
>>
>>
>> 1.
>>
>>  man gitsubmodules
>>
>>        ·   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.
>>
>>            If the submodule is not yet initialized, then the configuration inside the submodule does not exist yet, so configuration where to
>>            obtain the submodule from is configured here for example.
>>
>> What's the "active flag" mentioned above? Also I find the phrase "is recursed into at all"
>> to be a little slippery. How could it be improved?
> 
> There are multiple ways to indicate if a submodule is "active", i.e. if Git is
> supposed to pay attentio. Historically we had to set the
> submodule.<name>.url flag in the config, but last year Brandon added
> submodule.active as well as submodule.<name>.active which supersede
> the .url flag.
> 
> (See is_submodule_active() in submodule.c to see the definitive answer to
> "should Git pay attention?")
> https://github.com/git/git/blob/master/submodule.c#L224
> 

Thanks for the info!


> I wonder if this indicates a lack of documentation when the active
> flags were introduced.
> They are found in 'man git config', but maybe we need to spell them
> out explicitly
> in the submodule related docs.
> 

Possibly. So, why not in Documentation/gitsubmodules! Here's a replaced
version of that paragraph,

    * The configuration file `$GIT_DIR/config` in the superproject.
   Typically this file is used to specify whether the submodule
   is recursed into at all via the `active` flag for example. A
   submodule is considered active if `submodule.<name>.url` is set
   or if the submodules path is present in `submodule.active` or
   if `submodule.<name>.url` is set.


>> 2.
>>
>>  man git submodule
>>
>>        update
>>            ...
>>
>>            checkout
>>                ....
>>
>>                If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit
>>                specified in the index of the containing repository already matches the commit checked out in the submodule.
>>
>> I'm not sure this is conveying all the information it should be conveying.
>> It seems to making the user wonder, "How at all does 'git submodule update --force'
>> differs from 'git submodule update'?" also "using git checkout --force if appropriate"
>> seems to be invoking all sorts confusion as "appropriate" is superfluous.
> 
> When "submodule update" is invoked with the `--force` flag, that flag is passed
> on to the 'checkout' operation. If you do not give the --force, then
> the checkout
> will also be done without --force.
> 

If that's the case then shouldn't the "if appropriate" part of "(using
git checkout --force if appropriate)" be dropped? That seems to make it
clear, at least for me. Or is intended as '--force' will not be passed
to git checkout all the time?

>>
>> How could these confusions be clarified?
> 
> I tried giving an alternative snippet above, not sure how else to tell.
> 



-- 
Kaartic

Quote: "Be creative. Be adventurous. Be original. And above all else, be
young." - Wonder Woman


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 870 bytes --]

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH 0/8] Doc/submodules: a few updates
  2018-01-09 17:06   ` Kaartic Sivaraam
@ 2018-01-09 18:50     ` Stefan Beller
  0 siblings, 0 replies; 4+ messages in thread
From: Stefan Beller @ 2018-01-09 18:50 UTC (permalink / raw)
  To: Kaartic Sivaraam; +Cc: Brandon Williams, Git mailing list

On Tue, Jan 9, 2018 at 9:06 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> On Tuesday 09 January 2018 12:38 AM, Stefan Beller wrote:
>> On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam
>> <kaartic.sivaraam@gmail.com> wrote:
>>
>> While small patches are really appreciated for code (bisect, automated
>> testing, and
>> the general difficulty to reason about code, as a very small change
>> may affect the whole
>> code base), I am not sure if they benefit in documentation.
>> Documentation is a rather
>> local human readable thing, so by changing one sentence we don't
>> affect the understanding
>> of documentation at a completely unrelated place.
>>
>> Also it helps to read more than just sentence fragments, i.e. I tried
>> looking at the
>> whole paragraph for review. May I suggest to squash them all and
>> resend as one patch?
>>
>
> I wouldn't mind that. I thought it might be easy to find to find the
> parts I changed when the patches are small. So, I sent them without
> squashing them together. In case you feel it's not worth, let me know so
> I'll squash them in.
>
> BTW, in case I did squash them in, would it be nice to keep the commit
> subjects of the current patch series as bullet points in the unified
> commit message?

Sure.

>> I wonder if this indicates a lack of documentation when the active
>> flags were introduced.
>> They are found in 'man git config', but maybe we need to spell them
>> out explicitly
>> in the submodule related docs.
>>
>
> Possibly. So, why not in Documentation/gitsubmodules! Here's a replaced
> version of that paragraph,
>
>     * The configuration file `$GIT_DIR/config` in the superproject.
>    Typically this file is used to specify whether the submodule
>    is recursed into at all via the `active` flag for example. A
>    submodule is considered active if `submodule.<name>.url` is set
>    or if the submodules path is present in `submodule.active` or
>    if `submodule.<name>.url` is set.

I wonder if we'd want to give an example later, and first describe the
mechanics precisely:

   The configuration file `$GIT_DIR/config` in the superproject.
    Git only recurses into active submodules. A submodule is
    considered active (a) if `submodule.<name>.active` is set
    or (b) if the submodules path is matches the pathsepc in
    `submodule.active` or (c) if `submodule.<name>.url` is set.
    (c) is a historical artefact and will be ignored if the pathspec
    set in (b) excludes the submodule. For example:

    [submodule "foo"]
        active = false
        url = https://example.org/foo
    [submodule "bar"]
        active = true
        url = https://example.org/bar
    [submodule "baz"]
        url = https://example.org/baz

    In the above config only the submodule bar and baz are active,
    bar due to (a) and baz due to (c). Another example

    [submodule "foo"]
        active = true
        url = https://example.org/foo
    [submodule "bar"]
        url = https://example.org/bar
    [submodule "baz"]
        url = https://example.org/baz
    [submodule "bob"]
        ignore = true
    [submodule]
        active = b*
        active = (:exclude) baz

    In here all submodules except baz (foo, bar, bob) are active.
    'foo' due to its own active flag and all the others due to the
    submodule active pathspec, which specifies that any submodule
    starting with 'b' except 'baz' are also active, no matter if the .url field
    is present.

>>> 2.
>>>
>>>  man git submodule
>>>
>>>        update
>>>            ...
>>>
>>>            checkout
>>>                ....
>>>
>>>                If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit
>>>                specified in the index of the containing repository already matches the commit checked out in the submodule.
>>>
>>> I'm not sure this is conveying all the information it should be conveying.
>>> It seems to making the user wonder, "How at all does 'git submodule update --force'
>>> differs from 'git submodule update'?" also "using git checkout --force if appropriate"
>>> seems to be invoking all sorts confusion as "appropriate" is superfluous.
>>
>> When "submodule update" is invoked with the `--force` flag, that flag is passed
>> on to the 'checkout' operation. If you do not give the --force, then
>> the checkout
>> will also be done without --force.
>>
>
> If that's the case then shouldn't the "if appropriate" part of "(using
> git checkout --force if appropriate)" be dropped? That seems to make it
> clear, at least for me. Or is intended as '--force' will not be passed
> to git checkout all the time?
>

Yes, essentially we only pass the force flag when we were given the force flag
("when appropriate" :) Not sure how to say that otherwise. But dropping sounds
good)

Stefan

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, back to index

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-01-06 18:46 [PATCH 0/8] Doc/submodules: a few updates Kaartic Sivaraam
2018-01-08 19:08 ` Stefan Beller
2018-01-09 17:06   ` Kaartic Sivaraam
2018-01-09 18:50     ` Stefan Beller

git@vger.kernel.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