Parameter Settings

Workflow Overview:
Perform quick operations on a list of paths obtained after filtering based on path matching and file attributes.

Workflow Key Points:

1. Obtain the list of paths to be processed.
2. Further process the list of paths.

Quick Feature Categories:

1. Read-only Operations: Process source path data without writing or modification.
   E.g., list, search, fdups, archive, unarchive, mirror.
2. Read-write Operations: Process source path data involving modification or deletion.
   E.g., replace, rmdir, clean, wipe.

The correspondence between quick features and CLI commands is as follows:

• Quick Features (Available Commands)
• Global Options
• Command Arguments

Terminal CLI Commands:

ft --help
FileTools: cross-platform glob & streams.
Usage: ft <command> <source> [arguments]

Global options:
-h, --help                        Print this usage information.
-v, --verbose                     Show additional command output.
    --version                     Print the tool version.
    --source=<path>               Specify the source (file|directory)
    --config=<file>               Loads a config file for variable referencing
    --config_txt=<yaml>           Loads a yaml text for variable referencing
    --config_gen                  Generate a custom config on curdir.
    --errexit                     exit on error.
                                  (defaults to on)
    --define                      Define or override a variable from command line
    --pattern                     Glob pattern
                                  (defaults to "**")
    --excludes                    Glob pattern after exclusion (e.g. --excludes='.**')
    --fields                      show fields (ok, action, type, mime, perm, time, size, extra)
    --size_le                     file size less than (in bytes, unit:B|K|M|G|T|P)
    --size_ge                     file size greater than (in bytes, unit:B|K|M|G|T|P)
    --time_le                     file time before (yyyyMMddTHHmmss | yyyyMMdd)
    --time_ge                     file time after (yyyyMMddTHHmmss | yyyyMMdd)
    --time_type=<modified>        file time type (changed | modified | accessed)

          [changed]               ctime - change time
          [modified] (default)    mtime - modification time
          [accessed]              atime - access time

Available commands:
  archive     archive source file|directory to target file.
  clean       clean source file|diretory
  execute     execute command blocks defined in `--config`, using `--source` as the working directory.
  fdups       find duplicate files from source diretory
  list        listing all entities that match a glob
  mirror      mirror source file|diretory to target directory
  rmdir       remove empty source directory
  search      search with regexp or replace.
  shell       execute script blocks defined in `--config`, using `--source` as the working directory.
  unarchive   unarchive tar|tgz source file to target directory
  wipe        secure wipe source file|diretory

Run "ft help <command>" for more information about a command.

T1GUI-Global Parameters - Filter

1. --pattern: Path Matching Pattern
2. --excludes: Exclusion Pattern
3. --size_ge: File Size Greater Than or Equal To
4. --size_le: File Size Less Than or Equal To
5. --time_ge: File Time After
6. --time_le: File Time Before
7. --fields: Display Fields
8. Save Current Configuration
9. More Options:
   • SaveAs Configuration File
   • Preview Configuration File
   • Load Configuration File
10. Return and Apply Current Configuration

T2GUI-Command Arguments - Search

ft help search
Search with regexp or replace.

Usage: ft search <source> --regexp=<pattern> [arguments]
-h, --help                Print this usage information.
    --regexp=<pattern>    regex pattern
    --extmime             ext mime for search (e.g. --extmine='yaml=text/yaml')
    --[no-]linebyline     line by line file processing
                          (defaults to on)
    --esc                 escape regexp special characters.
    --rei                 regex use case insensitive.
    --reu                 regex use unicode.
    --res                 regex use dot all.
    --rem                 regex use multiLine.
    --replace             regexp has match to replace

Run "ft help" to see global options.

If only searching, leave the replacement content empty.

1. --regexp: Regular Expression
2. --replace: Replacement Content
3. Regular Expression Options:
   • reI (--rei): Case-insensitive;
   • reU (--reu): Use Unicode;
   • reM (--rem): Multiline mode;
   • reS (--res): Dot matches all characters.
4. --linebyline: Process file line by line

T3GUI-Command Arguments - Target Path

• A. mirror Command Arguments
• B. unarchive Command Arguments
• C. archive Command Arguments

