threads / patch / 31547

patch, 8 partsDoc clean: add See Also links

Subject: [PATCH 7/8] Doc clean: add See Also links

## tl;dr

6 messages between Sep 16, 2012 and Sep 17, 2012. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

Philip Oakley· Sep 16, 2012, 10:58 UTC · lore

'git clean' is controlled by gitignore, excludes, and core.excludesfile. Provide See Also links for them.

Use of core.excludesfile is implied.

Signed-off-by: Philip Oakley <philipoakley@iee.org>

Show changes to Documentation/git-clean.txt +6 −0

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 79fb984..9a977b7 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -63,6 +63,12 @@ OPTIONS
 	Remove only files ignored by git.  This may be useful to rebuild
 	everything from scratch, but keep manually created files.
 
+SEE ALSO
+--------
+linkgit:gitignore[5]
+linkgit:gitrepository-layout[5]
+The optional configuration variable `core.excludesfile` linkgit:git-config[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite

-- 
1.7.8.msysgit.0

Matthieu Moy· Sep 16, 2012, 12:08 UTC · re: Philip Oakley · lore

Re: [PATCH 7/8] Doc clean: add See Also links

Philip Oakley <philipoakley@iee.org> writes:

Show 11 quoted lines

> --- a/Documentation/git-clean.txt
> +++ b/Documentation/git-clean.txt
> @@ -63,6 +63,12 @@ OPTIONS
>  	Remove only files ignored by git.  This may be useful to rebuild
>  	everything from scratch, but keep manually created files.
>  
> +SEE ALSO
> +--------
> +linkgit:gitignore[5]
> +linkgit:gitrepository-layout[5]
> +The optional configuration variable `core.excludesfile` linkgit:git-config[1]

I think linkgit:gitignore[5] is enough. linkgit:gitrepository-layout[5] is a very general documentation, it's not clear to the reader which part is intended to be read in complement to git-clean, and indeed, the relevant information is already in linkgit:gitignore[5]. Same for core.excludesfile which is already documented in linkgit:gitignore[5].

Otherwise, I suspect we'll end-up having the transitive closure of SEE ALSO in each manpage ...

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Philip Oakley· Sep 16, 2012, 19:21 UTC · re: Matthieu Moy · lore

Re: [PATCH 7/8] Doc clean: add See Also links

On 16/09/12 13:08, Matthieu Moy wrote:

Show 21 quoted lines

> Philip Oakley <philipoakley@iee.org> writes:
>
>> --- a/Documentation/git-clean.txt
>> +++ b/Documentation/git-clean.txt
>> @@ -63,6 +63,12 @@ OPTIONS
>>   	Remove only files ignored by git.  This may be useful to rebuild
>>   	everything from scratch, but keep manually created files.
>>   
>> +SEE ALSO
>> +--------
>> +linkgit:gitignore[5]
>> +linkgit:gitrepository-layout[5]
>> +The optional configuration variable `core.excludesfile` linkgit:git-config[1]
> I think linkgit:gitignore[5] is enough. linkgit:gitrepository-layout[5]
> is a very general documentation, it's not clear to the reader which part
> is intended to be read in complement to git-clean, and indeed, the
> relevant information is already in linkgit:gitignore[5]. Same for
> core.excludesfile which is already documented in linkgit:gitignore[5].
>
> Otherwise, I suspect we'll end-up having the transitive closure of SEE
> ALSO in each manpage ...

I'd added all three partly because of the git add link which went first to the repository layout which didn't help me much without the extra link.

In fact I've lost a patch (a mistaken rebase todo list possibly) to make the three git ignore pattern types more obvious in the documentation, which would probably cover your point.

Philip Oakley· Sep 16, 2012, 20:02 UTC · re: Philip Oakley · lore

Re: [PATCH 7/8] Doc clean: add See Also links

On 16/09/12 20:21, Philip Oakley wrote:

Show 19 quoted lines

> On 16/09/12 13:08, Matthieu Moy wrote:
>> Philip Oakley <philipoakley@iee.org> writes:
>>
>>> --- a/Documentation/git-clean.txt
>>> +++ b/Documentation/git-clean.txt
>>> @@ -63,6 +63,12 @@ OPTIONS
>>>       Remove only files ignored by git.  This may be useful to rebuild
>>>       everything from scratch, but keep manually created files.
>>>   +SEE ALSO
>>> +--------
>>> +linkgit:gitignore[5]
>>> +linkgit:gitrepository-layout[5]
>>> +The optional configuration variable `core.excludesfile`
>>> linkgit:git-config[1]
>> I think linkgit:gitignore[5] is enough. <snip>
>
> In fact I've lost a patch (a mistaken rebase todo list possibly) to
> make the three git ignore pattern types more obvious in the
> documentation, which would probably cover your point.

False alarm. It was patch 5/8, with the spelling mistake. sorry.

Junio C Hamano· Sep 17, 2012, 05:00 UTC · re: Matthieu Moy · lore

Re: [PATCH 7/8] Doc clean: add See Also links

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

Show 22 quoted lines

> Philip Oakley <philipoakley@iee.org> writes:
>
>> --- a/Documentation/git-clean.txt
>> +++ b/Documentation/git-clean.txt
>> @@ -63,6 +63,12 @@ OPTIONS
>>  	Remove only files ignored by git.  This may be useful to rebuild
>>  	everything from scratch, but keep manually created files.
>>  
>> +SEE ALSO
>> +--------
>> +linkgit:gitignore[5]
>> +linkgit:gitrepository-layout[5]
>> +The optional configuration variable `core.excludesfile` linkgit:git-config[1]
>
> I think linkgit:gitignore[5] is enough. linkgit:gitrepository-layout[5]
> is a very general documentation, it's not clear to the reader which part
> is intended to be read in complement to git-clean, and indeed, the
> relevant information is already in linkgit:gitignore[5]. Same for
> core.excludesfile which is already documented in linkgit:gitignore[5].
>
> Otherwise, I suspect we'll end-up having the transitive closure of SEE
> ALSO in each manpage ...

Concurred.  Thanks.

Philip Oakley· Sep 17, 2012, 22:19 UTC · re: Junio C Hamano · lore

Re: [PATCH 7/8] Doc clean: add See Also links

From: "Junio C Hamano" <gitster@pobox.com>

Show 32 quoted lines

> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>
>> Philip Oakley <philipoakley@iee.org> writes:
>>
>>> --- a/Documentation/git-clean.txt
>>> +++ b/Documentation/git-clean.txt
>>> @@ -63,6 +63,12 @@ OPTIONS
>>>  Remove only files ignored by git.  This may be useful to rebuild
>>>  everything from scratch, but keep manually created files.
>>>
>>> +SEE ALSO
>>> +--------
>>> +linkgit:gitignore[5]
>>> +linkgit:gitrepository-layout[5]
>>> +The optional configuration variable `core.excludesfile` 
>>> linkgit:git-config[1]
>>
>> I think linkgit:gitignore[5] is enough. 
>> linkgit:gitrepository-layout[5]
>> is a very general documentation, it's not clear to the reader which 
>> part
>> is intended to be read in complement to git-clean, and indeed, the
>> relevant information is already in linkgit:gitignore[5]. Same for
>> core.excludesfile which is already documented in 
>> linkgit:gitignore[5].
>>
>> Otherwise, I suspect we'll end-up having the transitive closure of 
>> SEE
>> ALSO in each manpage ...
>
> Concurred.  Thanks.
> --

The improved layout of gitignore in patch 5/8 should cover it. The three links came about because of the initial 'git add' patch 6/8.

I'll update (though probably tomorrow night..).