Update

This command allows you to update the document metadata stored in the info.yaml file. With it, you can either change individual values manually or update a document with information automatically retrieved from a variety of sources.

When using it to add information, Papis formatting patterns and Python expressions can be used. See below examples for more information. The command also tries to sanitise filenames so that they don’t contain any problematic characters.

Normally, papis update will abort on encountering an error. If you want to skip errors and apply as many changes as possible, use the --batch flag.

Examples

  • Search among papers with the tag “classics” and update the author to “Einstein, Albert”:

    papis update --set author "Einstein, Albert" "tags:classics"

    This will open the picker containing all documents that match the query from where you can select the document you want to update.

  • Update the journal to “Mass and Energy” for all documents with the journal “Energy and Mass”:

    papis update --all --set journal "Mass and Energy" "journal:'Energy and Mass'"

    The --all flag means that the tag is applied to all documents that match the query, rather than allowing you to pick one individual document to update.

  • Update a document automatically and interactively (searching by DOI in Crossref or in other sources…):

    papis update --auto "author:dyson"

  • Update your library from a BibTeX file, where many entries may be listed:

    papis update --from bibtex libraryfile.bib

    Papis will try to look for documents in your library that match these entries and will ask you for each entry whether you want to update it.

  • Add the “, Albert” to the author string of a documents matching ‘Einstein’:

    papis update --set author "{doc[author]}, Albert" Einstein

    The papis update command tries to format input strings using the configured formatter. Here, it is used to get the existing author “Albert” and then add the string “, Einstein” to end up with “Einstein, Albert”

  • The above can also be achieved with the --append option:

    papis update --append author ", Albert" Einstein

    This appends “, Albert” to the existing author string.

  • You can also append an item to a list:

    papis update --append tags physics

    This adds the tag ‘physics’ to the existing list of tags. If the list doesn’t yet exist, it will be created. All duplicate items will be removed from the list.

    As you might have guessed, the --append flag needs to know the type of the key it is appending to. It does this by looking at the doctor-key-type-keys (and doctor-key-type-keys-extend) configuration options. If the key you are appending to is not in that list, the command will fail.

  • To remove an item from a list, use --remove:

    papis update --remove tags physics

    If the tag “physics” is in the list of tags, this command removes it.

  • To remove a key-value pair entirely, use --drop:

    papis update --drop tags

    This removes all tags.

  • There is also a convenience option --rename if you want to rename a list item. It’s equivalent to doing --remove and --append sequentially:

    papis update --rename tags physics philosophy

    This renames the tag ‘physics’ to ‘philosophy’. Note that this option being a combination of --remove and --append, it will append the desired values even if the value to be removed didn’t exist. Thus, the above command will add the tag “philosophy” even if the tag “physics” didn’t exist before the operation.

  • As an advanced feature, papis update also supports the parsing of python expressions (such as lists or dictionaries). This can be used as follows:

    papis update --set author_list "[{'family': 'Einstein', 'given': 'Albert'}]"

    Because the above string is a valid python expression, author_list is updated to a set that contains a dictionary.

Command-line interface

Update document metadata.

Usage

papis update [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--git, --no-git

Commit changes to git.

--doc-folder <doc_folder>

Document folder on which to apply action.

-a, --all

Apply action to all matching documents.

--sort <FIELD>

Sort documents with respect to the FIELD.

--reverse

Reverse sort order.

--auto

Try to gather metadata from different sources.

--auto-doctor, --no-auto-doctor

Apply automatic doctor fixes to newly added documents.

--from <from_importer>

Add document from a specific importer.

--list-importers

List all supported importers.

-s, --set <to_set>

Set the key to the given value.

-d, --drop <to_drop>

Drop a key from the document.

-p, --append <to_append>

Append a value to a document key.

-r, --remove <to_remove>

Remove an item from a list.

-n, --rename <to_rename>

Rename an item in a list.

-b, --batch

Do not prompt, and skip documents containing errors.

Arguments

QUERY

Optional argument