Autogenerated HTML docs for v1.5.0-rc0-g53af9

diff --git a/git-commit-tree.html b/git-commit-tree.html
index cc4e1ee9df6a63d16f2bbf0e39ecf3a7e0b5829b..a68db3628ea90b93d83c16fd75b15ea951f7b33d 100644 (file)
--- a/git-commit-tree.html
+++ b/git-commit-tree.html
@@ -385,6 +385,81 @@ Your sysadmin must hate you!
 </dd>\r
 </dl>\r
 </div>\r
+<h2>Discussion</h2>\r
+<div class="sectionbody">\r
+<p>At the core level, git is character encoding agnostic.</p>\r
+<ul>\r
+<li>\r
+<p>\r
+The pathnames recorded in the index and in the tree objects\r
+   are treated as uninterpreted sequences of non-NUL bytes.\r
+   What readdir(2) returns are what are recorded and compared\r
+   with the data git keeps track of, which in turn are expected\r
+   to be what lstat(2) and creat(2) accepts.  There is no such\r
+   thing as pathname encoding translation.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The contents of the blob objects are uninterpreted sequence\r
+   of bytes.  There is no encoding translation at the core\r
+   level.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The commit log messages are uninterpreted sequence of non-NUL\r
+   bytes.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>Although we encourage that the commit log messages are encoded\r
+in UTF-8, both the core and git Porcelain are designed not to\r
+force UTF-8 on projects.  If all participants of a particular\r
+project find it more convenient to use legacy encodings, git\r
+does not forbid it.  However, there are a few things to keep in\r
+mind.</p>\r
+<ol>\r
+<li>\r
+<p>\r
+<tt>git-commit-tree</tt> (hence, <tt>git-commit</tt> which uses it) issues\r
+  an warning if the commit log message given to it does not look\r
+  like a valid UTF-8 string, unless you explicitly say your\r
+  project uses a legacy encoding.  The way to say this is to\r
+  have core.commitencoding in <tt>.git/config</tt> file, like this:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[core]\r
+        commitencoding = ISO-8859-1</tt></pre>\r
+</div></div>\r
+<p>Commit objects created with the above setting record the value\r
+of <tt>core.commitencoding</tt> in its <tt>encoding</tt> header.  This is to\r
+help other people who look at them later.  Lack of this header\r
+implies that the commit log message is encoded in UTF-8.</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>git-log</tt>, <tt>git-show</tt> and friends looks at the <tt>encoding</tt>\r
+  header of a commit object, and tries to re-code the log\r
+  message into UTF-8 unless otherwise specified.  You can\r
+  specify the desired output encoding with\r
+  <tt>core.logoutputencoding</tt> in <tt>.git/config</tt> file, like this:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[core]\r
+        logoutputencoding = ISO-8859-1</tt></pre>\r
+</div></div>\r
+<p>If you do not have this configuration variable, the value of\r
+<tt>core.commitencoding</tt> is used instead.</p>\r
+</li>\r
+</ol>\r
+<p>Note that we deliberately chose not to re-code the commit log\r
+message when a commit is made to force UTF-8 at the commit\r
+object level, because re-coding to UTF-8 is not necessarily a\r
+reversible operation.</p>\r
+</div>\r
 <h2>See Also</h2>\r
 <div class="sectionbody">\r
 <p><a href="git-write-tree.html">git-write-tree(1)</a></p>\r
@@ -403,7 +478,7 @@ Your sysadmin must hate you!
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 03-Oct-2006 08:40:57 UTC\r
+Last updated 31-Dec-2006 01:19:01 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-commit-tree.txt b/git-commit-tree.txt
index 41d1a1c4b340b17a545feebe9877def8b009933f..77ba96ed8a4820354ef6d2ff4265660385289f3d 100644 (file)
--- a/git-commit-tree.txt
+++ b/git-commit-tree.txt
@@ -81,6 +81,11 @@ Your parents must have hated you!::
 Your sysadmin must hate you!::
     The password(5) name field is longer than a giant static buffer.
 
+Discussion
+----------
+
+include::i18n.txt[]
+
 See Also
 --------
 gitlink:git-write-tree[1]

diff --git a/git-commit.html b/git-commit.html
index 087aa3ef7fe2c5a6cb58329dc1c1e8d98dd152dc..849254d2ccd8b86a0c62d5879dc2bc6c2842b741 100644 (file)
--- a/git-commit.html
+++ b/git-commit.html
@@ -549,6 +549,81 @@ alter the order the changes are committed, because the merge
 should be recorded as a single commit.  In fact, the command\r
 refuses to run when given pathnames (but see <tt>-i</tt> option).</p>\r
 </div>\r
