From: Jonathan Nieder <jrnieder@gmail.com>
Date: Tue, 18 Jan 2011 22:02:26 GMT
Subject: Re: [PATCH] Documentation/fast-import: put explanation of M 040000 <dataref> "" in context
Message-ID: <20110118220226.GB22763@burratino>
In-Reply-To: <7vk4i1khvp.fsf@alter.siamese.dyndns.org>

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:

>> +++ b/Documentation/git-fast-import.txt
>> @@ -542,7 +542,7 @@ The value of `<path>` must be in canonical form. That is it must not:
>>  * contain the special component `.` or `..` (e.g. `foo/./bar` and
>>    `foo/../bar` are invalid).
>>  
>> -In `040000` mode, `<path>` can be the empty string (`""`)
>> +If `<mode>` is `040000`, `<path>` can be the empty string (`""`)
>>  to specify the root of the tree.
>
> For whom is this paragraph written?  People who produce g-f-i streams, or
> people who interpret somebody else's g-f-i streams?
> 
> I am wondering if it is easier to read if we consistently target the
> former, something like this:
> 
>         The root of the tree can be represented by `<mode> 040000` with an
>         empty string as `<path>`.

Sounds good to me.  I suppose the clause "by <mode> 040000" should just
be left out --- we already explained that directories must have mode
S_IFDIR a few lines earlier.