Re: [PATCH/RFC v2] Document format of basic Git objects
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Feb 19, 2012, 09:14 UTC
- Message-ID
- <7vboovp4lv.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <7vlinzp67m.fsf@alter.siamese.dyndns.org>
Junio C Hamano <gitster@pobox.com> writes:
> Nguyễn Thái Ngọc Duy <pclouds@gmail.com> writes: > >> Still draft for discussion.
Small clarifications and corrections.
Show 6 quoted lines
> ... from a larger > workflow point of view it would not be so useful, as it would involve > steps like this: > > ... > * Then you give the general public the resulting commit.
The point of the above is *not* that it involves hash-object or having to preserve both author and committer dates when secondary signers sign the commit---these are something the tool *could* learn to assist. The point is that adding more signatures *must* change the resulting commit object name, making it necessary not to expose it to the general public in order to avoid history rewinding, which *is* what makes it "not so useful".
And that is why I didn't add such a tool support to help producing the end result that wouldn't be so useful anyway.
Show 9 quoted lines
>> +TREE OBJECTS >> +------------ >> +Tree object payload contains a list of entries, each with a mode, >> +object type, object name, and filename, sorted by filename. It >> +represents the contents of a single directory tree. > > Drop "object type," from this list. It is inferred from the mode. I > personally would prefer to say "path" or "pathname" when the entity > referred to may not be a regular file.
The principle is not to say "filename" to give an incorrect impression that we are only talking about a regular file. This principle applies to pathnames in general (i.e. covers what is recorded in the index, too), but because we are talking about an entry in a tree, "pathname component" is even better than "path" or "pathname", because it has a specific meaning: one part of pathname delimited by a slash.
POSIX does use "filename" for this purpose (and mentions "pathname component" as a synonym), but if we use the word, without clarifying that this document uses it in the strict POSIX sense, the reader can easily misunderstand that we mean a more general "name of a regular file".
Show 5 quoted lines
>> +The object type may be a blob, representing the contents of a file, >> +another tree, representing the contents of a subdirectory, or a commit >> +(representing a subproject). > > and drop the above line.
Should be obvious from the context, but I meant "drop the above three lines".
> I personally do not think it is necessary to have the above paragraph at > all in this object.
s/in this object/in this document/;
Show 9 quoted lines
>> +Encoding >> +~~~~~~~~ > > "Encoding" is such a loaded word and does not help clarify what this > section is really about, which is "format of a tree entry", or simply > "Entries". > >> +Entries are of variable length and self-delimiting. Each entry >> +consists of
Actually, title this section as "Tree Entries", and begin the paragraph with
Tre entries are of ...delimiting. Each entry consists of...
Show 8 quoted lines
>> +Ident strings >> +~~~~~~~~~~~~~ >> +Ident strings record who's responsible of doing something at what >> +time. For a commit, the ident string in "author" line records who is >> +the author of the associated changes and when the changes are > > s/are/were/, perhaps? Again, what the purpose of this document? If this > were more than to strictly describe the "structure", it is OK and even
s/ more than to/to/;
Show 7 quoted lines
> preferable to leave the meaning the "author" as vague, but if this were > also to suggest the best current practice interpretation, it may be worth > to add something like > > There may be a case where it is difficult to attribute a commit to > a single author; think of it as recording the primary contact, the > person to ask any questions about the commit if needed later.