• A|B|C 1: --relative: Target path uses the relative structure of the source path.
• A|B|C 2: --tail: Target path includes the tail segment level of the source path.
• A|B|C 3: --target: Specify the target directory.

Example effects are as follows: --source=~/Downloads/ft --target=~/Downloads/backups

• --no-relative: Does not use relative paths. The complete source path structure will be copied to the target path.
  Example result: ~/Downloads/backups/${HOME}/Donwloads/ft.
• --relative --tail=0 (default): The target path is the specified target directory itself.
  Example result: ~/Downloads/backups
• --relative --tail=1: The target path includes the last level of the source path directory.
  Example result: ~/Downloads/backups/ft
• --relative --tail=2: The target path includes the last two levels of the source path directory.
  Example result: ~/Downloads/backups/Downloads/ft

Example (mirror):

ft help mirror

mirror source file|diretory to target directory
Usage: ft mirror <source> <target> [arguments]
-h, --help                  Print this usage information.
    --target=<directory>    target directory
    --[no-]relative         mirror source use relative directory.
                            (defaults to on)
    --tail=<int>            tail source injection to target.
                            (defaults to "0")

# Default: --relative --tail=0; Target path: ~/Downloads/backups/temp/
ft mirror ~/Downloads/ft ~/Downloads/backups/temp -v --fields=ok,action,type
1  mirror f ~/Downloads/backups/temp/README.md
1  mirror f ~/Downloads/backups/temp/pubspec.yaml

# Example: --relative --tail=1; Target path: ~/Downloads/backups/ft/
ft mirror ~/Downloads/ft ~/Downloads/backups/ --tail=1 -v --fields=ok,action,type
1  mirror f ~/Downloads/backups/ft/README.md
1  mirror f ~/Downloads/backups/ft/pubspec.yaml

T4GUI-Global Parameters - Variable Settings

The Variable feature corresponds to the --define option in the CLI.

• System Environment Variables
  E.g., HOME, PATH, HTTP_PROXY
• User-Defined Variables
  Variable names only support lowercase letters a-z and underscores _;
  E.g., my_project_dir, my_backup_dir, my_log_dir, my_data_dir
• Runtime Variables
  CURDIR, CURDATE, CURDATETIME

Variable Priority: User-Defined Variables < System Environment Variables < Runtime Variables.

A. Example: --define='downloads=~/Downloads,ft_target_dir=~/Documents/FileShows,backup_files=**~'

In the GUI, this is equivalent to setting the following three items separately:

• downloads=~/Downloads
• ft_target_dir=~/Documents/FileShows
• backup_files=**~

Variable Substitution Examples:

# Clean all Emacs backup files in the downloads directory.
ft clean --source='$downloads' --pattern='$backup_files' -v --define='downloads=~/Downloads,backup_files=**~'

# Archive the ~/Downloads/ft folder daily.
ft archive --source='$downloads/ft' --target='$ft_target_dir/archive/$CURDATE' --tail=1  -v --define='downloads=~/Downloads,ft_target_dir=~/Documents/FileShows'

B. Target Base Directory (External Data Root)

In sandboxed systems like macOS, Android, and Linux (e.g., Snap/Flatpak), applications are strictly isolated from external data, and accessing external data requires explicit authorization.

Here, you can select and authorize an external directory to serve as this application's $ft_target_dir, for unified reading, writing, and management of external data. The application will gain persistent access to $ft_target_dir and its subdirectories.

For example, if $ft_target_dir is set to /storage/emulated/0/Documents, the application's related external directories will be organized as follows:

• mirror_to -> $ft_target_dir/mirror
• archive_to -> $ft_target_dir/archive
• unarchive_to -> $ft_target_dir/unarchive

(Note: Due to its strict sandboxing model, iOS typically does not support users specifying an arbitrary external directory as a base for applications.)

C. App-Internal HOME Variable Override

In Unix-like systems, ~ represents the HOME environment variable. However, in sandboxed environments (e.g., macOS, Android, Linux Snap/Flatpak), this variable may be incorrect or unavailable to applications.

This feature allows you to customize and override the application's internal HOME variable. This app-specific setting does not affect system environment variables, ensuring correct HOME-based path resolution within the app.

Example: If the internal HOME is /storage/emulated/0/Documents and the file is /storage/emulated/0/Documents/archive/ft.tgz, then ~/archive/ft.tgz will correctly resolve to that file within the application.

