Mv

The mv command is used to move document folders around your library (or to another library).

It will (except when run with --all) bring up the picker with a list of documents that match the query. You can then select the document or documents you’d like to move.

The command works similarly to the Unix mv command. Hence, when the specified target folder exists, the document’s current main folder is moved into the target folder. If the specified target folder doesn’t exist, then the current folder is renamed to the target folder name. Unlike Unix mv, if a target folder isn’t given, it defaults to the add-folder-name pattern, so papis mv QUERY renames matching documents to their default folder names.

Folder names are cleaned, so that characters that can lead to invalid file paths are avoided (see doc-paths-extra-chars for a list of allowed characters and how to change it). This cleaning applies to all path components, including any literal subfolders passed to --to. This means and you cannot use the mv command to move docs into a folder containing excluded characters.

The mv command will first check whether moving the folders as specified will fail. If any errors are encountered, they are displayed and you will be prompted whether you want to abort or move the unproblematic documents (if any exist).

Examples

• Query documents by author “Rick Astley” and move some of them. After picking the relevant documents, they will be renamed to their default names specified by the add-folder-name option.

  papis mv author:"Rick Astley"
  

• You can use --to to pass the path of the target folder, relative to the library root. Here we’ll move a document by the author “Rick Astley” to a folder named rick-astley:

  papis mv --to rick-astley author:"Rick Astley"
  

  If the folder “rick-astley” doesn’t exist, then the document’s folder will be renamed to that so that the new folder becomes “rick-astley”. If the folder “rick-astley” exists, then the document’s folder will be moved into it. If, say, the document’s folder is currently “rick-s-the-best”, then the new folder will be “rick-astley/rick-s-the-best”.

  If multiple selected documents resolve to the exact same folder name, Papis will warn you and skip those documents. Consider the above case when the target folder doesn’t exist. Here, each document would be renamed to rick-astley, causing Papis to skip the documents to avoid collisions. In contrast, if the target folder already exists, each document will be placed into its own subfolder (e.g. “rick-astley/rick-s-the-best” and “rick-astley/rick-s-very-cool”), so there is no risk of collision.

• You can use formatting patterns to generate the folder names. For instance, to organise all documents by author “Rick Astley” by year, you can use this command:

  papis mv --to "{doc[year]}" --all author:"Rick Astley"
  

  Note that the --all flag means that the picker isn’t shown and all documents matching the query will be moved.

• You can use the --batch flag to skip all prompts. You will not be prompted if there are problematic moves and all unproblematic moves will happen automatically. If an unexpected error occurs while moving a document (e.g. a permission error), the command logs a warning and continues with the next document instead of aborting.

  papis mv --batch --all author:"Rick Astley"
  

Command-line Interface

Move a document into another folder.

Usage

papis mv [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

-t, --to <to>

Path relative to the library root

--target-library <target_library>

Target library

-b, --batch

Do not prompt. Warnings are logged but moves proceed automatically.

--git, --no-git

Commit changes to git.

--sort <FIELD>

Sort documents with respect to the FIELD.

--reverse

Reverse sort order.

--doc-folder <doc_folder>

Document folder on which to apply action.

-a, --all

Apply action to all matching documents.

Arguments

QUERY

Optional argument