+<h2>DISCUSSION</h2>\r
+<div class="sectionbody">\r
+<p>At the core level, git is character encoding agnostic.</p>\r
+<ul>\r
+<li>\r
+<p>\r
+The pathnames recorded in the index and in the tree objects\r
+   are treated as uninterpreted sequences of non-NUL bytes.\r
+   What readdir(2) returns are what are recorded and compared\r
+   with the data git keeps track of, which in turn are expected\r
+   to be what lstat(2) and creat(2) accepts.  There is no such\r
+   thing as pathname encoding translation.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The contents of the blob objects are uninterpreted sequence\r
+   of bytes.  There is no encoding translation at the core\r
+   level.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The commit log messages are uninterpreted sequence of non-NUL\r
+   bytes.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>Although we encourage that the commit log messages are encoded\r
+in UTF-8, both the core and git Porcelain are designed not to\r
+force UTF-8 on projects.  If all participants of a particular\r
+project find it more convenient to use legacy encodings, git\r
+does not forbid it.  However, there are a few things to keep in\r
+mind.</p>\r
+<ol>\r
+<li>\r
+<p>\r
+<tt>git-commit-tree</tt> (hence, <tt>git-commit</tt> which uses it) issues\r
+  an warning if the commit log message given to it does not look\r
+  like a valid UTF-8 string, unless you explicitly say your\r
+  project uses a legacy encoding.  The way to say this is to\r
+  have core.commitencoding in <tt>.git/config</tt> file, like this:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[core]\r
+        commitencoding = ISO-8859-1</tt></pre>\r
+</div></div>\r
+<p>Commit objects created with the above setting record the value\r
+of <tt>core.commitencoding</tt> in its <tt>encoding</tt> header.  This is to\r
+help other people who look at them later.  Lack of this header\r
+implies that the commit log message is encoded in UTF-8.</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>git-log</tt>, <tt>git-show</tt> and friends looks at the <tt>encoding</tt>\r
+  header of a commit object, and tries to re-code the log\r
+  message into UTF-8 unless otherwise specified.  You can\r
+  specify the desired output encoding with\r
+  <tt>core.logoutputencoding</tt> in <tt>.git/config</tt> file, like this:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[core]\r
+        logoutputencoding = ISO-8859-1</tt></pre>\r
+</div></div>\r
+<p>If you do not have this configuration variable, the value of\r
+<tt>core.commitencoding</tt> is used instead.</p>\r
+</li>\r
+</ol>\r
+<p>Note that we deliberately chose not to re-code the commit log\r
+message when a commit is made to force UTF-8 at the commit\r
+object level, because re-coding to UTF-8 is not necessarily a\r
+reversible operation.</p>\r
+</div>\r
 <h2>ENVIRONMENT VARIABLES</h2>\r
 <div class="sectionbody">\r
 <p>The command specified by either the VISUAL or EDITOR environment\r
@@ -579,7 +654,7 @@ Junio C Hamano &lt;junkio@cox.net&gt;</p>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 16-Dec-2006 07:43:46 UTC\r
+Last updated 31-Dec-2006 01:19:02 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-commit.txt b/git-commit.txt
index 0b74cd708ecaa63ccc19d2db40790b315539ce8b..a7adf24fa5a601f372099988c1fedfb929ceaab1 100644 (file)
--- a/git-commit.txt
+++ b/git-commit.txt
@@ -223,6 +223,11 @@ should be recorded as a single commit.  In fact, the command
 refuses to run when given pathnames (but see `-i` option).
 
 
+DISCUSSION
+----------
+
+include::i18n.txt[]
+
 ENVIRONMENT VARIABLES
 ---------------------
 The command specified by either the VISUAL or EDITOR environment

diff --git a/git-diff-tree.html b/git-diff-tree.html
index a09faf5b8d9aff020cf5b89361531614d7ee67b6..61e5b019fe41b23487e6eefa948b99c8c332cb7a 100644 (file)
--- a/git-diff-tree.html
+++ b/git-diff-tree.html
@@ -847,6 +847,18 @@ simplification into account.</p>
 </ul>\r
 </dd>\r
 <dt>\r