T5GUI-Command Arguments - Batch Processing

In batch processing, commands are used for the ft execute subcommand, and scripts are used for the ft shell subcommand.

1. Source Paths (sources)
   This field's data originates from the source path input on the shortcuts page, facilitating reuse during saving and loading. It has no direct association with the execute and shell subcommands.
2. Commands (commands)
   Only built-in ft subcommands are supported.
3. Scripts (scripts)
   Supports all CLI commands available in the current operating system.

Example (commands):

Suppose you have a website located at /mnt/100G/mywebsite1/, which contains a logs folder, a dbs folder (using SQLite), and an imagen folder. You need to archive dbs and logs to /mnt/100T/archive/mywebsite1/ every morning, then clear logs, and remove images older than 1 month.

# Archive logs and dbs folders.
ft archive /mnt/100G/mywebsite1/dbs /mnt/100T/archive/mywebsite1/\$CURDATE --tail=1
ft archive /mnt/100G/mywebsite1/logs /mnt/100T/archive/mywebsite1/\$CURDATE --tail=1
# Clear all files in the logs folder.
ft clean /mnt/100G/mywebsite1/logs
# Clear images older than 1 month.
ft clean /mnt/100G/mywebsite1/imagen --time_le='1 month ago'

If you save these commands to a configuration file named ft_mywebsite1_archive.yaml, you can run them as follows:

ft execute . --config=ft_mywebsite1_archive.yaml

Example (scripts):

Suppose you have a source code directory located at ~/Projects/, containing project folders ft and fileshows. The fileshows application needs to import the ft package. Before building fileshows, you need to pull the latest code for both projects and update their dependencies.

cd ~/Projects/ft
# git reset --hard origin/main
git pull
dart pub get --no-example
dart pub upgrade

cd ~/Projects/fileshows
# git reset --hard origin/main
git pull
flutter pub get --no-example
flutter pub upgrade

If you save these scripts to a configuration file named ft_fileshows_refresh.yaml, you can run them as follows:

ft shell . --cofnig=ft_fileshows_refresh.yaml

T6GUI-Scheduled Tasks (Cronjob)

If you have batch operations that need to be executed periodically, you can set them up here.

1. Operation (Action): run | pause | stop | delete
2. Frequency (Time): hourly | daily | weekly | ...
3. Cron Expression (Expression)
4. Log Path (Logpath): Specify the log saving directory
5. Run Once (Run Once)

Example (commands):

> We incrementally mirror documents from the user's temporary desktop workspace, allowing them to revisit documents from the last few days.

# Current Time (NOW): 2025-08-29T09:02:26.441496;
# Current Date (CURDATE): 20250829; Current Date-Time (CURDATETIME): 20250829090226
# Date 1 Day Ago (AGODATE1DAY): 20250828; Date-Time 1 Day Ago (AGODATETIME1DAY): 20250828090226
# Date 1 Week Ago (AGODATE1WEEK): 20250822; Date-Time 1 Week Ago (AGODATETIME1WEEK): 20250822090226
# ft mirror ~/Desktop ~/Documents/FileShows/mirror/Desktop/\$CURDATE/\$CURDATETIME
ft mirror ~/Desktop ~/Documents/FileShows/mirror/Desktop/\$CURDATE/
ft rmdir --force ~/Documents/FileShows/mirror/Desktop/\$AGODATE1WEEK/
# ft rmdir --force --keeptop ~/Documents/FileShows/mirror/Desktop/ --time_type=changed --time_le='1 week ago'

T7GUI-Metadata Settings (MetaData)

Example:

• Name (Name):
  Incremental Desktop Mirroring
• Description (Description):
  Mirrored the past week's desktop files incrementally to another directory.
• Authors (Authors):
  crown.hg@gmail.com

T0GUI-macOS: Desktop File Access Permissions

To ensure the FileShows application can access your desktop files:

1. Go to "System Settings" > "Privacy & Security".
2. Click "Files and Folders", locate "FileShows", and check the "Desktop Folder" option.
3. If FileShows is not listed under "Files and Folders", click "Full Disk Access", then manually add and enable the "FileShows" application.

After completing these settings, please restart the FileShows application to ensure the changes take effect.