---
name: "bib2gls"
section: "1"
platform: "linux"
package: "texlive-doc"
version: "2026.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/bib2gls"
---

# bib2gls(1)

## SYNOPSIS

**bib2gls** \[*option*\]+ *auxfile*

## DESCRIPTION

**bib2gls** is designed to work with the **glossaries-extra** LaTeX package. (The **record** package option is required.) The application performs two functions in one: (1) selects entries from .bib files according to information found in the *auxfile* (similar to **bibtex**); (2) hierarchically sorts entries and collates location lists (similar to **makeindex** and **xindy**). The .aux extension may be omitted from *auxfile*.

The *auxfile* (and corresponding .log file) should either be in the  current directory or in the directory specified by **--dir**. Bib files can  either be relative to the directory the *auxfile* is in or in a location that can be found by kpsewhich.

## OPTIONS

- **--aux-input-action** *setting*

  Determines what to do when **bib2gls** encounters `"\@input"` in the *aux* file. The *setting* may be one of:

  - **follow**

    Follow the reference (that is, input the file as usual).

  - **skip-after-bibglsaux** (or **skip after bibglsaux**)

    Follow the reference for each `"\@input"` encountered until  `"\@bibgls@input"` is encountered, after which skip all remaining instances of `"\@input"` (default).

  - **skip**

    Skip all instances of `"\@input"` (but not `"\@bibgls@input"` which is always followed).

  The `"\@bibgls@input"` command will be in the *aux* file if the package option `"bibglsaux"` has been used.

- **--break-space**

  Interpret `"~"` (tilde) character and `"\nobreakspace"` as a normal space.

- **--cite-as-record**

  Treat `"\citation"` as an ignored record.

- **--collapse-same-location-range**

  Collapse an explicit range that has a duplicate start and end location into a normal record (default).

- **--custom-packages** *list*

  Instruct the TeX parser library to attempt to parse the  packages listed in *list*. This is intended for simple custom packages that don't contain complex code.

- **--datatool-sort-markers**

  The interpreter will use the *datatool-base.sty* marker commands to match their  localised definitions within `"\DTLsortwordlist"` (*datatool* v3.0+). You will need a sort method that doesn't ignore the control characters used by those commands.

- **--date-in-header** (or **-D**)

  The header comment at the start of the *.glstex* file will include the file modification date.

- **--debug** \[*n*\]

  Switch on the debug mode at the given setting *n*, which should be a non-negative integer. If *n* is **0** then the debug mode is switched off. If omitted, *n* is set to 1, which corresponds to **--debug-mode** **io**. Any positive number will enable all of **bib2gls**'s debugging messages. The amount of TeX Parser Library debugging messages depends on bitwise operation of *n*.

