Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Files and Formats

The export-ignore and export-subst attributes

Reference for export-ignore and export-subst in .gitattributes: leave files out of git archive output and expand $Format:...$ placeholders with commit data.

Two attributes shape the output of git archive, the command behind source tarballs and GitHub's "Download ZIP". export-ignore leaves matching paths out of the archive, which keeps tests, CI files and editor settings out of a release. export-subst expands $Format:...$ placeholders in the file's content with data from the commit being archived, so a released file can carry its own version string.

Both only affect git archive. A normal checkout or clone is unaffected.

Terminal
/tests       export-ignore
.github/     export-ignore
.gitattributes export-ignore
version.txt  export-subst

Try it

Bash Leave files out of an archive

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Stamp a commit into a file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
<pattern> export-ignore
<pattern> export-subst
Name Description
export-ignore Matching files and directories are not written by git archive. A directory pattern removes everything below it.
export-subst In matching files, $Format:<pretty-format>$ is replaced using the same placeholders as git log --pretty=format:, evaluated for the archived commit.
$Format:...$ Any placeholder works, such as %H (full hash), %h (short hash), %s (subject), %cs (commit date) or %D (ref names, useful for tags).
$Format:%(describe)$ Expands to git describe output (Git 2.32 and later), handy for version strings.

Edge cases: a $Format: with no closing $ is left as it is. There is no escape syntax, so a file that must contain a literal $Format:...$ should not be marked export-subst. Expansion changes the file length, so checksums of the archived file differ from the committed blob.

Usage notes

  • Attributes are read from the archived tree. Because git archive HEAD uses .gitattributes from that commit, add the attributes before tagging the release.
  • Use --worktree-attributes if you want the uncommitted .gitattributes to apply.
  • Escape percent signs in printf. The printf in the example writes %%H to produce %H; a plain editor does not need this.
  • export-ignore does not hide history. The files are still in the repository and in git clone; it is not a secrecy feature.
  • Ignore .gitattributes itself so the archive stays clean; the rules have already done their job.
  • Reproducible archives. git archive uses the commit time for file times, so identical commits give identical tarballs.
  • Not applied by git checkout. Placeholders in your working copy stay as typed.
  • Hosts. GitHub and GitLab source archives honor both attributes, since they run git archive.