+--encoding[=&lt;encoding&gt;]\r
+</dt>\r
+<dd>\r
+<p>\r
+        The commit objects record the encoding used for the log message\r
+        in their encoding header; this option can be used to tell the\r
+        command to re-code the commit log message in the encoding\r
+        preferred by the user.  For non plumbing commands this\r
+        defaults to UTF-8.\r
+</p>\r
+</dd>\r
+<dt>\r
 --no-commit-id\r
 </dt>\r
 <dd>\r
@@ -1268,7 +1280,7 @@ two unresolved merge parents with the working tree file
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 26-Dec-2006 09:11:33 UTC\r
+Last updated 31-Dec-2006 01:19:02 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-log.html b/git-log.html
index 081201844831029562b4e5fb777890c29128af0d..e963c38e5ba93e2f489a327fd4fdf1e08724f372 100644 (file)
--- a/git-log.html
+++ b/git-log.html
@@ -417,6 +417,18 @@ simplification into account.</p>
 </ul>\r
 </dd>\r
 <dt>\r
+--encoding[=&lt;encoding&gt;]\r
+</dt>\r
+<dd>\r
+<p>\r
+        The commit objects record the encoding used for the log message\r
+        in their encoding header; this option can be used to tell the\r
+        command to re-code the commit log message in the encoding\r
+        preferred by the user.  For non plumbing commands this\r
+        defaults to UTF-8.\r
+</p>\r
+</dd>\r
+<dt>\r
 --max-count=&lt;n&gt;\r
 </dt>\r
 <dd>\r
@@ -429,7 +441,9 @@ simplification into account.</p>
 </dt>\r
 <dd>\r
 <p>\r
-        Show only commits between the named two commits.\r
+        Show only commits between the named two commits.  When\r
+        either &lt;since&gt; or &lt;until&gt; is omitted, it defaults to\r
+        <tt>HEAD</tt>, i.e. the tip of the current branch.\r
 </p>\r
 </dd>\r
 <dt>\r
@@ -492,6 +506,81 @@ git log -r --name-status release..test
 </dd>\r
 </dl>\r
 </div>\r
+<h2>Discussion</h2>\r
+<div class="sectionbody">\r
+<p>At the core level, git is character encoding agnostic.</p>\r
+<ul>\r
+<li>\r
+<p>\r
+The pathnames recorded in the index and in the tree objects\r
+   are treated as uninterpreted sequences of non-NUL bytes.\r
+   What readdir(2) returns are what are recorded and compared\r
+   with the data git keeps track of, which in turn are expected\r
+   to be what lstat(2) and creat(2) accepts.  There is no such\r
+   thing as pathname encoding translation.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The contents of the blob objects are uninterpreted sequence\r
+   of bytes.  There is no encoding translation at the core\r
+   level.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The commit log messages are uninterpreted sequence of non-NUL\r
+   bytes.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>Although we encourage that the commit log messages are encoded\r
+in UTF-8, both the core and git Porcelain are designed not to\r
+force UTF-8 on projects.  If all participants of a particular\r
+project find it more convenient to use legacy encodings, git\r
+does not forbid it.  However, there are a few things to keep in\r
+mind.</p>\r
+<ol>\r
+<li>\r
+<p>\r
+<tt>git-commit-tree</tt> (hence, <tt>git-commit</tt> which uses it) issues\r
+  an warning if the commit log message given to it does not look\r
+  like a valid UTF-8 string, unless you explicitly say your\r
+  project uses a legacy encoding.  The way to say this is to\r
+  have core.commitencoding in <tt>.git/config</tt> file, like this:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[core]\r
+        commitencoding = ISO-8859-1</tt></pre>\r
+</div></div>\r
+<p>Commit objects created with the above setting record the value\r
+of <tt>core.commitencoding</tt> in its <tt>encoding</tt> header.  This is to\r
+help other people who look at them later.  Lack of this header\r
+implies that the commit log message is encoded in UTF-8.</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>git-log</tt>, <tt>git-show</tt> and friends looks at the <tt>encoding</tt>\r
+  header of a commit object, and tries to re-code the log\r
+  message into UTF-8 unless otherwise specified.  You can\r
+  specify the desired output encoding with\r
+  <tt>core.logoutputencoding</tt> in <tt>.git/config</tt> file, like this:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[core]\r
+        logoutputencoding = ISO-8859-1</tt></pre>\r
+</div></div>\r
+<p>If you do not have this configuration variable, the value of\r
+<tt>core.commitencoding</tt> is used instead.</p>\r
+</li>\r
+</ol>\r
+<p>Note that we deliberately chose not to re-code the commit log\r
+message when a commit is made to force UTF-8 at the commit\r
+object level, because re-coding to UTF-8 is not necessarily a\r
+reversible operation.</p>\r
+</div>\r
 <h2>Author</h2>\r
 <div class="sectionbody">\r
 <p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt;</p>\r
