From 1c68ddf372f907a9b0102bfeffe36511fc5d69ef Mon Sep 17 00:00:00 2001 From: Vincent de Phily Date: Sat, 4 Nov 2023 11:01:09 +0000 Subject: [PATCH] docs: Update changelog, readme, comparison, contribution --- CHANGELOG.md | 8 +++- README.md | 93 +++++++++++++++++++++++--------------------- docs/COMPARISON.md | 3 +- docs/CONTRIBUTING.md | 40 ++++++++----------- 4 files changed, 74 insertions(+), 70 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f4e0ddc..065b097 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,13 @@ * Improve predict's `tmpdir`: - Autodetect `tmpdir` using currently running emerge processes - Support multiple `--tmpdir` arguments -* Passing `--resume` without argument is now the same as `--resume main` +* Improve output selection: + - `--tabs` has been renamed `--output=tab/cols` (or `-ot` for short) + - Default output is now `cols` on tty and `tab` otherwise, to simplify `emlop ...|cut -f...` workflow +* Improve resume list selection: + - Added `--resume=any` variant to resume either main or backup list + - Passing `--resume` without argument is now the same as `--resume any` +* Remove `--resume=auto` and `--color=auto` variants (just don't pass the option) * Upgraded clap dependency - Inline help styling/content changed a bit diff --git a/README.md b/README.md index 13ab2eb..d61fd7c 100644 --- a/README.md +++ b/README.md @@ -10,41 +10,46 @@ ergonomic, see [comparison](docs/COMPARISON.md). ## Usage -Emlop is split into commands. Command names and arguments can be abbreviated, and shell completion is available. See `emlop --help` and `emlop --help` -for complete and up to date usage info. +Emlop is split into commands. Command names and arguments can be abbreviated, and shell completion +is available. See `emlop --help` and `emlop --help` for complete and up to date usage +info. ### Common options All commands share these arguments, affecting parsing and output: - OPTIONS: - -F, --logfile Location of emerge log file. [default: /var/log/emerge.log] - -v Increase verbosity (can be given multiple times). - -h, --help Show short (-h) or detailed (--help) help. - FILTER: - -f, --from Only parse log entries after . - -t, --to Only parse log entries before . - FORMAT: - -H, --header Show table header - --utc Parse/display dates in UTC instead of local time - --tabs Separate columns using tabs instead of spaces - --duration Output durations in different formats. [default: hms] - --date Output dates in different formats. [default: ymdhms] - --color Enable color (auto/always/never/y/n). [default: auto] - - -### List merges, unmerges, and rsyncs with `log` + Options: + -F, --logfile Location of emerge log file [default: /var/log/emerge.log] + -v... Increase verbosity (can be given multiple times) + -h, --help Print help (see more with '--help') + -V, --version Print version + Filter: + -f, --from Only parse log entries after + -t, --to Only parse log entries before + Format: + -H, --header Show table header + --utc Parse/display dates in UTC instead of local time + -o, --output Ouput format (cols/c/tab/t) + --duration Output durations in different formats [default: hms] + --date Output dates in different formats [default: ymdhms] + --color [] Enable color (always/never/y/n) + + +### List merges, unmerges, and syncs with `log` ![Log demo](log.webp) Log-specific options: - FILTER: - Show only packages matching . - -e, --exact Match package with a string instead of a regex. - -s, --show Show (m)erges, (u)nmerges, (s)yncs, and/or (a)ll. [default: m] - -N, --first Show only the first entries. - -n, --last Show only the last entries. + Filter: + [search]... Show only packages/repos matching + -e, --exact Match using plain string + -s, --show Show (m)erges, (u)nmerges, (s)yncs, and/or (a)ll [default: m] + -N, --first [] Show only the first entries + -n, --last [] Show only the last entries + +Note that `emaint sync` currently [doesn't write to emerge.log](https://bugs.gentoo.org/553788), so +`emlop l --show s` will appear empty if you use `emaint`. Use `emerge --sync` or `eix-sync` instead. ### Estimate how long a merge with take with `predict` @@ -52,18 +57,16 @@ Log-specific options: Predict-specific arguments: - OPTIONS: - --tmpdir Location of portage tmpdir. [default: /var/tmp] - --resume Use auto, main, backup, or no portage resume list [default: auto] - FILTER: - -s, --show Show (e)emerge processes, (m)erges, (t)otal, and/or (a)ll. [default: - emt] - -N, --first Show only the first entries. - -n, --last Show only the last entries. - STATS: - --limit Use the last merge times to predict durations. [default: 10] - --avg Select function used to predict durations. [default: median] - + Options: + --tmpdir Location of portage tmpdir [default: /var/tmp] + --resume [] Use main, backup, any, or no portage resume list + Filter: + -s, --show Show (e)emerge processes, (m)erges, (t)otal, and/or (a)ll [default: emt] + -N, --first [] Show only the first entries + -n, --last [] Show only the last entries + Stats: + --limit Use the last merge times to predict durations [default: 10] + --avg Select function used to predict durations [default: median] ### Show aggregated statistics with `stats` @@ -71,14 +74,14 @@ Predict-specific arguments: Stats-specific arguments: - FILTER: - Show only packages matching . - -e, --exact Match package with a string instead of a regex. - -s, --show Show (p)ackages, (t)otals, (s)yncs, and/or (a)ll. [default: p] - STATS: - -g, --groupby Group by (y)ear, (m)onth, (w)eek, or (d)ay. - --limit Use the last merge times to predict durations. [default: 10] - --avg Select function used to predict durations. [default: median] + Filter: + [search]... Show only packages/repos matching + -e, --exact Match using plain string + -s, --show Show (p)ackages, (t)otals, (s)yncs, and/or (a)ll [default: p] + Stats: + -g, --groupby Group by (y)ear, (m)onth, (w)eek, or (d)ay + --limit Use the last merge times to predict durations [default: 10] + --avg Select function used to predict durations [default: median] ### Other commands diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md index ebf12ed..ff90710 100644 --- a/docs/COMPARISON.md +++ b/docs/COMPARISON.md @@ -113,7 +113,8 @@ piping `emerge -rOp` would do). Genlop has multiple estimation bugs where data get mixed up (different categories, parallel merges, etc). `Genlop -p` doesn't take current elapsed emerge time into account. When run as a normal user, qlop warns about missing /proc permissions, finds bogus current merges, and doesn't give the same -ETA for the ones it finds. +ETA for the ones it finds. The linuxhowtos db is unmaintained and unlikely to contain info for your +CPU and ebuilds. All tools give pessimistic prediction when packages are merged in parallel, because they assume sequential merging. Even if they detected an ongoing parallel merge, it's not clear how they would diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7e250d0..d8999b9 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -5,41 +5,35 @@ Thank you for taking the time to contribute. Follow the [Rust](https://www.rust-lang.org/en-US/conduct.html) and [Gentoo](https://wiki.gentoo.org/wiki/Project:Council/Code_of_conduct) codes of conduct. -## Reporting bugs and feature requests +## Reporting bugs or feature requests -Please create issues via [Github](https://github.com/vincentdephily/emlop/issues). You might want to -peek at the [roadmap](ROADMAP.md) for inspiration. +Please create issues via [Github](https://github.com/vincentdephily/emlop/issues). Check existing +issues, and make sure you're running the latest version. -## Submitting patches +## Sending patches -Send pull requests to [Github](https://github.com/vincentdephily/emlop). +Emlop is licensed as GPLv3, any contribution accepted into the emlop repo will have that license. +Send pull requests via [Github](https://github.com/vincentdephily/emlop). -Make sure to `cargo test -- --include-ignored` before submitting your code. A bugfix should probably -include an updated unittest. Check `cargo clippy` hints. Format code using `cargo +nightly fmt`. +Run `cargo test -- --include-ignored` before submitting your code. A bugfix should probably +include a new/updated unittest. Check `cargo clippy` hints. Format code using `cargo +nightly fmt`. The +github CI also runs these checks. -Test emlop with the latest rust stable versions from both Gentoo and upstream. Using `rustup` is -highly recomended. +Test emlop with the latest rust stable versions from both Gentoo and upstream, and the oldest +version from Gentoo. Using `rustup` is highly recomended. -Speed is important, check for improvements/regressions using `benches/exec_compare.rs` (you need to -`cargo install scriptisto` to be able to run this file). - -Respect [semver](https://semver.org/). - -## Status on other environements +Check for performance improvements/regressions using `benches/exec_compare.rs` (you need to +`cargo install scriptisto` to be able to run this file) and `cargo +nightly bench -F unstable bench` +(you need a nightly toolchain installed). I only have access to amd64/linux/gentoo/portage environements. Reports about running emlop on arm/freebsd/funtoo/paludis/etc would be appreciated. -## License - -Emlop is licensed as GPLv3. Any contribution accepted into the emlop repo will have that license, -unless the contributor explicitly demands otherwise. - ## Release checklist * Update deps: `cargo outdated`, edit Cargo.toml, `cargo update`. -* Check `git status` and either `commit` or `stash`. -* Test: `rustup override set 1.65.0 && cargo test -- --include-ignored && rustup override unset && cargo test -- --include-ignored`. +* Check `git status` and either `commit+push` or `stash`. +* Check github CI status. * Update/commit CHANGELOG.md, Cargo.toml, Cargo.lock. * `git tag -a` (copy the changelog entry into the tag). * `git push --tags`. @@ -49,4 +43,4 @@ unless the contributor explicitly demands otherwise. - Check against main repo ebuild - Check tests and useflag variations * Publish to [crates.io](https://crates.io/). -* Send a [bump request](https://bugs.gentoo.org/). +* Send a [pull request](https://github.com/gentoo/gentoo/pulls).