export-subst uses git log's custom formatter

git archive uses git log's `pretty=format:` processor directly, and
strips the surrounding `$Format:` and `$` markup from the output.

Author: jthill

book/08-customizing-git/sections/attributes.asc

@@ -279,26 +279,49 @@ Now, when you run git archive to create a tarball of your project, that director
 
 ===== `export-subst`
 
-Another thing you can do for your archives is some simple keyword substitution.
-Git lets you put the string `$Format:$` in any file with any of the `--pretty=format` formatting shortcodes, many of which you saw in Chapter 2.
-For instance, if you want to include a file named `LAST_COMMIT` in your project, and the last commit date was automatically injected into it when `git archive` ran, you can set up the file like this:
+When exporting files for deployment you can apply `git log`'s formatting and keyword-expansion processing to selected portions of files marked with the
+`export-subst` attribute.
+
+For instance, if you want to include a file named `LAST_COMMIT` in your project, and have metadata about the last commit automatically injected into it when `git archive` runs, you can for example set up the file like this:
 
 [source,console]
 ----
-$ echo 'Last commit date: $Format:%cd$' > LAST_COMMIT
+$ echo 'Last commit date: $Format:%cd by %aN$' > LAST_COMMIT
 $ echo "LAST_COMMIT export-subst" >> .gitattributes
 $ git add LAST_COMMIT .gitattributes
 $ git commit -am 'adding LAST_COMMIT file for archives'
 ----
 
-When you run `git archive`, the contents of that file when people open the archive file will look like this:
+When you run `git archive`, the contents of the archived file will look like this:
 
 [source,console]
 ----
-$ cat LAST_COMMIT
-Last commit date: $Format:Tue Apr 21 08:38:48 2009 -0700$
+$ git archive HEAD | tar xCf ../deployment-testing -
+$ cat ../deployment-testing/LAST_COMMIT
+Last commit date: Tue Apr 21 08:38:48 2009 -0700 by Scott Chacon
+----
+
+The substitutions can include for example the commit message and any git notes, and git log can do simple word wrapping:
+
+[source.console]
+----
+$ echo '$Format:Last commit: %h by %aN at %cd%n%+w(76,6,9)%B$' > LAST_COMMIT
+$ git commit -am 'export-subst uses git log's custom formatter
+
+git archive uses git log's `pretty=format:` processor
+directly, and strips the surrounding `$Format:` and `$`
+markup from the output.
+'
+$ git archive @ | tar xfO - LAST_COMMIT
+Last commit: 312ccc8 by Jim Hill at Fri May 8 09:14:04 2015 -0700
+       export-subst uses git log's custom formatter
+
+         git archive uses git log's `pretty=format:` processor directly, and 
+         strips the surrounding `$Format:` and `$` markup from the output.
 ----
 
+The resulting archive is suitable for deployment work, but like any exported archive it isn't suitable for further development work.
+
 ==== Merge Strategies
 
 (((merging, strategies)))