From bb8bb2ac635d0555a8db221e5634b9864beccce1 Mon Sep 17 00:00:00 2001 From: mpl Date: Mon, 16 Jul 2018 19:47:11 +0200 Subject: [PATCH] doc: add files vs permanodes explanation The confusion of users regarding files VS permanodes and the related questions comes back very often on IRC or on the mailing-lists. Therefore, this small explanation that we can point them to should help alleviate that confusion. Change-Id: I02acd38754f866acb4fe91c4dfa7e93ef80ac8ea --- doc/README.md | 1 + doc/files-and-permanodes.md | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 doc/files-and-permanodes.md diff --git a/doc/README.md b/doc/README.md index 0300ad150..410113ecc 100644 --- a/doc/README.md +++ b/doc/README.md @@ -20,6 +20,7 @@ synchronization to cloud storage. securely connect to your Perkeep server(s) * [Search Commands](/doc/search-ui.md): Covers the available search operators * [Configuring Geocoding](/doc/geocoding.md): how to enable geocoding (the `loc:` search operator) +* [Files or Permanodes](/doc/files-and-permanodes.md): explains the basic difference between a file and a permanode ## For Developers diff --git a/doc/files-and-permanodes.md b/doc/files-and-permanodes.md new file mode 100644 index 000000000..6f9fac487 --- /dev/null +++ b/doc/files-and-permanodes.md @@ -0,0 +1,20 @@ +# Files or Permanodes? + +Even though the basic unit in Perkeep is the blob, the high-level object that +Perkeep relies on and manipulates is the [**permanode**](/doc/schema/permanode.md) +(which is just a kind of blob). Permanodes are what one interacts with in the +various interfaces, such as the Web UI. + +That is why, when one uses e.g. `pk-put file somefile`, one does not see any +representation of the uploaded file in the Web UI. The file must be associated +to a permanode. With the **pk-put file** command, there are two main ways to achieve +that: the `--filenodes` option, and the `--permanode` option. But what is the +difference? + +* Use the `--filenodes` option if you want to attach each of the files given as +argument to their own individual permanode. Each of them will then appear in the +Web UI as a distinct object that can be browsed, searched, displayed, etc. +* Use the `--permanode` option if you want to preserve your directories +hierarchy. The hierarchy will be browsable, but only the top-level directory +will be associated with a permanode and represented as a distinct object. This +is mostly meant for archival usage.