- **--debug-mode** *setting*

  May be used instead of **--debug** where the level number is difficult to remember. The *setting* may be a comma-separated list of any of the keywords:

  - **all**

    Highest level (likely to result in a large transcript file). Equivalent to switching on all settings.

  - **catcode**

    TeX Parser category code changes.

  - **cs**

    TeX Parser command definitions.

  - **decl**

    TeX Parser declarations.

  - **expansion**

    TeX Parser expansions (may result in a large transcript file).

  - **expansion-list**

    TeX Parser stack expansions (may result in a large transcript file).

  - **expansion-once**

    TeX Parser one-level expansions.

  - **expansion-once-list**

    TeX Parser one-level list expansions.

  - **io**

    TeX Parser I/O operations (open, close and fetch token).

  - **popped**

    TeX Parser stack popping.

  - **process**

    TeX Parser macro process (may result in a large transcript file).

  - **process-generic-cs**

    TeX Parser generic command process.

  - **process-stack**

    TeX Parser stack process (may result in a large transcript file).

  - **process-stack-list**

    TeX Parser detailed stack process (may result in a large transcript file).

  - **read**

    TeX Parser codepoint read from file (likely to result in a large transcript file).

  - **sty-data**

    TeX Parser data (typically relates to internal objects that don't have an analogous TeX macro). This includes data gathered from the aux file.

  For example: `"bib2gls --debug-mode io,catcode,sty-data mydoc"`

- **--default-encoding** *name*

  Set the default character encoding for input and output files. If omitted, the JVM default encoding is assumed.

- **--dir** *directory* (or **-d** \<directory\>)

  Files are relative to *directory*. (This doesn't change the current working directory.)

- **--expand-fields**

  Don't write `"\glsnoexpandfields"` to the *.glstex* file.

- **--force-cross-resource-refs** or **-x**

  Force cross-resource referencing mode on.

- **--group** or **-g**

  Add **group** field to entries.

- **--help** or **-h**

  Display help message and exit.

- **--ignore-packages** *list* (or **-k** *list*)

  Don't parse the log file for the packages listed in *list*. Note that **--packages** overrides this option, so if the same package is listed in both **--ignore-packages** and **--packages** then the interpreter will check if it's supported. This option has a cumulative action. Only known packages may be included in *list*.

- **--interpret**

  Use the TeX Parser Library to interpret known (La)TeX commands (default).

- **--list-known-packages**

  Lists all the packages that have are known to the TeX parser library and then exits (with exit code 0). Any of the listed packages may be used in **--packages** or **--ignore-packages**.

- **--locale** *lang* (or **-l** *lang*)

  Use language resource file for *lang* (which should be an IETF locale tag).

- **--log-encoding** *name*

  Set the character encoding for the *log* files (which may not be the same as the encoding for the document LaTeX files).

- **--log-file** *file* (or **-t** \<file\>)

  Set the transcript file.

- **--merge-nameref-on** *rule*

  Rule for merging locations created with the **record=nameref** package option (requires *glossaries-extra.sty* version 1.37+). The *rule* may be one of: **hcounter**, **href**, **title** or **location**.

- **--merge-wrglossary-records**

  Merge an entry's **wrglossary** records for the same page locations. (For use with the **indexcounter** package option.)

- **--mfirstuc-math-protection**

  Switch on the auto-insertion of an empty group for math-shift (`"$"`).

  If *mfirstuc* v2.08+, *glossaries* v4.50+ and *glossaries-extra* v1.49+  are detected, the default will be **--no-mfirstuc-math-protection** as there should no longer be any need for this protection.

- **--mfirstuc-protection** *fields*\|**all** (or **-u** *fields*\|**all**)

  Insert an empty group if fields start with certain problematic commands to protect against case-changing commands like `"\Gls"`.

  The default is to do this for all fields.  To do this for only a subset of fields, set *fields* to a comma-separated list of fields (e.g. **name,short,long**).  The keyword **all** indicates all fields.

  If *mfirstuc* v2.08+, *glossaries* v4.50+ and *glossaries-extra* v1.49+  are detected, the default will be **--no-mfirstuc-protection** as there should no longer be any need for this protection.

- **--nested-link-check** *list*\|**none**

  Check each field listed in *list* for potentially problematic nested link text. (Default list: name, text, plural, first, firstplural, short, shortplural, long, longplural, symbol).

  If **none**, disable check.

- **--no-break-space**

  Interpret `"~"` (tilde) and `"\nobreakspace"` as a non-breaking space (default).

- **--no-cite-as-record**

  Don't check for instances of `"\citation"` in the *.aux* file (default).

- **--no-collapse-same-location-range**

  Don't collapse an explicit range that has a duplicate start and end location into a normal record.

- **--no-datatool-sort-markers**

  The interpreter will use the normal definition of the *datatool-base.sty* sort marker commands.

- **--no-date-in-header**

  The header comment at the start of the *.glstex* file will not include the file modification date (default).

- **--no-debug** (or **--nodebug**)

  Switch off debug mode. (Equivalent to **--debug** **0**)

- **--no-expand-fields**

  Write `"\glsnoexpandfields"` to the *.glstex* file (default).

- **--no-force-cross-resource-refs**

  Don't force cross-resource referencing mode on (default).

- **--no-group**

  Don't add **group** field to entries (default).

- **--no-interpret**

  Don't try interpreting (La)TeX commands. The TeX Parser Library will still be used to parse the *aux* and *bib* files.

- **--no-merge-wrglossary-records**

  Don't merge an entry's **wrglossary** records.

- **--no-mfirstuc-math-protection**

  Switch off the auto-insertion of an empty group for math-shift (`"$"`).

- **--no-mfirstuc-protection**

  Switch off the auto-insertion of an empty group for all fields.

- **--no-nested-link-check**

  Don't check for potentially problematic nested link text. (Equivalent to **--nested-link-check** **none**)

- **--no-obey-aux-catcode**

  Ignore category code changing commands encountered in the aux file.

- **--no-provide-glossaries**

  Don't write `"\provideignoredglossary*"` to the *.glstex* file to provide unknown glossaries except in documented situations (**master**, **secondary** and **trigger-type** resource options). This setting is the default.

- **--no-record-count**

  Don't add record count field to entries (default). This option automatically implements **--no-record-count-unit**.

- **--no-record-count-unit**

  Don't add unit record count field to entries (default).

- **--no-replace-quotes**

  Don't replace quote characters (default).

- **--no-retain-formats**

  Normal location merging rules apply (default).

- **--no-shift-zero-sections**

  Don't check for locations ending with ".0" (default).

- **--no-support-unicode-script**

  Text superscript (`"\textsuperscript"`) or subscripts (`"\textsubscript"`) won't be converted to Unicode superscript/subscript characters. For example, `"\textsuperscript{2}"` will be converted to `"<sup>2</sup>"` and the markup will be stripped leaving just the character 2.

- **--no-trim-fields**

  Don't trim leading and trailing spaces from fields (default). This option cancels **--trim-only-fields** and **--trim-fields**.

- **--no-verbose** (or **--noverbose**)

  Switch off verbose mode. (Some messages will still be written to STDOUT.)

- **--no-warn-non-bib-fields**

  Don't warn if internal non-bib fields are found in the *.bib* file. The use of these internal fields can cause unexpected results, so only use this option if you have taken appropriate precautions.

- **--no-warn-unknown-entry-types**

  Don't warn if any unknown entry types are found in the *.bib* file.

- **--obey-aux-catcode**

  Obey known category code changing commands encountered in the aux file.

- **--packages** *list* (or **-p** *list*)

  Instruct the TeX parser library to pretend the packages listed  in *list* have been used by the document. Note that there's only a limited number of packages supported by the TeX parser library. This option has a cumulative action so **--packages wasysym,pifont** is the same as **--packages wasysym --packages pifont**.

  You can find out the list of supported packages with **--list-known-packages**.

- **--provide-glossaries**

  Write `"\provideignoredglossary*"` to the *.glstex* file to provide unknown glossaries.

- **--quiet** (or **-q**)

  Only display error messages. All other messages are just written to the transcript file.

- **--record-count** or **-c**

  Add record count fields to entries.

- **--record-count-rule** *rule* or **-r** *rule*

  Sets the rule used by **--record-count** and **--record-count-unit**. This option automatically implements **--record-count**.

  The *rule* may be: `"all"` or `"a"` (count all records),  `"non-ignored"` or `"n"` (count all non-ignored records),  `"f/"`*regex*`"/"` (only count records where the format  matches the regular expression *regex*), `"c/"`*regex*`"/"` (only count records where the counter name  matches the regular expression *regex*), or `"f/"`*regex1*`"/c/"`*regex2*`"/"`*op* (only count records where the format  matches the regular expression *regex1* and/or the counter name  matches the regular expression *regex2*). The *op* part is optional. If present it may be one of: `"and"` (format AND counter must match), `"or"` (format OR counter must match). If *op* is omitted, AND is assumed.

- **--record-count-unit** or **-n**

  Add unit record count fields to entries. This option automatically implements **--record-count**.

- **--replace-quotes**

  Replace single and double quote characters (`"'"` and `"""`) with  `"\bibglsaposchar"` and `"\bibglsdoublequotechar"` in field values and group information written to the *.glstex* file.

- **--retain-formats** *list*

  Indicates which location formats should always be retained even if it causes a partial duplicate. Only exact duplicates will be merged.

- **--shift-zero-sections**

  Shift up section locations ending with ".0" (for sections deeper than chapter). This action is applied recursively.

  For example, if a record has counter `"subsection"` and location `2.0.0` then this will first be replaced with counter `"section"` and location `2.0` but since this still has a section location ending with ".0" the function will be applied again and the counter will be changed to `"chapter"` and the location will be changed to `2` (so the location subsection 2.0.0 ends up as chapter 2). The log file (and verbose mode) will have a line for each change in the recursion.

- **--shortcuts** *option*

  Check for the shortcut commands when searching for dependencies. Permitted values of *option*: **acronyms** (or **acro**), **ac**, **abbreviations** (or **abbr**), **all** (or **true**), **none** (or **false**). This overrides the setting given in *auxfile*.

- **--map-format** *key***:***value*\[**,***key***:***value*\]\* (or **-m** *key***:***value*\[**,***key***:***value*\]\*)

  Set location format mappings.

- **--silent**

  Only display error messages. All other messages are just written to the transcript file. (Synonym of **--quiet**.)

- **--support-unicode-script**

  Text superscript (`"\textsuperscript"`) or subscripts (`"\textsubscript"`) will use Unicode superscript/subscript characters if available. For example, `"\textsuperscript{2}"` will be converted to U+00B2 (superscript two).

- **--tex-encoding** *name*

  Set the character encoding for the *glstex* files. This overrides the setting given in *auxfile*.

- **--trim-except-fields** *list*

  Trim leading and trailing spaces from all fields except those listed. This option is cumulative but is cancelled by **--trim-fields** and **--no-trim-fields**. This option may not be used with **--trim-only-fields**.

- **--trim-fields**

  Trim leading and trailing spaces from all fields. This option cancels **--trim-only-fields** and **--no-trim-fields**.

- **--trim-only-fields** *list*

  Trim leading and trailing spaces from only the listed fields. This option is cumulative but is cancelled by **--trim-fields** and **--no-trim-fields**. This option may not be used with **--trim-except-fields**.

- **--verbose**

  Switch on verbose mode.

- **--version** or **-v**

  Display version information and exit.

- **--warn-non-bib-fields**

  Warn if internal non-bib fields are found in the *.bib* file.

- **--warn-unknown-entry-types**

  Warn if any unknown entry types are found in the *.bib* file.

## REQUIRES

Java 8 or later and a TeX distribution.

## LICENSE

License GPLv3+: GNU GPL version 3 or later \<http://gnu.org/licenses/gpl.html\> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

## RECOMMENDED READING

The bib2gls manual:

```
        texdoc bib2gls
```

The glossaries-extra manual:

```
        texdoc glossaries-extra
```

The glossaries manual:

```
        texdoc glossaries
```

## AUTHOR

Nicola L. C. Talbot, \<https://www.dickimaw-books.com/\>