diff --git a/README.md b/README.md index c5f4a6a..a98c4f1 100644 --- a/README.md +++ b/README.md @@ -10,12 +10,28 @@ current shell is not bash. ## 2. Getting started Download and extract (or use git clone) the profile archive into your home -directory. You will have to modify your `~/.bashrc` and/or `~/.profile` file to -add at the end (preferably): +directory. + +The profile is designed to be **sourced**, not executed directly. + +Manual setup: ```bash source /profile/profile.sh ``` +Automatic setup (recommended): +```bash +bash /profile/profile.sh --install +``` + +`--install` appends the required `source` line to both `~/.bashrc` and +`~/.profile` by default. You can target one file only: + +```bash +bash /profile/profile.sh --install --bashrc +bash /profile/profile.sh --install --profile +``` + You may also set the `PROFILE_PATH` environment variable before sourcing if you want to override the automatic path detection: ```bash @@ -49,10 +65,10 @@ A bar-style prompt showing current time, execution time of the last command | Function | Module | Description | |---|---|---| | `busy` | fun | Monitor /dev/urandom for a hex pattern — look busy | -| `check_updates` | updates | Check whether a newer profile version is available online | +| `check_updates` | updates | Check whether a newer profile version is available online; when called with `-q` at startup a 3-second network timeout is applied so a slow or absent network never delays the prompt | | `clean` | filefct | Erase backup files in given directories, optionally recursive | -| `disp` | disp | Display formatted info / warning / error / debug messages | -| `dwl` | net | Download a URL using curl, wget, or fetch transparently | +| `disp` | disp | Display formatted info / warning / error / debug messages; long messages are word-wrapped and continuation lines are indented to align with the message text | +| `dwl` | net | Download a URL using curl, wget, or fetch transparently; supports `-t ` / `--timeout ` to cap the transfer time | | `expandlist` | filefct | Expand glob expressions into a quoted, separated list | | `file_stats` | filefct | Display file size statistics for a path | | `findbig` | filefct | Find the biggest files in the given or current directory | @@ -68,7 +84,7 @@ A bar-style prompt showing current time, execution time of the last command | `gsync` | git | Fetch and rebase the current branch onto its upstream | | `gst` | git | Display compact git status with branch tracking information | | `gwip` | git | Create a quick WIP checkpoint commit | -| `help` | help | Display the list of available functions and basic usage | +| `help` | help | Display the list of available functions and basic usage; `help ` delegates to ` --help` | | `isipv4` | net | Tell if the given parameter is a valid IPv4 address | | `isipv6` | net | Tell if the given parameter is a valid IPv6 address | | `ku` | processes | Kill all processes owned by the given user name or ID | @@ -99,6 +115,13 @@ A bar-style prompt showing current time, execution time of the last command Locale shortcut functions (`setfr`, `setus`, etc.) are dynamically generated at startup from the `SET_LOCALE` configuration key (see section 4). +### 3.3. Bash completion + +profile loads all `*.sh` files found under `profile.d/bash-completion/` +automatically in interactive sessions. This directory is the right place to add +any custom completion definitions. profile already ships completions for its git +helper functions there (`git-completion.sh`). + ## 4. Configuration profile uses an INI-style configuration file (`profile.conf`) located in the same directory as `profile.sh`. Sections are declared with `[section_name]` and diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md index 2096555..451c9e1 100755 --- a/doc/CHANGELOG.md +++ b/doc/CHANGELOG.md @@ -7,6 +7,31 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`). --- +## [4.1.0] — 2026-05-07 + +### Added +- `profile.sh --install` command to automatically configure profile loading in + shell startup files. +- `--install --bashrc` and `--install --profile` target selectors for + single-file installation. +- **`git.sh`** — entirely new module providing git workflow helpers: `gst`, + `ggraph`, `gsync`, `gacp`, `greset`, `gwip`, `gprune`, `groot`. +- Dedicated git helper completions under `profile.d/bash-completion/`, loaded + automatically in interactive sessions from `profile.d/bash-completion/*.sh`. + +### Changed +- `disp` now wraps long messages on terminal width, avoids mid-word splits, and + aligns continuation lines with the message body after the prefix. +- `help` now supports `help ` and delegates to ` --help`. + +### Fixed +- Startup responsiveness improved: `check_updates -q` now uses a short network + timeout so unavailable/slow networks no longer delay prompt readiness. +- `dwl` gained timeout support (`-t` / `--timeout`) and is now used by quiet + startup update checks to enforce fast failure. +- `profile.sh` now detects direct execution and warns that it is designed to be + sourced. + ## [4.0.0] — 2026-04-23 ### Added diff --git a/doc/FAQ.md b/doc/FAQ.md index 4f81cf9..c556c34 100755 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -4,6 +4,33 @@ ## Installation & loading +**Q: How do I install profile automatically into my shell startup files?** + +Run the installer directly (no need to source first): +```bash +bash /profile/profile.sh --install +``` +This appends the required `source` line to both `~/.bashrc` and `~/.profile`. +To target only one file: +```bash +bash /profile/profile.sh --install --bashrc +bash /profile/profile.sh --install --profile +``` +The operation is idempotent — running it again will not add a duplicate line. + +--- + +**Q: I ran `profile.sh` directly and got a warning about sourcing.** + +profile.sh is designed to be *sourced*, not executed: +```bash +source /profile/profile.sh +``` +The only exception is `--install`, which must be passed to a direct execution +(`bash profile.sh --install`) to set up the sourcing line automatically. + +--- + **Q: profile refuses to load and prints "This profile requires Bash 4.3 or higher."** Your system's default shell is an older Bash (common on macOS, which ships @@ -84,7 +111,8 @@ Add to `profile.conf`: PROMPT_THEME = dark ``` Built-in names: `default`, `dark`, `light`, `solarized`, `solarized-light`, -`monokai`, `monochrome`, `abyss`, `plasma`, `adwaita`. +`monokai`, `monochrome`, `abyss`, `plasma`, `adwaita`, but you can create your +own theme. --- @@ -119,6 +147,55 @@ theme file cannot execute code. Values must be a colour variable reference --- +## Git helpers + +**Q: What git helper functions does profile provide?** + +All git helpers are defined in `profile.d/git.sh` (new in 4.1.0): + +| Command | Purpose | +|---|---| +| `gst` | Compact status with branch tracking info | +| `ggraph` | Decorated history graph | +| `gsync` | Fetch and rebase onto upstream | +| `gacp` | Add, commit and push in one command | +| `greset` | Reset to upstream, stashing local changes first | +| `gwip` | Quick WIP checkpoint commit | +| `gprune` | Delete merged local branches | +| `groot` | Print or cd to repository root | + +All commands accept `-h` / `--help`. + +--- + +**Q: Tab completion for `gacp` does not show modified files.** + +Profile ships dedicated completions in `profile.d/bash-completion/git-completion.sh`, +loaded automatically in interactive sessions. If completions are missing, +check that the system git completion is installed: +```bash +# Debian / Ubuntu +apt-get install bash-completion +# Fedora / RHEL +dnf install bash-completion +``` +When the native git completion helpers are available, `gacp` path completion +behaves exactly like `git add` (modified files, untracked files, directories). + +--- + +**Q: `gacp` says "No files specified" even though I passed `-a`.** + +The `-a` / `--auto` flag adds all modified files (equivalent to `git add -A`). +The default depends on `GIT_GACP_AUTO_ADD` in `profile.conf`: +```ini +[git] +GIT_GACP_AUTO_ADD = 1 +``` +Set to `1` to make `-a` the default. + +--- + ## Functions **Q: `meteo` prints "No city specified" even though I set a default.** @@ -147,11 +224,46 @@ Or set `DWL_PREFERRED_TOOL` in `[net]` to whichever tool you have. --- +**Q: How do I limit how long `dwl` waits for a download?** + +Use the `-t` / `--timeout` option: +```bash +dwl -t 5 https://example.com/file.txt /tmp/file.txt +``` +This sets a 5-second cap on both the connection and the overall transfer. +The timeout is propagated to `curl` (`--max-time` + `--connect-timeout`), +`wget` (`--timeout`), or `fetch` (`-T`) transparently. + +--- + +**Q: The prompt takes a long time to appear when my network is unavailable.** + +Fixed in 4.1.0. `check_updates -q` (called at startup) now enforces a +3-second network timeout. If the update server is unreachable the check +fails silently and the prompt appears immediately. + +--- + +**Q: `help` only shows a list of functions. Can I get usage for a specific one?** + +Yes — pass the command name as an argument: +```bash +help gacp +help dwl +help taz +``` +This calls ` --help` and prints the full usage for that function. + +--- + **Q: `pkgs` does not find packages I know are installed.** -`pkgs` delegates to `dpkg -l` (Debian/Ubuntu) or `rpm -qa` (RHEL/Fedora). -If your distribution uses a different package manager (pacman, apk, brew …) -it is not yet supported. See `doc/todo.md` for the tracking issue. +`pkgs` uses `get_pkgmgr` to detect the active package manager and delegates +to the appropriate tool. Supported families: `apt` (Debian/Ubuntu), +`dnf` / `yum` (RHEL/Fedora), `zypper` (openSUSE), `pacman` (Arch), +`apk` (Alpine), `portage` (Gentoo), `xbps` (Void), `nix`, `brew` (macOS). +If your distribution is not detected, run `get_pkgmgr` to see what is +identified, and check that the package manager binary is in your `PATH`. --- diff --git a/doc/todo.md b/doc/todo.md index f7b273b..1e88d27 100755 --- a/doc/todo.md +++ b/doc/todo.md @@ -12,7 +12,7 @@ version-bump. blockers are `local -A` (no associative arrays in ZSH without `typeset -A`) and `local -n` namerefs. A thin compatibility shim would open the project to ZSH users. **[hard]** -- [ ] **Bash completion** — add a `profile.d/completion/` directory and write +- [ ] **Bash completion** — add a more bash completion directory and write `_profile_upgrade`, `_taz`, `_utaz`, `_meteo`, etc. completions so that `` works on all public functions. **[medium]**