WARNING

Autobib is alpha software.

• Things might be broken.
• All of your data might be deleted.
• The interface may change without warning in unexpected ways.

On the other hand, Autobib is currently usable, and you are welcome to try it out with these caveats in mind. Please report any issues in the issues page.

Autobib

Autobib is a command-line tool for managing bibliographic records. Unlike other bibliography management tools such as Zotero or JabRef, Autobib aims to be a lower-level tool for providing an interface between local records, remote records, and bibliographic records associated with a project.

Moreover, Autobib is designed with first-class support for BibTeX.

Installation

Currently, the best way to install Autobib is to have the rust toolchain installed on your device and run

cargo install autobib

Basic usage

In order to see all of the commands available to Autobib, run

autobib help
autobib help <subcommand>

Jump to:

• Getting records
• Sourcing from files
• Editing records
• Assigning aliases
• Creating local records
• Searching for records
• Shell completions

Getting records

At its most basic, Autobib converts identifiers into records. To obtain the data associated with the zbMath record Zbl 1337.28015, running

autobib get zbl:1337.28015

will return

@article{zbl:1337.28015,
  author = {Hochman, Michael},
  doi = {10.4007/annals.2014.180.2.7},
  journal = {Ann. Math. (2)},
  language = {English},
  pages = {773--822},
  title = {On self-similar sets with overlaps and inverse theorems for entropy},
  volume = {180},
  year = {2014},
  zbl = {1337.28015},
}

An identifier is a pair provider:sub_id. The current supported providers are:

• arxiv: An arXiv identifier, such as arxiv:1212.1873 or arxiv:math/9201254
• doi: A DOI identifier, such as doi:10.4007/annals.2014.180.2.7
• jfm: A special zbMath identifier mainly for old records, such as jfm:60.0017.02
• mr: A MathSciNet identifier, such as mr:3224722
• zbl: A zbMath external identifier of the form xxxx.xxxxx, such as zbl:1337.28015
• zbmath: A zbMath internal identifier of the form xxxxxxxx, such as zbmath:06346461

Sourcing from files

A more common scenario is that you have a file, say main.tex, with some contents:

% contents of file `main.tex`
\documentclass{article}
\begin{document}
We refer the reader to \cite{zbl:1337.28015,zbl:1409.11054}.
\end{document}

Then, for example, running

autobib source main.tex --out main.bib

will search through the document for valid citation keys and output the bibliography into the file main.bib.

Editing records

On the first run, Autobib retrieves the data directly from a remote provider. The data is stored locally in a SQLite database, which defaults to ~/.local/share/autobib/records.db, so that subsequent runs are substantially faster. You can view and update the internally stored record with

autobib edit zbl:1337.28015

If the record does not yet exist in your local record database, it will be retrieved before editing.

Assigning aliases

It is also possible to assign aliases to records, using the autobib alias sub-command. To create an alias for the record with identifier zbl:1337.28015, run

autobib alias add hochman-entropy zbl:1337.28015

Then running autobib get hochman-entropy returns

@article{hochman-entropy,
  author = {Hochman, Michael},
  doi = {10.4007/annals.2014.180.2.7},
  journal = {Ann. Math. (2)},
  language = {English},
  pages = {773--822},
  title = {On self-similar sets with overlaps and inverse theorems for entropy},
  volume = {180},
  year = {2014},
  zbl = {1337.28015},
}

The record is identical to the record zbl:1337.28015, except that the citation key is the name of the alias. In order to distinguish from usual identifiers, an alias cannot contain the : colon symbol.

Note that the characters {}(),=\#%" are not permitted in a BibTeX entry key. You can still create aliases using these characters: for instance, autobib alias add % zbl:1337.28015 works. However, attempting to retrieve the BibTeX entry associated with this alias will result in an error.

$ autobib get %
ERROR Invalid bibtex entry key: %
  Suggested fix: use an alias which does not contain disallowed characters: {}(),=\#%"

Run autobib help alias for more options for managing aliases.

Aliases can be used in most locations that the usual identifiers are used. For instance, you can run autobib edit hochman-entropy, to edit the corresponding record data. Note, however, that these edits will apply to the original underlying record.

Creating local records

Sometimes, it is necessary to create a local record which may not otherwise exist on a remote database. In order to do this, the command autobib local can be used to generate a special local: record, which only exists locally database. To modify the contents, use autobib edit:

autobib local my-entry
autobib edit local:my-entry

These two steps can be combined:

autobib local my-entry --edit

It is also possible to create the local record from a BibTeX file:

autobib local my-entry --from source.bib

Note that the BibTeX file should contain exactly one entry, or this command will fail.

Searching for records

In order to search for records which are saved on your local database, use the autobib find command. This will open a fuzzy picker for searching through various fields. Specify the fields that you would like with -f, followed by a comma-separated list of fields. For example,

autobib find -f author,title

will list all of your local records with the author and title fields available to search against.

Shell completions

Autobib supports shell completion of commands and options in shells like Bash and Zsh. See supported shells.

A shell completions script can be generated as follows:

autobib completions <shell>

Run this on interactive shell start-up and redirect the output to your preferred directory of completions scripts.

For example, in Zsh, add the following lines to ~/.zshrc:

if type autobib &> /dev/null
then
  autobib completions zsh > "$HOME/.local/share/zsh/site-functions/_autobib"
fi

and make sure ~/.local/share/zsh/site-functions (or another directory of your choice) is added to the FPATH environment variable.

In Bash, add the following lines to ~/.profile:

if type autobib &> /dev/null
then
  autobib completions bash > "$HOME/.local/share/bash-completion/completions/autobib"
fi

For this to take effect, remember to restart your shell or source the relevant file. Then you can try typing autobib f and pressing the tab key. You should see autobib find .

License

The source code of Autobib is distributed under the terms of the GNU Affero General Public License, version 3.

See LICENSE and COPYRIGHT for details.