Junio C Hamano <gitster@xxxxxxxxx> writes: > Nguyễn Thái Ngọc Duy <pclouds@xxxxxxxxx> writes: > >> Still draft for discussion. Small clarifications and corrections. > ... 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. >> +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". >> +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/; >> +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... >> +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/; > 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html