From f79fbdead919ba79f3f8ea03cf981ba17dc171c8 Mon Sep 17 00:00:00 2001 From: Matteo Paonessa Date: Fri, 27 Dec 2024 20:02:08 +0100 Subject: [PATCH] CI and docs updates --- .github/FUNDING.yml | 2 + .github/dependabot.yml | 7 +- .github/workflows/clippy.yml | 15 +++ .github/workflows/fmt.yml | 21 ++++ .github/workflows/test.yml | 8 +- CHANGELOG.md | 41 ++++---- README.md | 141 +++++-------------------- docs/USAGE.md | 195 +++++++++++++++++++++++++++++++++++ rustfmt.toml | 5 - src/options.rs | 16 +-- 10 files changed, 293 insertions(+), 158 deletions(-) create mode 100644 .github/FUNDING.yml create mode 100644 .github/workflows/clippy.yml create mode 100644 .github/workflows/fmt.yml create mode 100644 docs/USAGE.md diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..3465cc7 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,2 @@ +github: [ Lymphatus ] +#custom: ['https://www.paypal.com/donate/?hosted_button_id=W74TDJHTBKSAY'] \ No newline at end of file diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 391287d..c0f251c 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,12 +1,7 @@ -# To get started with Dependabot version updates, you'll need to specify which -# package ecosystems to update and where the package manifests are located. -# Please see the documentation for all configuration options: -# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates - version: 2 updates: - package-ecosystem: "cargo" # See documentation for possible values directory: "/" # Location of package manifests open-pull-requests-limit: 0 schedule: - interval: "weekly" + interval: "weekly" \ No newline at end of file diff --git a/.github/workflows/clippy.yml b/.github/workflows/clippy.yml new file mode 100644 index 0000000..6fc0d6c --- /dev/null +++ b/.github/workflows/clippy.yml @@ -0,0 +1,15 @@ +name: Clippy check +on: + - push + - pull_request + +env: + RUSTFLAGS: "-Dwarnings" + +jobs: + clippy_check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run Clippy + run: cargo clippy --all-targets --all-features diff --git a/.github/workflows/fmt.yml b/.github/workflows/fmt.yml new file mode 100644 index 0000000..ea42033 --- /dev/null +++ b/.github/workflows/fmt.yml @@ -0,0 +1,21 @@ +name: Code formatting + +on: + - push + - pull_request + +jobs: + fmt_check: + name: Fmt + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - uses: dtolnay/rust-toolchain@stable + with: + components: rustfmt + + - name: Check code formatting + run: cargo fmt -- --check \ No newline at end of file diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 5e6a5f3..456c90d 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,10 +1,8 @@ name: Test on: - push: - branches: [ main ] - pull_request: - branches: [ main ] + - push + - pull_request env: CARGO_TERM_COLOR: always @@ -14,7 +12,7 @@ jobs: runs-on: ${{ matrix.os }} strategy: matrix: - os: [macos-latest, ubuntu-latest, windows-latest] + os: [ macos-latest, ubuntu-latest, windows-latest ] steps: - uses: actions/checkout@v4 diff --git a/CHANGELOG.md b/CHANGELOG.md index 9bd7ff9..3de46b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,21 +1,22 @@ ## CHANGELOG -* 0.22.0 - Same folder as input, suffix options + lossless flag -* 0.21.0 - Compress by quality and long/short edge resize options -* 0.20.0 - Keep original dates and format conversion -* 0.19.0 - Rust migration -* 0.18.0 - Fixed Windows build + libcaesium 0.9.3 -* 0.17.0 - libcaesium 0.9.2 -* 0.16.0 - Using libcaesium Rust library -* 0.15.2 - Fixed Windows -RS bug -* 0.15.1 - Fixed rename bug on Windows + "Compressing..." message -* 0.15.0 - Support for libcaesium 0.5.0 -* 0.14.0 - Added --quiet option -* 0.13.1 - Bugfix -* 0.13.0 - Bugfix -* 0.12.1 - Bugfix -* 0.12.0 - Resizing (experimental) -* 0.11.0 - Fixing paths issues and dry-run option -* 0.10.2 - Bugfixes & full Windows support -* 0.10.1 - All features are available -* 0.10.0 - Switched to cmake build system and libcaesium -* 0.9.1 - Initial development stage \ No newline at end of file + +- 1.0.0-beta.0 - Same folder as input, suffix options + lossless flag + code refactoring +- 0.21.0 - Compress by quality and long/short edge resize options +- 0.20.0 - Keep original dates and format conversion +- 0.19.0 - Rust migration +- 0.18.0 - Fixed Windows build + libcaesium 0.9.3 +- 0.17.0 - libcaesium 0.9.2 +- 0.16.0 - Using libcaesium Rust library +- 0.15.2 - Fixed Windows -RS bug +- 0.15.1 - Fixed rename bug on Windows + "Compressing..." message +- 0.15.0 - Support for libcaesium 0.5.0 +- 0.14.0 - Added --quiet option +- 0.13.1 - Bugfix +- 0.13.0 - Bugfix +- 0.12.1 - Bugfix +- 0.12.0 - Resizing (experimental) +- 0.11.0 - Fixing paths issues and dry-run option +- 0.10.2 - Bugfixes & full Windows support +- 0.10.1 - All features are available +- 0.10.0 - Switched to cmake build system and libcaesium +- 0.9.1 - Initial development stage \ No newline at end of file diff --git a/README.md b/README.md index 1620c6c..a6a258b 100644 --- a/README.md +++ b/README.md @@ -1,145 +1,58 @@ -## Caesium CommandLineTools -###### caesium-clt - v1.0.0-beta.0 +## Caesium Command Line Tools -###### REQUIREMENTS -* [Rust](https://www.rust-lang.org/tools/install) ----------- +[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/Lymphatus) +[![Test](https://github.com/Lymphatus/caesium-clt/workflows/Test/badge.svg)](https://github.com/Lymphatus/caesium-clt/actions?query=workflow%3ATest) +[![Clippy](https://github.com/Lymphatus/caesium-clt/actions/workflows/clippy.yaml/badge.svg)](https://github.com/Lymphatus/caesium-clt/actions/workflows/clippy.yaml) +[![Code formatting](https://github.com/Lymphatus/caesium-clt/actions/workflows/fmt.yaml/badge.svg)](https://github.com/Lymphatus/caesium-clt/actions/workflows/fmt.yaml) -###### COMPILATION -`cargo build --release` - ----------- - -###### USAGE - -``` -Usage: caesiumclt [OPTIONS] <--quality |--lossless|--max-size > <--output |--same-folder-as-input> [FILES]... - -Arguments: - [FILES]... - - -Options: - -q, --quality - sets output file quality between [0-100] - - --lossless - perform lossless compression - - --max-size - set the expected maximum output size in bytes - - --width - width of the output image, if height is not set will preserve aspect ratio - - --height - height of the output image, if width is not set will preserve aspect ratio - - --long-edge - sets the size of the longest edge of the image - - --short-edge - sets the size of the shortest edge of the image - - -o, --output - output folder - - --same-folder-as-input - sets the output folder to be the same as the input folder, overwrites original files - - --format - convert to the selected output format, or keep the original - - [default: original] - [possible values: jpeg, png, webp, tiff, original] - - --png-opt-level - select level for PNG optimization, between [0-6] - - [default: 3] +v1.0.0-beta.0 - --zopfli - use zopfli when optimizing PNG files (it may take a very long time to complete) +### Development - -e, --exif - keeps EXIF info during compression +#### Requirements - --keep-dates - keep original file date information +* [Rust](https://www.rust-lang.org/tools/install) >= 1.79.0 - --suffix - add a suffix to the output filename +#### Build - -R, --recursive - if input is a folder, scan subfolders too - - -S, --keep-structure - keep the folder structure, can be used only with -R - - -d, --dry-run - do not write output files - - --threads - specify the number of parallel jobs (max is the number of processors available) - - [default: 1] - - -O, --overwrite - overwrite policy - - [default: all] - - Possible values: - - all: Always overwrite - - never: Never overwrite - - bigger: Overwrite only if the file to be overwritten is bigger - - -Q, --quiet - suppress all output - - --verbose - select how much output you want to see - - [default: progress] - - Possible values: - - quiet: Suppress all output - - progress: Show only progress and final results - - warnings-and-errors: Show also skipped and error messages - - all: Print all +`cargo build --release` - -h, --help - Print help (see a summary with '-h') +### Usage - -V, --version - Print version -``` +See full usage docs [here](docs/USAGE.md). ----------- - -###### EX AMPLES +#### Examples Losslessly compress ```image1.jpg```, located in the ```home``` directory, into a folder called ```output``` + ``` $ caesiumclt -q 0 -o ~/output/ ~/image.jpg ``` -Compress ```image1.jpg```, located in the ```home``` directory, into a folder called ```output``` with lossy compression and quality set to 80 +Compress ```image1.jpg```, located in the ```home``` directory, into a folder called ```output``` with lossy compression +and quality set to 80 + ``` $ caesiumclt -q 80 -o ~/output/ ~/image.jpg ``` -Losslessly compress ```image1.jpg```, located in the ```home``` directory, into a folder called ```output``` and keeps EXIF metadata +Losslessly compress ```image1.jpg```, located in the ```home``` directory, into a folder called ```output``` and keeps +EXIF metadata + ``` $ caesiumclt -q 0 -e -o ~/output/ ~/image.jpg ``` -Losslessly compress ```Pictures``` folder and subfolders, located in the ```home``` directory, into a folder called ```output``` +Losslessly compress ```Pictures``` folder and subfolders, located in the ```home``` directory, into a folder called +```output``` + ``` $ caesiumclt -q 0 -R -o ~/output/ ~/Pictures ``` -Losslessly compress ```Pictures``` folder and subfolders, located in the ```home``` directory, into a folder called ```output``` retaining the input folder structure +Losslessly compress ```Pictures``` folder and subfolders, located in the ```home``` directory, into a folder called +```output``` retaining the input folder structure + ``` $ caesiumclt -q 0 -RS -o ~/output/ ~/Pictures ``` diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..db9c537 --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,195 @@ +## CaesiumCLT Usage + +### Options + +##### Compression (at least one is required) + +- -q, --quality + Sets compression quality between 0 and 100. Higher the value, better the quality and bigger the file size. +- --lossless + Perform lossless compression. Some file formats may not support this or result in bigger file sizes. +- --max-size + Attempts to compress the image to the nearest size in bytes without exceeding it. If the requested size is too small, + it will output the smallest possible result. + +##### Advanced compression + +- --png-opt-level + Sets the optimization level for PNG files. Higher values result in better compression but take longer to complete. + Possible values are between 0 and 6. Default is 3. +- --zopfli + Use zopfli when optimizing PNG files. It may take a very long time to complete, especially if the application is not + build in release mode. + +##### Metadata + +- -e, --exif + Keeps EXIF metadata info during compression, if present. This can slightly increase the output file size. +- --keep-dates + Keeps the original last modified and last accessed date information, if possible. + +##### Resizing + +- --width + Sets the width of the output image. If height is not set, it will preserve the aspect ratio. Can't be used with + `--long-edge` or `--short-edge`. +- --height + Sets the height of the output image. If width is not set, it will preserve the aspect ratio. Can't be used with + `--long-edge` or `--short-edge`. +- --long-edge + Sets the size of the longest edge of the image. It is aware of rotation metadata. Can't be used with `--width` or + `--height` or `--short-edge`. +- --short-edge + Sets the size of the shortest edge of the image. It is aware of rotation metadata. Can't be used with `--width` or + `--height` or `--long-edge`. + +##### Destination + +- -o, --output + Sets the output folder. If the folder does not exist, it will be created. Can't be used with `--same-folder-as-input`. +- --same-folder-as-input + Sets the output folder to be the same as the input folder. WARNING: this can potentially overwrite the original files + if a suffix is not set. Overwritten files CANNOT be recovered. +- --suffix + Adds a suffix to the output filename, before the file extension. +- -S, --keep-structure + Preserves the folder tree structure of the input files. Can be used only with `-R`. +- -o, --overwrite + Sets the overwrite policy if the output file already exists. Possible values are: + - `all`: Always overwrite + - `never`: Never overwrite + - `bigger`: Overwrite only if the file to be overwritten is bigger +- --format + Converts the original image to the selected format. Possible values are: + - `jpeg` + - `png` + - `webp` + - `tiff` + - `original` (default, no changes) + +##### Other + +- -R, --recursive + If the input is a folder, scan its subfolders too. +- -d, --dry-run + Do not write output files, only simulate the process. +- --threads + Specify the number of parallel jobs. The maximum is the number of processors available. `0` means that the application + will try to guess the maximum number of parallel jobs available. Default is `0`. +- -Q, --quiet + Suppress all output. Overrides `--verbose`. +- --verbose + Select how much output you want to see. Possible values are: + - `quiet`: Suppress all output + - `progress`: Show only progress and final results + - `warnings-and-errors`: Show also skipped and error messages + - `all`: Print all +- -h, --help + Print help. A summary can be seen with `-h`. +- -V, --version + Print version. + +### Full help + +``` +Usage: caesiumclt [OPTIONS] <--quality |--lossless|--max-size > <--output |--same-folder-as-input> [FILES]... + +Arguments: + [FILES]... + + +Options: + -q, --quality + sets output file quality between [0-100] + + --lossless + perform lossless compression + + --max-size + set the expected maximum output size in bytes + + --width + width of the output image, if height is not set will preserve aspect ratio + + --height + height of the output image, if width is not set will preserve aspect ratio + + --long-edge + sets the size of the longest edge of the image + + --short-edge + sets the size of the shortest edge of the image + + -o, --output + output folder + + --same-folder-as-input + sets the output folder to be the same as the input folder, overwrites original files + + --format + convert to the selected output format, or keep the original + + [default: original] + [possible values: jpeg, png, webp, tiff, original] + + --png-opt-level + select level for PNG optimization, between [0-6] + + [default: 3] + + --zopfli + use zopfli when optimizing PNG files (it may take a very long time to complete) + + -e, --exif + keeps EXIF info during compression + + --keep-dates + keep original file date information + + --suffix + add a suffix to the output filename + + -R, --recursive + if input is a folder, scan subfolders too + + -S, --keep-structure + keep the folder structure, can be used only with -R + + -d, --dry-run + do not write output files + + --threads + specify the number of parallel jobs (max is the number of processors available) + + [default: 0] + + -O, --overwrite + overwrite policy + + [default: all] + + Possible values: + - all: Always overwrite + - never: Never overwrite + - bigger: Overwrite only if the file to be overwritten is bigger + + -Q, --quiet + suppress all output + + --verbose + select how much output you want to see + + [default: progress] + + Possible values: + - quiet: Suppress all output + - progress: Show only progress and final results + - warnings-and-errors: Show also skipped and error messages + - all: Print all + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version +``` \ No newline at end of file diff --git a/rustfmt.toml b/rustfmt.toml index cc66a4b..866c756 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -1,6 +1 @@ -comment_width = 120 -format_code_in_doc_comments = true -imports_granularity = "Crate" -imports_layout = "Vertical" -wrap_comments = true max_width = 120 \ No newline at end of file diff --git a/src/options.rs b/src/options.rs index 1190246..1a27e86 100644 --- a/src/options.rs +++ b/src/options.rs @@ -1,5 +1,5 @@ -use std::path::PathBuf; use clap::{Args, Parser, ValueEnum}; +use std::path::PathBuf; #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum, Debug)] pub enum OverwritePolicy { @@ -8,7 +8,7 @@ pub enum OverwritePolicy { /// Never overwrite Never, /// Overwrite only if the file to be overwritten is bigger - Bigger + Bigger, } #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum, Debug)] @@ -29,7 +29,7 @@ pub enum VerboseLevel { /// Show also skipped and error messages WarningsAndErrors = 2, /// Print all - All = 3 + All = 3, } #[derive(Parser, Debug)] @@ -37,7 +37,7 @@ pub enum VerboseLevel { pub struct CommandLineArgs { #[command(flatten)] pub compression: Compression, - + #[command(flatten)] pub resize: Resize, @@ -47,7 +47,7 @@ pub struct CommandLineArgs { /// convert to the selected output format, or keep the original #[arg(long, value_enum, default_value = "original")] pub format: OutputFormat, - + /// select level for PNG optimization, between [0-6] #[arg(long, default_value = "3")] pub png_opt_level: u8, @@ -55,7 +55,7 @@ pub struct CommandLineArgs { /// use zopfli when optimizing PNG files (it may take a very long time to complete) #[arg(long)] pub zopfli: bool, - + /// keeps EXIF info during compression #[arg(short, long)] pub exif: bool, @@ -81,7 +81,7 @@ pub struct CommandLineArgs { pub dry_run: bool, /// specify the number of parallel jobs (max is the number of processors available) - #[arg(long, default_value = "1")] + #[arg(long, default_value = "0")] pub threads: u32, /// overwrite policy @@ -145,4 +145,4 @@ pub struct OutputDestination { /// sets the output folder to be the same as the input folder, overwrites original files #[arg(long, default_value = "false", group = "output_destination")] pub same_folder_as_input: bool, -} \ No newline at end of file +}