@@ -506,7 +595,7 @@ git log -r --name-status release..test
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 23-Nov-2006 02:47:21 UTC\r
+Last updated 31-Dec-2006 01:19:04 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-log.txt b/git-log.txt
index 79643ac928b05b4a97a09a5adfb67b1b4a2b832c..e9f746bbd4cebde9d8f5b90dd8fea6a2a610b140 100644 (file)
--- a/git-log.txt
+++ b/git-log.txt
@@ -31,7 +31,9 @@ include::pretty-formats.txt[]
        Limits the number of commits to show.
 
 <since>..<until>::
-       Show only commits between the named two commits.
+       Show only commits between the named two commits.  When
+       either <since> or <until> is omitted, it defaults to
+       `HEAD`, i.e. the tip of the current branch.
 
 -p::
        Show the change the commit introduces in a patch form.
@@ -63,6 +65,12 @@ git log -r --name-status release..test::
        in the "release" branch, along with the list of paths
        each commit modifies.
 
+Discussion
+----------
+
+include::i18n.txt[]
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>

diff --git a/git-rev-list.html b/git-rev-list.html
index 41ccd2cde889efdb221b1cc6dc51d2db60756e03..ecf560fe5e62c2b268cc37c116114356baf55e66 100644 (file)
--- a/git-rev-list.html
+++ b/git-rev-list.html
@@ -285,6 +285,7 @@ git-rev-list(1) Manual Page
              [ --stdin ]\r
              [ --topo-order ]\r
              [ --parents ]\r
+             [ --encoding[=<encoding>] ]\r
              [ --(author|committer|grep)=<pattern> ]\r
              [ [--objects | --objects-edge] [ --unpacked ] ]\r
              [ --pretty | --header ]\r
@@ -466,6 +467,18 @@ simplification into account.</p>
 </ul>\r
 </dd>\r
 <dt>\r
+--encoding[=&lt;encoding&gt;]\r
+</dt>\r
+<dd>\r
+<p>\r
+        The commit objects record the encoding used for the log message\r
+        in their encoding header; this option can be used to tell the\r
+        command to re-code the commit log message in the encoding\r
+        preferred by the user.  For non plumbing commands this\r
+        defaults to UTF-8.\r
+</p>\r
+</dd>\r
+<dt>\r
 --relative-date\r
 </dt>\r
 <dd>\r
@@ -774,7 +787,7 @@ and the git-list &lt;git@vger.kernel.org&gt;.</p>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 25-Dec-2006 11:36:06 UTC\r
+Last updated 31-Dec-2006 01:19:04 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-rev-list.txt b/git-rev-list.txt
index 9e0dcf8d3fef2495da4940ce662a46cc8a2bf621..86c94e7dfd257f5a7eff5c9d5aa4540a41128864 100644 (file)
--- a/git-rev-list.txt
+++ b/git-rev-list.txt
@@ -21,6 +21,7 @@ SYNOPSIS
             [ \--stdin ]
             [ \--topo-order ]
             [ \--parents ]
+            [ \--encoding[=<encoding>] ]
             [ \--(author|committer|grep)=<pattern> ]
             [ [\--objects | \--objects-edge] [ \--unpacked ] ]
             [ \--pretty | \--header ]

diff --git a/git-show.html b/git-show.html
index d02b8a7b4472f595b66c2ddcfea89bcb7ef3a107..530bf55298a822a495af17e2a95b0efca0ca9bb8 100644 (file)
--- a/git-show.html
+++ b/git-show.html
@@ -290,11 +290,11 @@ with --name-only).</p>
 <div class="sectionbody">\r
 <dl>\r
 <dt>\r
-&lt;commitid&gt;\r
+&lt;object&gt;\r
 </dt>\r
 <dd>\r
 <p>\r
-        ID of the commit to show.\r
+        The name of the object to show.\r
 </p>\r
 </dd>\r
 <dt>\r
@@ -427,6 +427,18 @@ simplification into account.</p>
 </li>\r
 </ul>\r
 </dd>\r
