.TH BIB-EXTRACT 1 "June 2026" "bibutils" "User Commands"
.SH NAME
bib-extract \- emit only the database entries cited in a document
.SH SYNOPSIS
.B bib-extract
.I file.aux
.RI [ db.bib ]
.SH DESCRIPTION
.B bib-extract
collects the citation keys recorded in
.I file.aux
and filters the bibtex database given as
.I db.bib
(or read on standard input), emitting only the cited entries, in
canonical form, on standard output.
.PP
Both classic bibtex
.RB ( \[rs]citation )
and biblatex/biber
.RB ( \[rs]abx@aux@cite )
aux files are understood.
A citation of
.B *
(as produced by
.BR \[rs]nocite{*} )
selects the entire database.
.B @string
and
.B @preamble
blocks always pass through.
.PP
roff/refer citation sources are planned but not yet supported.
.SH EXIT STATUS
0 on success (including no citations found), 1 if the aux file cannot
be read, 2 on usage error.
.SH ENVIRONMENT
.TP
.B BIBUTILS_LIB
Directory holding the shared awk library, overriding the default
search (lib/ next to the script, then /usr/local/share/bibutils).
.SH EXAMPLES
Produce a minimal database for submission alongside a paper:
.nf
bib-extract paper.aux master.bib > paper.bib
.fi
.SH SEE ALSO
.BR bib-ls (1),
.BR bib-util (1),
.BR bibtex (1)