Command Line Interface¶
The doFolder package provides a comprehensive command-line interface for file and directory management operations. The CLI supports various subcommands for different tasks like comparing directories and calculating file hashes.
Usage Modes¶
The doFolder CLI provides two equivalent usage modes after installation via pip:
Unified Interface
do-folder [subcommand] [options]
python3 -m doFolder [subcommand] [options]
Direct Commands (shortcuts for specific subcommands)
do-compare [options] # Equivalent to: do-folder compare [options]
do-hash [options] # Equivalent to: do-folder hash [options]
Both modes provide identical functionality - the direct commands are convenient shortcuts for frequently used operations.
Global Options¶
All commands support these global options:
-v, --version Show version information
-vv, --full-version Show detailed version information including Python details
-w, --console-width INT Set console width for output formatting
--no-color Disable colored output
-m, --mute-warning Suppress warning messages
-t, --traceback Show full traceback on errors
-h, --help Show this help message and exit
Compare Command¶
The compare command allows you to compare two files or directories and optionally synchronize them.
Basic Usage¶
# Unified interface
do-folder compare path_A path_B [options]
python3 -m doFolder compare path_A path_B [options]
# Direct command (equivalent)
do-compare path_A path_B [options]
Arguments¶
path_A Path to the first file or directory
path_B Path to the second file or directory
Options¶
-C, --compare-mode {SIZE,CONTENT,TIMETAG,TIMETAG_AND_SIZE,IGNORE}
How to compare two files (default: TIMETAG_AND_SIZE)
SIZE: Compare by file size only
CONTENT: Compare by file content
TIMETAG: Compare by modification timestamp
TIMETAG_AND_SIZE: Compare by both timestamp and size
IGNORE: Ignore all differences
-S, --sync Synchronize the directories if they are different
-D, --sync-direction {BOTH,A2B,B2A,ASK}
Direction of synchronization (default: ASK)
BOTH: Synchronize in both directions
A2B: Synchronize from A to B only
B2A: Synchronize from B to A only
ASK: Prompt user for direction
-O, --overwrite [{A2B,B2A,ASK,AUTO,IGNORE}]
Overwrite mode (default: ASK)
A2B: Always overwrite B with A
B2A: Always overwrite A with B
ASK: Prompt user for each conflict
AUTO: Automatically decide based on modification time
IGNORE: Skip all overwrites
--create-root Create root directory if it does not exist
-R, --relative-timestamp [{ALWAYS,NEVER,AUTO}]
Timestamp display format (default: AUTO)
ALWAYS: Always show relative timestamps
NEVER: Always show absolute timestamps
AUTO: Automatically choose based on time difference
-y, --yes Do not prompt for confirmation if the sync plan is not pending and no overwrite is needed
-Y, --yes-overwrite Do not prompt for confirmation if the sync plan is not pending even if an overwrite is needed
Examples¶
Compare two directories:
# Using unified interface
do-folder compare /path/to/dir1 /path/to/dir2
# Using direct command (equivalent)
do-compare /path/to/dir1 /path/to/dir2
Compare and synchronize directories:
# Using unified interface
do-folder compare /path/to/source /path/to/backup --sync --sync-direction A2B
# Using direct command (equivalent)
do-compare /path/to/source /path/to/backup --sync --sync-direction A2B
Compare files by content:
# Using unified interface
do-folder compare file1.txt file2.txt --compare-mode CONTENT
# Using direct command (equivalent)
do-compare file1.txt file2.txt --compare-mode CONTENT
Hash Command¶
The hash command calculates and displays hash values for files using various algorithms.
Basic Usage¶
# Unified interface
do-folder hash [options] files...
python3 -m doFolder hash [options] files...
# Direct command (equivalent)
do-hash [options] files...
Default Behavior¶
When no specific algorithms are specified, the command uses the default hash algorithm:
# Using unified interface
do-folder hash file1.txt file2.txt
# Using direct command (equivalent)
do-hash file1.txt file2.txt
Algorithm Selection¶
Use the -a option to specify custom algorithms:
# Using unified interface
do-folder hash -a sha1,md5 file1.txt file2.txt
do-folder hash -a sha256 file1.txt -a blake2b file2.txt
# Using direct command (equivalent)
do-hash -a sha1,md5 file1.txt file2.txt
do-hash -a sha256 file1.txt -a blake2b file2.txt
Options¶
-a, --algorithms ALGORITHMS FILES
Specify algorithms (comma-separated) followed by files.
Can be used multiple times.
Example: -a sha1,md5 file1.txt file2.txt
-d, --allow-directory
Allow hashing of directories (hashes directory structure)
-r, --recursive Recursively hash all files in subdirectories
-A, --disable-aggregate-algos
Disable aggregate algorithms for better performance
-p, --to-absolute Display absolute paths in output
-f, --full-path Always display the full path regardless of conflicts
-s, --show-all Display all progress bars in any situation
-n, --thread-num INT Number of threads for parallel processing (default: 4)
--no-progress Disable progress bars and show results only
Supported Algorithms¶
The hash command supports various cryptographic hash algorithms including:
SHA family: sha1, sha224, sha256, sha384, sha512
MD5: md5
BLAKE2: blake2b, blake2s
SHA3: sha3_224, sha3_256, sha3_384, sha3_512
And other algorithms supported by Python’s hashlib
Examples¶
Calculate SHA256 hash for a single file:
# Using unified interface
do-folder hash -a sha256 document.pdf
# Using direct command (equivalent)
do-hash -a sha256 document.pdf
Calculate multiple hashes for multiple files:
# Using unified interface
do-folder hash -a sha1,sha256,md5 file1.txt file2.txt
# Using direct command (equivalent)
do-hash -a sha1,sha256,md5 file1.txt file2.txt
Hash all files in a directory recursively:
# Using unified interface
do-folder hash -r -d /path/to/directory
# Using direct command (equivalent)
do-hash -r -d /path/to/directory
Use multiple algorithm groups:
# Using unified interface
do-folder hash -a sha256 *.txt -a md5 *.pdf
# Using direct command (equivalent)
do-hash -a sha256 *.txt -a md5 *.pdf
Performance and Threading¶
The hash command supports parallel processing for better performance:
# Use 8 threads for faster processing (unified interface)
do-folder hash -n 8 -r /large/directory
# Use 8 threads for faster processing (direct command)
do-hash -n 8 -r /large/directory
# Show all progress bars for detailed monitoring (unified interface)
do-folder hash -s -r /path/with/many/files
# Show all progress bars for detailed monitoring (direct command)
do-hash -s -r /path/with/many/files
# Disable progress bars for cleaner output (unified interface)
do-folder hash --no-progress -r /large/directory
# Disable progress bars for cleaner output (direct command)
do-hash --no-progress -r /large/directory
Exit Codes¶
All commands return standard exit codes:
0: Success
1: General error
2: Command line argument error
Other: Specific error codes depending on the operation