+<dt>\r
+--encoding[=&lt;encoding&gt;]\r
+</dt>\r
+<dd>\r
+<p>\r
+        The commit objects record the encoding used for the log message\r
+        in their encoding header; this option can be used to tell the\r
+        command to re-code the commit log message in the encoding\r
+        preferred by the user.  For non plumbing commands this\r
+        defaults to UTF-8.\r
+</p>\r
+</dd>\r
 </dl>\r
 </div>\r
 <h2>EXAMPLES</h2>\r
@@ -437,7 +449,8 @@ git show v1.0.0
 </dt>\r
 <dd>\r
 <p>\r
-        Shows the tag <tt>v1.0.0</tt>.\r
+        Shows the tag <tt>v1.0.0</tt>, along with the object the tags\r
+        points at.\r
 </p>\r
 </dd>\r
 <dt>\r
@@ -457,10 +470,86 @@ git show v1.0.0
         Concatenates the contents of said Makefiles in the head\r
         of the branch <tt>master</tt>.</p>\r
 </div>\r
+<h2>Discussion</h2>\r
+<div class="sectionbody">\r
+<p>At the core level, git is character encoding agnostic.</p>\r
+<ul>\r
+<li>\r
+<p>\r
+The pathnames recorded in the index and in the tree objects\r
+   are treated as uninterpreted sequences of non-NUL bytes.\r
+   What readdir(2) returns are what are recorded and compared\r
+   with the data git keeps track of, which in turn are expected\r
+   to be what lstat(2) and creat(2) accepts.  There is no such\r
+   thing as pathname encoding translation.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The contents of the blob objects are uninterpreted sequence\r
+   of bytes.  There is no encoding translation at the core\r
+   level.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The commit log messages are uninterpreted sequence of non-NUL\r
+   bytes.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>Although we encourage that the commit log messages are encoded\r
+in UTF-8, both the core and git Porcelain are designed not to\r
+force UTF-8 on projects.  If all participants of a particular\r
+project find it more convenient to use legacy encodings, git\r
+does not forbid it.  However, there are a few things to keep in\r
+mind.</p>\r
+<ol>\r
+<li>\r
+<p>\r
+<tt>git-commit-tree</tt> (hence, <tt>git-commit</tt> which uses it) issues\r
+  an warning if the commit log message given to it does not look\r
+  like a valid UTF-8 string, unless you explicitly say your\r
+  project uses a legacy encoding.  The way to say this is to\r
+  have core.commitencoding in <tt>.git/config</tt> file, like this:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[core]\r
+        commitencoding = ISO-8859-1</tt></pre>\r
+</div></div>\r
+<p>Commit objects created with the above setting record the value\r
+of <tt>core.commitencoding</tt> in its <tt>encoding</tt> header.  This is to\r
+help other people who look at them later.  Lack of this header\r
+implies that the commit log message is encoded in UTF-8.</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>git-log</tt>, <tt>git-show</tt> and friends looks at the <tt>encoding</tt>\r
+  header of a commit object, and tries to re-code the log\r
+  message into UTF-8 unless otherwise specified.  You can\r
+  specify the desired output encoding with\r
+  <tt>core.logoutputencoding</tt> in <tt>.git/config</tt> file, like this:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>[core]\r
+        logoutputencoding = ISO-8859-1</tt></pre>\r
+</div></div>\r
+<p>If you do not have this configuration variable, the value of\r
+<tt>core.commitencoding</tt> is used instead.</p>\r
+</li>\r
+</ol>\r
+<p>Note that we deliberately chose not to re-code the commit log\r
+message when a commit is made to force UTF-8 at the commit\r
+object level, because re-coding to UTF-8 is not necessarily a\r
+reversible operation.</p>\r
+</div>\r
 <h2>Author</h2>\r
 <div class="sectionbody">\r
 <p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt; and\r
-Junio C Hamano &lt;junkio@cox.net&gt;</p>\r
+Junio C Hamano &lt;junkio@cox.net&gt;.  Significantly enhanced by\r
+Johannes Schindelin &lt;Johannes.Schindelin@gmx.de&gt;.</p>\r
 </div>\r
 <h2>Documentation</h2>\r
 <div class="sectionbody">\r
