Rooba
/
perkeep
mirror of https://github.com/perkeep/perkeep.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
mpl 2018-07-16 19:47:11 +02:00
parent 9c7ceeb90a
commit bb8bb2ac63
2 changed files with 21 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/README.md
View File

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

20
doc/files-and-permanodes.md Normal file
View File

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