[RFC/PATCH] hash-object doc: "git hash-object -w" can write invalid objects

[Jonathan Nieder <jrnieder@gmail.com>]

When using "hash-object -w" to create non-blob objects, it is
generally a good policy to run "git fsck" afterward to make sure the
resulting object is valid.  Add a warning to the manpage.

While it at, gently nudge the user of "hash-object -w" toward
higher-level interfaces for creating or modifying trees, commits, and
tags.

Reported-by: Mantas Mikulėnas <grawity@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Hi Mantas,

Mantas Mikulėnas wrote:

> When messing around with various repositories, I noticed that git 1.8
> (currently using 1.8.2.rc0.22.gb3600c3) has problems parsing tag objects
> that have invalid timestamps.
[...]
> Git doesn't handle the resulting tag objects nicely at all. For example,
> running `git cat-file -p` on the new object outputs a really odd
> timestamp "Thu Jun Thu Jan 1 00:16:09 1970 +0016" (I'm guessing it
> parses the year as Unix time),

The usual rule is that with invalid objects (e.g. as detected by "git
fsck"), any non-crash result is acceptable.  Garbage in, garbage out.

>                                and `git show` outright crashes
> (backtrace included below.)

Probably worth fixing.

I notice that git-hash-object(1) doesn't contain any reference to
git-fsck(1).  How about something like this, to start?

Perhaps by default hash-object should automatically fsck the objects
it is asked to create.

Thanks,
Jonathan

 Documentation/git-hash-object.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index 02c1f12..8ed8c6e 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -30,6 +30,8 @@ OPTIONS
 
 -w::
 	Actually write the object into the object database.
+	This does not check that the resulting object is valid;
+	for that, see linkgit:git-fsck[1].
 
 --stdin::
 	Read the object from standard input instead of from a file.
@@ -53,6 +55,14 @@ OPTIONS
 	conversion. If the file is read from standard input then this
 	is always implied, unless the --path option is given.
 
+SEE ALSO
+--------
+linkgit:git-mktree[1],
+linkgit:git-commit-tree[1],
+linkgit:git-tag[1],
+linkgit:git-filter-branch[1],
+sha1sum(1)
+
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
1.8.1.4