From 1f183ca03ec96aef1fa895e24f0ae256a0a53d84 Mon Sep 17 00:00:00 2001 From: abraunegg Date: Mon, 9 Oct 2023 08:18:13 +1100 Subject: [PATCH] Update PR * Update PR with doc updates --- docs/application-config-options.md | 114 +++++++++++++++++++++++++++-- docs/usage.md | 54 +++++++++++++- 2 files changed, 159 insertions(+), 9 deletions(-) diff --git a/docs/application-config-options.md b/docs/application-config-options.md index 2f2df44b2..3ab3d6465 100644 --- a/docs/application-config-options.md +++ b/docs/application-config-options.md @@ -3,7 +3,90 @@ Before reading this document, please ensure you are running application version [![Version](https://img.shields.io/github/v/release/abraunegg/onedrive)](https://github.com/abraunegg/onedrive/releases) or greater. Use `onedrive --version` to determine what application version you are using and upgrade your client if required. ## Table of Contents -TABLE OF CONTENTS GOES HERE + +- [Configuration File Options](#configuration-file-options) + - [application_id](#application_id) + - [azure_ad_endpoint](#azure_ad_endpoint) + - [azure_tenant_id](#azure_tenant_id) + - [bypass_data_preservation](#bypass_data_preservation) + - [check_nomount](#check_nomount) + - [check_nosync](#check_nosync) + - [classify_as_big_delete](#classify_as_big_delete) + - [cleanup_local_files](#cleanup_local_files) + - [connect_timeout](#connect_timeout) + - [data_timeout](#data_timeout) + - [debug_https](#debug_https) + - [disable_download_validation](#disable_download_validation) + - [disable_notifications](#disable_notifications) + - [disable_upload_validation](#disable_upload_validation) + - [display_running_config](#display_running_config) + - [dns_timeout](#dns_timeout) + - [download_only](#download_only) + - [drive_id](#drive_id) + - [dry_run](#dry_run) + - [enable_logging](#enable_logging) + - [force_http_11](#force_http_11) + - [ip_protocol_version](#ip_protocol_version) + - [local_first](#local_first) + - [log_dir](#log_dir) + - [monitor_fullscan_frequency](#monitor_fullscan_frequency) + - [monitor_interval](#monitor_interval) + - [monitor_log_frequency](#monitor_log_frequency) + - [no_remote_delete](#no_remote_delete) + - [operation_timeout](#operation_timeout) + - [rate_limit](#rate_limit) + - [read_only_auth_scope](#read_only_auth_scope) + - [remove_source_files](#remove_source_files) + - [resync](#resync) + - [resync_auth](#resync_auth) + - [skip_dir](#skip_dir) + - [skip_dir_strict_match](#skip_dir_strict_match) + - [skip_dotfiles](#skip_dotfiles) + - [skip_file](#skip_file) + - [skip_size](#skip_size) + - [skip_symlinks](#skip_symlinks) + - [space_reservation](#space_reservation) + - [sync_business_shared_items](#sync_business_shared_items) + - [sync_dir](#sync_dir) + - [sync_dir_permissions](#sync_dir_permissions) + - [sync_file_permissions](#sync_file_permissions) + - [sync_root_files](#sync_root_files) + - [upload_only](#upload_only) + - [user_agent](#user_agent) + - [webhook_enabled](#webhook_enabled) + - [webhook_expiration_interval](#webhook_expiration_interval) + - [webhook_listening_host](#webhook_listening_host) + - [webhook_listening_port](#webhook_listening_port) + - [webhook_public_url](#webhook_public_url) + - [webhook_renewal_interval](#webhook_renewal_interval) +- [Command Line Interface (CLI) Only Options](#command-line-interface-cli-only-options) + - [CLI Option: --auth-files](#cli-option---auth-files) + - [CLI Option: --auth-response](#cli-option---auth-response) + - [CLI Option: --confdir](#cli-option---confdir) + - [CLI Option: --create-directory](#cli-option---create-directory) + - [CLI Option: --create-share-link](#cli-option---create-share-link) + - [CLI Option: --destination-directory](#cli-option---destination-directory) + - [CLI Option: --display-config](#cli-option---display-config) + - [CLI Option: --display-sync-status](#cli-option---display-sync-status) + - [CLI Option: --force](#cli-option---force) + - [CLI Option: --force-sync](#cli-option---force-sync) + - [CLI Option: --get-file-link](#cli-option---get-file-link) + - [CLI Option: --get-sharepoint-drive-id](#cli-option---get-sharepoint-drive-id) + - [CLI Option: --logout](#cli-option---logout) + - [CLI Option: --modified-by](#cli-option---modified-by) + - [CLI Option: --monitor | -m](#cli-option---monitor--m) + - [CLI Option: --print-access-token](#cli-option---print-access-token) + - [CLI Option: --reauth](#cli-option---reauth) + - [CLI Option: --remove-directory](#cli-option---remove-directory) + - [CLI Option: --single-directory](#cli-option---single-directory) + - [CLI Option: --source-directory](#cli-option---source-directory) + - [CLI Option: --sync | -s](#cli-option---sync--s) + - [CLI Option: --verbose | -v+](#cli-option---verbose--v) + - [CLI Option: --with-editing-perms](#cli-option---with-editing-perms) +- [Depreciated Configuration File and CLI Options](#depreciated-configuration-file-and-cli-options) + - [min_notify_changes](#min_notify_changes) + - [CLI Option: --synchronize](#cli-option---synchronize) + ## Configuration File Options @@ -775,14 +858,27 @@ _**Description:**_ _**Usage Example:**_ ### CLI Option: --force -_**Description:**_ This CLI option enables the force the deletion of data when a 'big delete' is detected +_**Description:**_ This CLI option enables the force the deletion of data when a 'big delete' is detected. _**Usage Example:**_ +_**Additional Usage Notes:**_ This option should only be used when a 'big delete' has been triggered and you actually want to delete all the data, that will be deleted, online. + ### CLI Option: --force-sync -_**Description:**_ +_**Description:**_ This CLI option enables the syncing of a specific directory, using the Client Side Filtering application defaults, overriding any user application configuration. -_**Usage Example:**_ +_**Usage Example:**_ `onedrive --sync --verbose --force-sync --single-directory 'Data' + +_**Additional Usage Notes:**_ When this option is used, you will be presented with the following warning and risk acceptance: +```text +WARNING: Overriding application configuration to use application defaults for skip_dir and skip_file due to --synch --single-directory --force-sync being used + +The use of --force-sync will reconfigure the application to use defaults. This may have untold and unknown future impacts. +By proceeding in using this option you accept any impacts including any data loss that may occur as a result of using --force-sync. + +Are you sure you wish to proceed with --force-sync [Y/N] +``` +To procceed with this sync task, you must risk accept the actions you are taking. If you have any concerns, first use `--dry-run` and evaluate the outcome before proceeding with the actual action. ### CLI Option: --get-file-link _**Description:**_ @@ -827,9 +923,11 @@ _**Description:**_ _**Usage Example:**_ ### CLI Option: --single-directory -_**Description:**_ +_**Description:**_ This CLI option controls the applications ability to sync a specific single directory. -_**Usage Example:**_ +_**Usage Example:**_ `onedrive --sync --single-directory 'Data'` + +_**Additional Usage Notes:**_ The path specified is relative to your configured 'sync_dir' path. If the physical local path 'Folder' to sync is `~/OneDrive/Data/Folder` then the command would be `--single-directory 'Data/Folder'`. ### CLI Option: --source-directory _**Description:**_ @@ -842,9 +940,9 @@ _**Description:**_ This CLI option controls the 'Standalone Mode' operational as _**Usage Example:**_ `onedrive --sync` or `onedrive -s` ### CLI Option: --verbose | -v+ -_**Description:**_ +_**Description:**_ This CLI option controls the verbosity of the application output. Use the option once, to have normal verbose output, use twice to have debug level application output. -_**Usage Example:**_ +_**Usage Example:**_ `onedrive --sync --verbose` or `onedrive --monitor --verbose` ### CLI Option: --with-editing-perms _**Description:**_ diff --git a/docs/usage.md b/docs/usage.md index 8fc1a063f..24e24f693 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -3,7 +3,59 @@ Before reading this document, please ensure you are running application version [![Version](https://img.shields.io/github/v/release/abraunegg/onedrive)](https://github.com/abraunegg/onedrive/releases) or greater. Use `onedrive --version` to determine what application version you are using and upgrade your client if required. ## Table of Contents -TABLE OF CONTENTS GOES HERE + +- [Important Notes](#important-notes) + - [Upgrading from the 'skilion' Client](#upgrading-from-the-sklion-client) + - [Naming Conventions for Local Files and Folders](#naming-conventions-for-local-files-and-folders) + - [Compatibility with curl](#compatibility-with-curl) +- [First Steps](#first-steps) + - [Authorise the Application with Your Microsoft OneDrive Account](#authorise-the-application-with-your-microsoft-onedrive-account) + - [Display Your Applicable Runtime Configuration](#display-your-applicable-runtime-configuration) + - [Understanding OneDrive Client for Linux Operational Modes](#understanding-onedrive-client-for-linux-operational-modes) + - [Standalone Synchronisation Operational Mode (Standalone Mode)](#standalone-synchronisation-operational-mode-standalone-mode) + - [Ongoing Synchronisation Operational Mode (Monitor Mode)](#ongoing-synchronisation-operational-mode-monitor-mode) + - [Increasing application logging level](#increasing-application-logging-level) + - [Testing your configuration](#testing-your-configuration) + - [Performing a sync with Microsoft OneDrive](#performing-a-sync-with-microsoft-onedrive) + - [Performing a single directory synchronisation with Microsoft OneDrive](#performing-a-single-directory-synchronisation-with-microsoft-onedrive) + - [Performing a 'one-way' download synchronisation with Microsoft OneDrive](#performing-a-one-way-download-synchronisation-with-microsoft-onedrive) + - [Performing a 'one-way' upload synchronisation with Microsoft OneDrive](#performing-a-one-way-upload-synchronisation-with-microsoft-onedrive) + - [Performing a selective synchronisation via 'sync_list' file](#performing-a-selective-synchronisation-via-sync_list-file) + - [Performing a --resync](#performing-a-resync) + - [Performing a --force-sync without a --resync or changing your configuration](#performing-a-force-sync-without-a-resync-or-changing-your-configuration) + - [Enabling the Client Activity Log](#enabling-the-client-activity-log) + - [Client Activity Log Example:](#client-activity-log-example) + - [Client Activity Log Differences](#client-activity-log-differences) + - [GUI Notifications](#gui-notifications) + - [Handling a Microsoft OneDrive Account Password Change](#handling-a-microsoft-onedrive-account-password-change) + - [Determining the synchronisation result](#determining-the-synchronisation-result) +- [Frequently Asked Configuration Questions](#frequently-asked-configuration-questions) + - [How to change the default configuration of the client?](#how-to-change-the-default-configuration-of-the-client) + - [How to change where my data from Microsoft OneDrive is stored?](#how-to-change-where-my-data-from-microsoft-onedrive-is-stored) + - [How to change what file and directory permissions are assigned to data that is downloaded from Microsoft OneDrive?](#how-to-change-what-file-and-directory-permissions-are-assigned-to-data-that-is-downloaded-from-microsoft-onedrive) + - [How to only sync a specific directory?](#how-to-only-sync-a-specific-directory) + - [How to 'skip' files from syncing?](#how-to-skip-files-from-syncing) + - [How to 'skip' directories from syncing?](#how-to-skip-directories-from-syncing) + - [How to 'skip' dot files and folders from syncing?](#how-to-skip-dot-files-and-folders-from-syncing) + - [How to 'skip' files larger than a certain size from syncing?](#how-to-skip-files-larger-than-a-certain-size-from-syncing) + - [How to 'rate limit' the application to control bandwidth consumed for upload & download operations?](#how-to-rate-limit-the-application-to-control-bandwidth-consumed-for-upload--download-operations) + - [How can I prevent my local disk from filling up?](#how-can-i-prevent-my-local-disk-from-filling-up) + - [How does the client handle symbolic links?](#how-does-the-client-handle-symbolic-links) + - [How to synchronise shared folders (OneDrive Personal)?](#how-to-synchronise-shared-folders-onedrive-personal) + - [How to synchronise shared folders (OneDrive Business or Office 365)?](#how-to-synchronise-shared-folders-onedrive-business-or-office-365) + - [How to synchronise SharePoint / Office 365 Shared Libraries?](#how-to-synchronise-sharepoint--office-365-shared-libraries) + - [How to Create a Shareable Link?](#how-to-create-a-shareable-link) + - [How to Synchronise Both Personal and Business Accounts at once?](#how-to-synchronise-both-personal-and-business-accounts-at-once) + - [How to Synchronise Multiple SharePoint Libraries simultaneously?](#how-to-synchronise-multiple-sharepoint-libraries-simultaneously) + - [How to Receive Real-time Changes from Microsoft OneDrive Service, instead of waiting for the next sync period?](#how-to-receive-real-time-changes-from-microsoft-onedrive-service-instead-of-waiting-for-the-next-sync-period) + - [How to initiate the client as a background service?](#how-to-initiate-the-client-as-a-background-service) + - [OneDrive service running as root user via init.d](#onedrive-service-running-as-root-user-via-initd) + - [OneDrive service running as root user via systemd (Arch, Ubuntu, Debian, OpenSuSE, Fedora)](#onedrive-service-running-as-root-user-via-systemd-arch-ubuntu-debian-opensuse-fedora) + - [OneDrive service running as root user via systemd (Red Hat Enterprise Linux, CentOS Linux)](#onedrive-service-running-as-root-user-via-systemd-red-hat-enterprise-linux-centos-linux) + - [OneDrive service running as a non-root user via systemd (All Linux Distributions)](#onedrive-service-running-as-a-non-root-user-via-systemd-all-linux-distributions) + - [OneDrive service running as a non-root user via systemd (with notifications enabled) (Arch, Ubuntu, Debian, OpenSuSE, Fedora)](#onedrive-service-running-as-a-non-root-user-via-systemd-with-notifications-enabled-arch-ubuntu-debian-opensuse-fedora) + - [OneDrive service running as a non-root user via runit (antiX, Devuan, Artix, Void)](#onedrive-service-running-as-a-non-root-user-via-runit-antix-devuan-artix-void) + - [How to start a user systemd service at boot without user login?](#how-to-start-a-user-systemd-service-at-boot-without-user-login) ## Important Notes ### Upgrading from the 'skilion' Client