fast-export: do automatic reencoding of commit messages only if requested

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index dffa14a7950e074bbff73ec79defdbbdcc9702be..774cecc7ede787d22da5b656fe5299e4830d1d2e 100644 (file)
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -57,7 +57,7 @@ OPTIONS
        `xx`; for example `%00` interpolates to `\0` (NUL),
        `%09` to `\t` (TAB) and `%0a` to `\n` (LF).
 
---color[=<when>]:
+--color[=<when>]::
        Respect any colors specified in the `--format` option. The
        `<when>` field must be one of `always`, `never`, or `auto` (if
        `<when>` is absent, behave as if `always` was given).
@@ -121,20 +121,25 @@ refname::
        stripping with positive <N>, or it becomes the full refname if
        stripping with negative <N>.  Neither is an error.
 +
-`strip` can be used as a synomym to `lstrip`.
+`strip` can be used as a synonym to `lstrip`.
 
 objecttype::
        The type of the object (`blob`, `tree`, `commit`, `tag`).
 
 objectsize::
        The size of the object (the same as 'git cat-file -s' reports).
-
+       Append `:disk` to get the size, in bytes, that the object takes up on
+       disk. See the note about on-disk sizes in the `CAVEATS` section below.
 objectname::
        The object name (aka SHA-1).
        For a non-ambiguous abbreviation of the object name append `:short`.
        For an abbreviation of the object name with desired length append
        `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The
        length may be exceeded to ensure unique object names.
+deltabase::
+       This expands to the object name of the delta base for the
+       given object, if it is stored as a delta.  Otherwise it
+       expands to the null object name (all zeroes).
 
 upstream::
        The name of a local ref which can be considered ``upstream''
@@ -361,6 +366,20 @@ This prints the authorname, if present.
 git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
 ------------
 
+CAVEATS
+-------
+
+Note that the sizes of objects on disk are reported accurately, but care
+should be taken in drawing conclusions about which refs or objects are
+responsible for disk usage. The size of a packed non-delta object may be
+much larger than the size of objects which delta against it, but the
+choice of which object is the base and which is the delta is arbitrary
+and is subject to change during a repack.
+
+Note also that multiple copies of an object may be present in the object
+database; in this case, it is undefined which copy's size or delta base
+will be reported.
+
 SEE ALSO
 --------
 linkgit:git-show-ref[1]