Update Readme and instruction
This commit is contained in:
Rafał Mikrut
parent
083db7aa51
commit
cab191466e
56
README.md
56
README.md
|
|
@ -13,7 +13,7 @@
|
|||
- Rich search option - allows setting absolute included and excluded directories, set of allowed file extensions or excluded items with * wildcard
|
||||
- Image previews to get quick view at the compared photos
|
||||
- Multiple tools to use:
|
||||
- Duplicates - Finds duplicates basing on size(fast), hash(accurate), first 1MB of hash(moderate)
|
||||
- Duplicates - Finds duplicates basing on file name, size, hash, first 1 MB of hash
|
||||
- Empty Folders - Finds empty folders with the help of advanced algorithm
|
||||
- Big Files - Finds provided number of the biggest files in given location
|
||||
- Empty Files - Looks for empty files across disk
|
||||
|
|
@ -24,18 +24,28 @@
|
|||
- Invalid Symbolic Links - Shows symbolic links which points to non-existent files/directories
|
||||
|
||||
|
||||
|
||||
## Instruction
|
||||
You can find instruction how to use Czkawka [here](instructions/Instruction.md)
|
||||
|
||||
## Requirements
|
||||
If you are using Windows or Mac binaries, there is no specific requirements.
|
||||
Same with Appimage on Linux(except having system 18.04+ or similar).
|
||||
But compiled GUI binaries on Linux or compiling it on your own os require to install this packages:
|
||||
### Ubuntu/Debian
|
||||
```
|
||||
sudo apt install cargo libgtk-dev
|
||||
sudo apt install cargo libgtk-3-dev
|
||||
```
|
||||
### Fedora/CentOS
|
||||
```
|
||||
sudo yum install cargo gtk3-devel glib2-devel
|
||||
sudo yum install gtk3-devel glib2-devel
|
||||
```
|
||||
### Windows(Not working yet)
|
||||
First you need to install Visual C++ components from Visual Studio installer - https://visualstudio.microsoft.com/downloads/
|
||||
|
||||
Next install Rust from site https://rustup.rs/
|
||||
|
||||
After that the latest GTK 3 runtime must be installed from https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
|
||||
|
||||
## Usage
|
||||
### Precompiled binaries
|
||||
|
|
@ -45,10 +55,10 @@ If the app does not run when clicking at a launcher, run it through a terminal.
|
|||
### Appimage
|
||||
Appimage files are available in release page - https://github.com/qarmin/czkawka/releases/
|
||||
|
||||
For now looks that there is a bug with this format, because it doesn't allow to open two images/files at once.
|
||||
For now looks that there is a bug with this format, because it doesn't allow opening two images/files at once.
|
||||
|
||||
### Cargo
|
||||
The easiest method to install Czkawka is to use Cargo command(you must have installed GTK libraries in OS)
|
||||
The easiest method to install Czkawka is to use Cargo command, since it basically compile an entire app, you need to install required packages from `Compilation` section
|
||||
```
|
||||
cargo install czkawka_gui
|
||||
cargo install czkawka_cli
|
||||
|
|
@ -56,10 +66,13 @@ cargo install czkawka_cli
|
|||
You can update package by typing same command.
|
||||
|
||||
### Snap
|
||||
Snap also are available, but there is no access to
|
||||
Snap also are available, but there is no access to external drives.
|
||||
```
|
||||
sudo snap install czkawka
|
||||
```
|
||||
Snap store entry - https://snapcraft.io/czkawka
|
||||
|
||||
Edgy builds are build for every commit, but it may be a little unstable(very rarely, because I'm not pushing untested code).
|
||||
|
||||
### Flatpak
|
||||
Maybe someday
|
||||
|
|
@ -84,15 +97,20 @@ Artifacts from each commit you can also download here - https://github.com/qarmi
|
|||
|
||||
## Compilation
|
||||
### Requirements
|
||||
Rust 1.46 - probably lower also works fine(1.40 is needed by GTK)
|
||||
GTK 3.22 - for GTK backend
|
||||
Rust 1.48 - Czkawka aims to support only the latest stable Rust version
|
||||
GTK 3.22 - only for GTK backend
|
||||
|
||||
|
||||
For now only Linux (and maybe also macOS) is supported
|
||||
|
||||
- Install requirements for GTK
|
||||
If you want to compile CLI frontend, then just skip lines which contains `gtk` word.
|
||||
#### Debian/Ubuntu
|
||||
```shell
|
||||
sudo apt install -y curl # Needed by Rust update tool
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Download the latest stable Rust
|
||||
sudo apt install -y libgtk-3-dev
|
||||
```
|
||||
apt install -y libgtk-3-dev
|
||||
#### Fedora/CentOS/Rocky Linux
|
||||
```shell
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Download the latest stable Rust
|
||||
sudo yum install gtk3-devel glib2-devel
|
||||
```
|
||||
|
||||
### Compilation from source
|
||||
|
|
@ -106,7 +124,7 @@ cd czkawka
|
|||
cargo run --bin czkawka_gui
|
||||
```
|
||||
For Linux-to-Windows cross-building instruction look at the CI.
|
||||
|
||||
|
||||
- Run CLI(this will print help with a lot of examples)
|
||||
```
|
||||
cargo run --bin czkawka_cli
|
||||
|
|
@ -116,7 +134,7 @@ cargo run --bin czkawka_cli
|
|||
## Benchmarks
|
||||
Since Czkawka is written in Rust and aims to be a faster alternative to FSlint (written in Python), we need to compare the speed of these tools.
|
||||
|
||||
I tested it on SSD Disk 256GB GoodRam and i7 4770 CPU.
|
||||
I tested it on SSD Disk 256 GB GoodRam and i7 4770 CPU.
|
||||
|
||||
I prepared a directory and performed a test without any folder exceptions(I removed all directories from FSlint and Czkawka from other tabs than Include Directory) which contained 229868 files which took 203,7 GB and 13708 duplicates files in 9117 groups which took 7.90 GB.
|
||||
|
||||
|
|
@ -138,14 +156,14 @@ To not get Dupeguru crash I checked smaller directory with 217986 files and 4188
|
|||
| Czkawka 1.4.0 | 9 MB | 66 MB | 32 MB |
|
||||
| DupeGuru 4.0.4 | 80 MB | 210 MB | 155 MB |
|
||||
|
||||
Similar Images which check 332 files which takes 1,7GB
|
||||
Similar Images which check 332 files which takes 1,7 GB
|
||||
|
||||
| App| Scan time |
|
||||
|:----------:|:-------------:|
|
||||
| Czkawka 1.4.0 | 58s |
|
||||
| DupeGuru 4.0.4 | 51s |
|
||||
|
||||
Similar Images which check 1421 image files which takes 110,1MB
|
||||
Similar Images which check 1421 image files which takes 110,1 MB
|
||||
|
||||
| App| Scan time |
|
||||
|:----------:|:-------------:|
|
||||
|
|
@ -187,14 +205,14 @@ You can help by creating:
|
|||
- Bug report - memory leaks, unexpected behavior, crashes
|
||||
- Feature proposals - proposal to change/add/delete some features
|
||||
- Pull Requests - implementing a new feature yourself or fixing bugs, but you have to pay attention to code quality. If the change is bigger, then it's a good idea to open a new issue to discuss changes.
|
||||
- Documentation - There is [insruction](instructions/Instruction.md) which you can improve.
|
||||
- Documentation - There is [instruction](instructions/Instruction.md) which you can improve.
|
||||
|
||||
The code should be clean and well formatted (Clippy and fmt are required in each PR).
|
||||
|
||||
## Name
|
||||
Czkawka is a Polish word which means _hiccup_.
|
||||
|
||||
I chose this name because I wanted to hear people speaking other languages pronounce it.
|
||||
I chose this name because I wanted to hear people speaking other languages pronounce it.
|
||||
|
||||
This name is not as bad as it seems, because I was also thinking about using words like _żółć_, _gżegżółka_ or _żołądź_, but I gave up on these ideas because they contained Polish characters, which would cause difficulty in searching for the project.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,12 @@
|
|||
# Instruction
|
||||
|
||||
- [Basic information](#basic-informations)
|
||||
- [Tools - How works?](#tools---how-works)
|
||||
- [Config/Cache files](#configcache-files)
|
||||
- [GUI](#gui-gtk)
|
||||
- [CLI](#cli)
|
||||
- [Tips and tricks](#tips-and-tricks)
|
||||
|
||||
## Basic Informations
|
||||
Czkawka for now contains two independent frontends - Console and Graphical interface which share the core module which contains basic and common functions used by each frontend.
|
||||
|
||||
|
|
@ -6,18 +14,18 @@ Using Rust language without unsafe code, helps to create safe, fast with small r
|
|||
|
||||
The code has very good support for multithreading, so the better processor/disk the performance should increase exponentially.
|
||||
|
||||
## Tools
|
||||
## Tools - How works?
|
||||
### Duplicate Finder
|
||||
|
||||
Duplicate Finder allows you to search for files and group them according to a predefined criterion:
|
||||
- **By name** - Groups files by name e.g. `/home/rafal/plik.txt` will be treat like duplicate of file `/home/romb/plik.txt`. This is the fastest method, but it is very unreliable and should not be used unless you know what you are doing.
|
||||
- **By size** - Groups files by its size(in bytes), which must be exactly the same. It is as fast as the previous mode and usually gives much more correct results with duplicates, but I also do not recommend using it if you do not know what you are doing.
|
||||
- **By hash** - A mode containing a check of the hash (cryptographic hash) of a given file which determines with great probability whether the files are identical.
|
||||
|
||||
|
||||
This is the slowest, but almost 100% sure way to check the files.
|
||||
|
||||
|
||||
Because the hash is only checked inside groups of files of the same size, it is practically impossible for two different files to be considered identical.
|
||||
|
||||
|
||||
It consists of 3 parts:
|
||||
- Grouping files of identical size - allows you to throw away files of unique size, which are already known to have no duplicates at this stage.
|
||||
- PreHash check - Each group of files of identical size is placed in a queue using all processor threads (each action in the group is independent of the others).
|
||||
|
|
@ -119,7 +127,7 @@ Finally, each hash is compared with the others and if the distance between them
|
|||
## Config/Cache files
|
||||
For now Czkawka store only 2 files on disk:
|
||||
- `czkawka_gui_config.txt` - stores configuration of GUI which may be loaded at startup
|
||||
- `cache_similar_image.txt` - stores cache data and hashes which may be used later without needing to compute image hash again
|
||||
- `cache_similar_image.txt` - stores cache data and hashes which may be used later without needing to compute image hash again - DO NOT TRY TO EDIT THIS FILE MANUALLY! - editing this file may cause app crashes.
|
||||
|
||||
|
||||
This files are located in this path
|
||||
|
|
@ -127,9 +135,12 @@ This files are located in this path
|
|||
Linux - `/home/username/.config/czkawka`
|
||||
Mac - `/Users/username/Library/Application Support/pl.Qarmin.Czkawka`
|
||||
Windows - `C:\Users\Alice\AppData\Roaming\Qarmin\Czkawka\config`
|
||||
|
||||
|
||||
## GUI GTK
|
||||
<img src="https://user-images.githubusercontent.com/41945903/103002387-14d1b800-452f-11eb-967e-9d5905dd6db5.png" width="800" />
|
||||
|
||||
### GUI overview
|
||||
The GUI are built from different pieces:
|
||||
- Red - Program settings, contains info about included/excluded directories which user may want to check. Also there is a tab with allowed extensions, which allow user to choose which type of files want to check. Next category is Excluded items, which allow to discard specific path with use of `*` wildcard - `/home/*` means that e.g. `/home/rafal/` will be ignored but no `/home/czkawka/`. The last one is settings tab which allow to save configuration of program, reset it and load it when needed.
|
||||
- Green - This allow to choose which tool we want to use.
|
||||
|
|
@ -143,6 +154,21 @@ There is also an option to see image previews in Similar Images tool.
|
|||
|
||||
<img src="https://user-images.githubusercontent.com/41945903/103025544-50ca4480-4552-11eb-9a54-f1b1f6f725b1.png" width="800" />
|
||||
|
||||
### Action Buttons
|
||||
There are several buttons which do different actions:
|
||||
- Search - starts searching and shows progress dialog
|
||||
- Stop - button in progress dialog, allows to easily stop current task. Sometimes it may take a few seconds until all atomic operations ends and GUI will be able to use again
|
||||
- Select - allows selecting multiple entries at once
|
||||
- Delete - delete entirely all selected entries
|
||||
- Save - save initial state of results
|
||||
- Hamburger(parallel lines) - used to show/hide bottom text panel which shows warnings/errors
|
||||
- Add (directories) - adds directories to include or exclude
|
||||
- Remove (directories) - remove directories to search or to exclude
|
||||
- Manual Add (directories) - allows to write by hand directories(may be used to write non visible in file manager directories)
|
||||
- Save current configuration - saves current GUI configuration to configuration file
|
||||
- Load configuration - loads configuration of file and override current GUI config
|
||||
- Reset configuration - reset current GUI configuration to default
|
||||
|
||||
### Opening/Manipulating files
|
||||
It is possible to open selected files by double clicking at them.
|
||||
|
||||
|
|
@ -150,6 +176,7 @@ To open multiple file just select desired files with CTRL key pressed and still
|
|||
|
||||
To open folder containing selected file, just click twice at it with right mouse button.
|
||||
|
||||
|
||||
## CLI
|
||||
Czkawka CLI frontend is great to automate some tasks like removing empty directories.
|
||||
|
||||
|
|
@ -165,4 +192,8 @@ If you want to get more detailed info about certain tool, after its name just wr
|
|||
|
||||
By default all tools only write about results to console, but it is possible with specific arguments to delete some files/arguments or save it to file.
|
||||
|
||||
|
||||
## Tips and Tricks
|
||||
- **Manually adding multiple directories**
|
||||
You can manually edit config file `czkawka_gui_config.txt` and add required directories. After that load configuration.
|
||||
- **Slow checking of little number similar images**
|
||||
If you checked before a big amount of images(several tens of thousands) and them still exists on disk, then information's about it are loaded from cache and save to it, even if you have check now only a few images. You can rename cache file `cache_similar_image.txt`(to be able to use it again) or delete it - cache will regenerate but with lower amount of entries it should load and save a lot of faster.
|
||||
Loading…
Reference in a new issue