@@ -473,7 +562,7 @@ Junio C Hamano &lt;junkio@cox.net&gt;</p>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 16-Dec-2006 07:43:53 UTC\r
+Last updated 31-Dec-2006 01:19:05 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-show.txt b/git-show.txt
index 98dea6125da78fa74800925b57dad2f002b1d6f6..c210b9af6bb4ce09d061e24715b07cd64887d54c 100644 (file)
--- a/git-show.txt
+++ b/git-show.txt
@@ -30,8 +30,8 @@ This manual page describes only the most frequently used options.
 
 OPTIONS
 -------
-<commitid>::
-       ID of the commit to show.
+<object>::
+       The name of the object to show.
 
 include::pretty-formats.txt[]
 
@@ -40,7 +40,8 @@ EXAMPLES
 --------
 
 git show v1.0.0::
-       Shows the tag `v1.0.0`.
+       Shows the tag `v1.0.0`, along with the object the tags
+       points at.
 
 git show v1.0.0^{tree}::
        Shows the tree pointed to by the tag `v1.0.0`.
@@ -54,10 +55,16 @@ git show master:Makefile master:t/Makefile
        Concatenates the contents of said Makefiles in the head
        of the branch `master`.
 
+Discussion
+----------
+
+include::i18n.txt[]
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org> and
-Junio C Hamano <junkio@cox.net>
+Junio C Hamano <junkio@cox.net>.  Significantly enhanced by
+Johannes Schindelin <Johannes.Schindelin@gmx.de>.
 
 
 Documentation

diff --git a/i18n.txt b/i18n.txt
new file mode 100644 (file)
index 0000000..b4cbb38
--- /dev/null
+++ b/i18n.txt
@@ -0,0 +1,57 @@
+At the core level, git is character encoding agnostic.
+
+ - The pathnames recorded in the index and in the tree objects
+   are treated as uninterpreted sequences of non-NUL bytes.
+   What readdir(2) returns are what are recorded and compared
+   with the data git keeps track of, which in turn are expected
+   to be what lstat(2) and creat(2) accepts.  There is no such
+   thing as pathname encoding translation.
+
+ - The contents of the blob objects are uninterpreted sequence
+   of bytes.  There is no encoding translation at the core
+   level.
+
+ - The commit log messages are uninterpreted sequence of non-NUL
+   bytes.
+
+Although we encourage that the commit log messages are encoded
+in UTF-8, both the core and git Porcelain are designed not to
+force UTF-8 on projects.  If all participants of a particular
+project find it more convenient to use legacy encodings, git
+does not forbid it.  However, there are a few things to keep in
+mind.
+
+. `git-commit-tree` (hence, `git-commit` which uses it) issues
+  an warning if the commit log message given to it does not look
+  like a valid UTF-8 string, unless you explicitly say your
+  project uses a legacy encoding.  The way to say this is to
+  have core.commitencoding in `.git/config` file, like this:
++
+------------
+[core]
+       commitencoding = ISO-8859-1
+------------
++
+Commit objects created with the above setting record the value
+of `core.commitencoding` in its `encoding` header.  This is to
+help other people who look at them later.  Lack of this header
+implies that the commit log message is encoded in UTF-8.
+
+. `git-log`, `git-show` and friends looks at the `encoding`
+  header of a commit object, and tries to re-code the log
+  message into UTF-8 unless otherwise specified.  You can
+  specify the desired output encoding with
+  `core.logoutputencoding` in `.git/config` file, like this:
++
+------------
+[core]
+       logoutputencoding = ISO-8859-1
+------------
++
+If you do not have this configuration variable, the value of
+`core.commitencoding` is used instead.
+
+Note that we deliberately chose not to re-code the commit log
+message when a commit is made to force UTF-8 at the commit
+object level, because re-coding to UTF-8 is not necessarily a
+reversible operation.

diff --git a/pretty-formats.txt b/pretty-formats.txt
index 996f6289031a4535a29579f3111998856eb31bfd..fb0b0b95829e0fc1aa98019554ce12e9b45d1f63 100644 (file)
--- a/pretty-formats.txt
+++ b/pretty-formats.txt
@@ -76,3 +76,10 @@ displayed in full, regardless of whether --abbrev or
 --no-abbrev are used, and 'parents' information show the
 true parent commits, without taking grafts nor history
 simplification into account.
+
+--encoding[=<encoding>]::
+       The commit objects record the encoding used for the log message
+       in their encoding header; this option can be used to tell the
+       command to re-code the commit log message in the encoding
+       preferred by the user.  For non plumbing commands this
+       defaults to UTF-8.