samschott/maestral
1
1
Fork 0
mirror of https://github.com/samschott/maestral.git synced 2024-09-22 11:27:35 +03:00
Code Issues Projects Releases Wiki Activity

[docs] update config and state file docs

Browse Source
This commit is contained in:
Sam Schott 2021-09-14 18:04:02 +01:00
parent 57c56a42cc
commit 7a2fbe7316
2 changed files with 40 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/background/config_files.rst
View File

@ -6,35 +6,36 @@ The config files are located at ``$XDG_CONFIG_HOME/maestral`` on Linux (typicall
``~/.config/maestral``) and ``~/Library/Application Support/maestral`` on macOS. Each
configuration will get its own INI file with the settings documented below.
Config values in the sections ``main`` and ``account`` should not be edited manually but
Config values for ``path`` and ``excluded_items`` should not be edited manually but
rather through the corresponding CLI commands or GUI options. This is because changes of
these settings require Maestral to perform accompanying actions, e.g., download items
which have been removed from the excluded list or move the local Dropbox directory.
Those will not be performed if the user edits the options manually.
Changes to the other sections may be performed manually but will only take effect once
Maestral is restarted. Maestral will overwrite the entire config file if any change is
made to one of the options through the ``maestral.config`` module.
This also holds for the ``account_id`` which will be written to the config file after
successfully completing the OAuth flow with Dropbox servers.
Any changes will only take effect once Maestral is restarted. Any changes made to the
config file may be overwritten without warning if made while the sync daemon is running.
.. code-block:: ini
[main]
# The current Dropbox directory
path = /Users/samschott/Dropbox (Maestral)
# List of excluded files and folders
excluded_items = ['/test_folder', '/sub/folder']
# Config file version (not the Maestral version!)
version = 15.0.0
[account]
[auth]
# Unique Dropbox account ID. The account's email
# address may change and is therefore not stored here.
account_id = dbid:AABP7CC5bpYd8ghjIColDFrMoc9SdhACA4
# The keychain to store user credentials. If "automatic",
# will be set automatically from available backends when
# completing the OAuth flow.
keyring = keyring.backends.macOS.Keyring
[app]
# Level for desktop notifications:
@ -56,6 +57,12 @@ made to one of the options through the ``maestral.config`` module.
[sync]
# The current Dropbox directory
path = /Users/UserName/Dropbox (Maestral)
# List of excluded files and folders
excluded_items = ['/test_folder', '/sub/folder']
# Interval in sec to perform a full reindexing
reindex_interval = 604800

35
docs/background/state_files.rst
View File

@ -12,10 +12,11 @@ Database
********
The index is stored in a SQLite database with contains the sync index, the sync event
history of the last week and a cache of locally calculated content hashes. SQLAlchemy is
used to manage the database and the table declarations are given by the definitions of
:class:`maestral.database.IndexEntry`, :class:`maestral.database.SyncEvent` and
:class:`maestral.database.HashCacheEntry`.
history of the last week and a cache of locally calculated content hashes. We use our own
light-weight ORM layer, defined in :class:`maestral.utils.orm`, to manage the mapping
between Python objects and database rows. The actual table declarations are given by the
definitions of :class:`maestral.database.IndexEntry`, :class:`maestral.database.SyncEvent`
and :class:`maestral.database.HashCacheEntry`.
State file
**********
@ -30,41 +31,49 @@ The state file has the following sections:
version = 12.0.0
[account]
email = foo@bar.com
display_name = Foo Bar
abbreviated_name = FB
type = business
usage = 39.2% of 1312.8TB used
usage_type = team
# Information about the user's root namespace. This
# may be a personal namespace or a Team Space for certain
# Dropbox Business accounts.
path_root_type = team
path_root_nsid = 1287234
home_path = /User Name
[auth]
# The type of OAuth access token used:
# legacy: long-lived token
# offline: short-lived token with long-lived refresh token
token_access_type = offline
[app]
# Version for which update / migration scripts have
# run. This is bumped to the currently installed
# version after an update.
updated_scripts_completed = 1.2.0
# Time stamp of last update notification
update_notification_last = 0.0
# Latest avilable release
latest_release = 1.2.0
[sync]
# Cursor reflecting last-synced remote state
cursor = ...
# Time stamp reflecting last-synced local state
lastsync = 1589979736.623609
# Time stamp of last full reindexing
last_reindex = 1589577566.8533309