.TH BIB-ADD 1 "June 2026" "bibutils" "User Commands"
.SH NAME
bib-add \- insert bibtex entries into a database file
.SH SYNOPSIS
.B bib-add
.RB [ \-f ]
.I db.bib
.SH DESCRIPTION
.B bib-add
reads one or more fully formatted bibtex entries on standard input and
appends them to the database file
.IR db.bib ,
creating it if necessary.
Entries are canonicalized on the way in: entry types and field names
are lowercased, values are brace-delimited with internal whitespace
collapsed, bare numbers are left bare, and macro references and
.B #
concatenations are preserved verbatim.
.PP
If an incoming entry's key already exists in the database, the entry is
rejected and the duplicate keys are reported on standard error, unless
.B \-f
is given.
Input with an empty key, or with the same key appearing twice, is
always rejected.
.SH SAFETY
The database is never modified in place.
The complete new version is built in a temporary file alongside the
original, verified by re-parsing it and checking that exactly the
expected entries are present, and only then written over the database
\(em with the previous contents first saved in
.IB db.bib .bak\fR.
If anything fails along the way, the original file is left untouched.
.PP
Concurrent invocations are serialized through a lock file,
.IB db.bib .lock\fR,
created atomically with the owner's pid inside.
A waiter retries for 30 seconds before giving up with an error;
a lock whose owning process has died is reaped automatically.
.SH OPTIONS
.TP
.B \-f
Replace existing entries that share a key with an incoming entry.
The replaced entries are spliced out by their exact source spans, so
comments and the formatting of every other entry are preserved
byte-for-byte.
.SH EXIT STATUS
0 on success, 1 if the input was rejected or the database could not
be safely rewritten, 2 on usage error.
.SH FILES
.TP
.IB db.bib .bak
The previous contents of the database, written before each
modification.
.TP
.IB db.bib .lock
Write lock held for the duration of an invocation; contains the
owner's pid.
.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
Add a fetched entry to a database:
.nf
bib-fetch paper.pdf | bib-add refs.bib
.fi
.SH SEE ALSO
.BR bib-gen (1),
.BR bib-key (1),
.BR bib-util (1)