Update

This command allows you to update the document metadata stored in the info.yaml file. With it, you can either set individual fields’ values manually or update a document with information automatically retrieved from a variety of sources. The command also renames files and notes on disk when needed.

Papis formatting patterns and Python expressions can be used. See below examples for more information. The command also sanitises filenames so that they don’t contain any problematic characters (see doc-paths-extra-chars).

By default, papis update will prompt you when it encounters an error. If you want to skip errors automatically and apply as many changes as possible, use the --batch flag.

This command is mostly meant to be used to apply sweeping changes across a large number of documents. If you just want to update a single document, papis edit might be more appropriate.

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 operation is applied to all documents that match the query, rather than opening the picker to select individual documents to update.

• Add “, 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”.

• Reset a field to its default value using:

  papis update --reset ref Einstein
  

  This will reset the value to the default value defined for the field. Here, the “ref” is set to ref-format. Other fields that can be reset are: “author” (gets updated from author_list and multiple-authors-format), “notes” (using notes-name), and “files” (using add-file-name). Other fields do not support this as they do not have any well-defined default.

• The --append option can be used to append to a string value:

  papis update --append author ", Albert" Einstein
  

  This appends “, Albert” to the existing author value. Note that it will be appended to the existing value only if it does not already end with that exact string (case-sensitive). This avoids appending duplicates by mistake, as in the case of lists (below).

• You can also append an item to a list:

  papis update --append tags physics 'author:einstein'
  

  This adds the tag “physics” to the existing list of tags. If the list doesn’t yet exist, it will be created. The new tag will only be appended to the list if the tag does not already exist (as an exact case-sensitive match).

  The --append flag needs to know the type of the field it is appending to. If the field exists in the document, then the value set in the document determines the type. If the field doesn’t exist in the document, the command looks at the list of types defined in the document-field-types (and document-field-types-extend) configuration option. If the type cannot be determined in either of these two ways, the command will fail.

• To remove an item from a list, use --remove. For example, to remove the “physics” tag from the list of document tags, use

  papis update --remove tags physics 'author:einstein'
  

• To remove a field entirely, use --drop. For example, to remove all tags from documents use

  papis update --drop tags 'author:einstein'
  

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

  papis update --rename tags physics philosophy
  

  This renames the tag “physics” to “philosophy”. Note that the new tag will not be added to the list if the original tag doesn’t exist.

• The --batch flag suppresses interactive prompts and skips any document for which an update operation has failed. This is useful when applying the same operation across many documents where some may not have the expected keys or values:

  papis update --all --batch --remove tags obsolete "tags:obsolete"
  

  Without --batch, if a document does not have “obsolete” in its tag list (or has no tags key at all), the command pauses and asks whether to continue. With --batch, an error is logged, the document is skipped and the command moves on to the next one.

  More specifically, --batch suppresses prompts in the following way:

  • If an operation on a field fails (e.g. trying to --remove a value that is not in the list, --append to a field of unknown type, or a type conversion error from --set), the next operation is tried automatically. The affected field retains its original pre-failed-operation value and the remaining fields for that document are still processed.

  • If a file rename fails (e.g. the file on disk is missing or cannot be moved), then the whole document is skipped. This generally signals some external failure, so the user should just try again.

  In all cases the command exits with a non-zero status (indicating a failure) if any document was skipped.

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

  papis update --auto "author:dyson"
  

• Update your document from a DOI using the importer functionality:

  papis update --from doi '10.1103/PhysRev.47.777' 'author:einstein'
  

  For a list of all supported importers use papis update --list-importers.

• When you update the files or notes fields, the corresponding files on disk are renamed to match the new value:

  papis update --set notes "my-new-notes.tex" Einstein
  

  This updates the info.yaml file and renames the notes file on disk from its current name to my-new-notes.tex. The same applies when updating files:

  papis update --rename files einstein-old.pdf einstein-new.pdf Einstein
  

  This renames the file einstein-old.pdf to einstein-new.pdf in the info.yaml file and on disk. If the rename fails (e.g. the file does not exist or there is a permissions error), the metadata is not updated and an error is reported.

  Note that the --reset option also triggers a rename when used with notes or files. It renames the files to the names derived from the configured notes-name and add-file-name formats respectively.

Advanced Examples

• 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 list that contains a dictionary.

• You can use --set to set a value in a list at a given position:

  papis update --set files 0:some-new-file.pdf Einstein
  

  This command will rename the first entry in the list of files. This special syntax for --set only works with fields that are known to be lists (as determined based on document-field-types and document-field-types-extend). If the field is not a list, then the value is treated as a string. This might be unexpected, so make sure you are using it for list fields only.

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

Automatically select importers and downloaders based on document metadata.

--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.

--reset <to_reset>

Reset fields to their default values.

-d, --drop <to_drop>

Drop a field from the document.

-p, --append <to_append>

Append a value to a document field.

-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