lgcosta/paperless-ngx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Also update the file name handling docs

Browse Source
This commit is contained in:
shamoon
2024-03-06 12:54:41 -08:00
parent c1633ef37a
commit 42a263ab42
2 changed files with 32 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docs/advanced_usage.md
View File

@@ -256,7 +256,8 @@ document. You will end up getting files like `0000123.pdf` in your media
directory. This isn't necessarily a bad thing, because you normally directory. This isn't necessarily a bad thing, because you normally
don't have to access these files manually. However, if you wish to name don't have to access these files manually. However, if you wish to name
your files differently, you can do that by adjusting the your files differently, you can do that by adjusting the
[`PAPERLESS_FILENAME_FORMAT`](configuration.md#PAPERLESS_FILENAME_FORMAT) configuration option. Paperless adds the [`PAPERLESS_FILENAME_FORMAT`](configuration.md#PAPERLESS_FILENAME_FORMAT) configuration option
or using [storage paths (see below)](#storage-paths). Paperless adds the
correct file extension e.g. `.pdf`, `.jpg` automatically. correct file extension e.g. `.pdf`, `.jpg` automatically.
This variable allows you to configure the filename (folders are allowed) This variable allows you to configure the filename (folders are allowed)
@@ -289,6 +290,15 @@ will create a directory structure as follows:
paperless will report your files as missing and won't be able to find paperless will report your files as missing and won't be able to find
them. them.
!!! tip
Paperless checks the filename of a document whenever it is saved. Changing (or deleting)
a [storage paths](#storage-paths) will automatically be reflected in the file system. However,
when changing `PAPERLESS_FILENAME_FORMAT` you will need to manually run the
[`document renamer`](administration.md#renamer) to move any existing documents.
#### Placeholders
Paperless provides the following placeholders within filenames: Paperless provides the following placeholders within filenames:
- `{asn}`: The archive serial number of the document, or "none". - `{asn}`: The archive serial number of the document, or "none".
@@ -321,6 +331,12 @@ Paperless provides the following placeholders within filenames:
- `{original_name}`: Document original filename, minus the extension, if any, or "none" - `{original_name}`: Document original filename, minus the extension, if any, or "none"
- `{doc_pk}`: The paperless identifier (primary key) for the document. - `{doc_pk}`: The paperless identifier (primary key) for the document.
!!! warning
When using file name placeholders, in particular when using `{tag_list}`,
you may run into the limits of your operating system's maximum path lengths.
In that case, files will retain the previous path instead and the issue logged.
Paperless will try to conserve the information from your database as Paperless will try to conserve the information from your database as
much as possible. However, some characters that you can use in document much as possible. However, some characters that you can use in document
titles and correspondent names (such as `: \ /` and a couple more) are titles and correspondent names (such as `: \ /` and a couple more) are
@@ -331,34 +347,12 @@ paperless will automatically append `_01`, `_02`, etc to the filename.
This happens if all the placeholders in a filename evaluate to the same This happens if all the placeholders in a filename evaluate to the same
value. value.
!!! tip If there are any errors in the placeholders included in `PAPERLESS_FILENAME_FORMAT`,
paperless will fallback to using the default naming scheme instead.
You can affect how empty placeholders are treated by changing the
following setting to `true`.
```
PAPERLESS_FILENAME_FORMAT_REMOVE_NONE=True
```
Doing this results in all empty placeholders resolving to "" instead
of "none" as stated above. Spaces before empty placeholders are
removed as well, empty directories are omitted.
!!! tip
Paperless checks the filename of a document whenever it is saved.
Therefore, you need to update the filenames of your documents and move
them after altering this setting by invoking the
[`document renamer`](administration.md#renamer).
!!! warning
Make absolutely sure you get the spelling of the placeholders right, or
else paperless will use the default naming scheme instead.
!!! caution !!! caution
As of now, you could totally tell paperless to store your files anywhere As of now, you could potentially tell paperless to store your files anywhere
outside the media directory by setting outside the media directory by setting
``` ```
@@ -366,28 +360,25 @@ value.
``` ```
However, keep in mind that inside docker, if files get stored outside of However, keep in mind that inside docker, if files get stored outside of
the predefined volumes, they will be lost after a restart of paperless. the predefined volumes, they will be lost after a restart.
!!! warning ##### Empty placeholders
When file naming handling, in particular when using `{tag_list}`, You can affect how empty placeholders are treated by changing the
you may run into the limits of your operating system's maximum [`PAPERLESS_FILENAME_FORMAT_REMOVE_NONE`](configuration.md#PAPERLESS_FILENAME_FORMAT_REMOVE_NONE) setting.
path lengths. Files will retain the previous path instead and
the issue logged.
## Storage paths Enabling this results in all empty placeholders resolving to "" instead of "none" as stated above. Spaces
before empty placeholders are removed as well, empty directories are omitted.
One of the best things in Paperless is that you can not only access the ### Storage paths
documents via the web interface, but also via the file system.
When a single storage layout is not sufficient for your use case, When a single storage layout is not sufficient for your use case, storage paths allow for more complex
storage paths come to the rescue. Storage paths allow you to configure structure to set precisely where each document is stored in the file system.
more precisely where each document is stored in the file system.
- Each storage path is a [`PAPERLESS_FILENAME_FORMAT`](configuration.md#PAPERLESS_FILENAME_FORMAT) and - Each storage path is a [`PAPERLESS_FILENAME_FORMAT`](configuration.md#PAPERLESS_FILENAME_FORMAT) and
follows the rules described above follows the rules described above
- Each document is assigned a storage path using the matching - Each document is assigned a storage path using the matching algorithms described above, but can be
algorithms described above, but can be overwritten at any time overwritten at any time
For example, you could define the following two storage paths: For example, you could define the following two storage paths:

2
docs/configuration.md
View File

@@ -264,7 +264,7 @@ directory. See [File name handling](advanced_usage.md#file-name-handling) for de
: Tells paperless to replace placeholders in : Tells paperless to replace placeholders in
`PAPERLESS_FILENAME_FORMAT` that would resolve to `PAPERLESS_FILENAME_FORMAT` that would resolve to
'none' to be omitted from the resulting filename. This also holds 'none' to be omitted from the resulting filename. This also holds
true for directory names. See [File name handling](advanced_usage.md#file-name-handling) for true for directory names. See [File name handling](advanced_usage.md#empty-placeholders) for
details. details.
Defaults to `false` which disables this feature. Defaults to `false` which disables this feature.