From: Philip Oakley <philipoakley@iee.org>
Date: Mon, 02 Sep 2013 22:45:57 GMT
Subject: Re: [PATCH v3 07/11] Documentation/replace: tell that -f option bypasses the type check
Message-ID: <733E4B5A574946859D178D425231C172@PhilipOakley>
In-Reply-To: <20130902222625.GB2668@elie.Belkin>

From: "Jonathan Nieder" <jrnieder@gmail.com>
> Philip Oakley wrote:
>
>> The problem is the file format, in the sense that the earlier `git 
>> cat-file
>> commit $orig` has a human readable output which is a description of 
>> the
>> commit header, rather than the specific binary content.
>
> Ah.  That's the actual "raw" commit object format, though.
>

Aha.. Sudden realisation that the cat-file _is_ the 'raw' format and 
that the sha1's etc are shown in ascii hex, rather than being in a 
compact binary format (same for 'unix' dates etc.)

So the 'human readable' output is exactly the 'type_name' field followed 
by a single space (SP) followed by the sha1 in ascii hex (i.e. 
tree/parent), or appropriate data in the well defined format (for 
author/committer) SP 'email' SP date. etc.

It was the Human readable == Machine readable that I'd missed.

> The manpage for git-cat-file(1) says:
>
> SYNOPSIS
> git cat-file (-t | -s | -e | -p | <type> | --textconv ) <object>
> git cat-file (--batch | --batch-check) < <list-of-objects>
>
> DESCRIPTION
> In its first form, the command provides the content or the
> type of an object in the repository. [...]
>
> OUTPUT
> ...
> If <type> is specified, the raw (though uncompressed)
> contents of the <object> will be returned.
>
> I agree that this isn't as clear as it should be.  I see a few 
> problems:
>
> (1) The synopsis treats "git cat-file -t/-s/-e/-p <object>",
>     "git cat-file --textconv <tree>:<path>", and
>     "git cat-file <type> <object>" as the same form of the command.
>     It would be easier to explain these as three different forms.
>
> (2) There is no EXAMPLES section and no examples.
>
> (3) There is no pointer to the git object formats.  A pointer to a
>     new gitobject(5) manpage would presumably make everything clearer.
>
> https://www.kernel.org/pub/software/scm/git/docs/user-manual.html#examining-the-data
> might be a good source of text to start from for solving (1), since
> it explains the command a little better.

A quick run of the example "git cat-file commit HEAD", seen in the 
context of your email helped me appreciate the situation.

>
> Thanks,
> Jonathan
>

Philip