update doc and release 4.1.0

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
+directory.
-add at the end (preferably):
+
+The profile is designed to be **sourced**, not executed directly.
+
+Manual setup:
 ```bash
 source <installpath>/profile/profile.sh
 ```
 
+Automatic setup (recommended):
+```bash
+bash <installpath>/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 <installpath>/profile/profile.sh --install --bashrc
+bash <installpath>/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 |
+| `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 |
+| `dwl` | net | Download a URL using curl, wget, or fetch transparently; supports `-t <seconds>` / `--timeout <seconds>` 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 <command>` delegates to `<command> --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

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 <command>` and delegates to `<command> --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

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 <installpath>/profile/profile.sh --install
+```
+This appends the required `source` line to both `~/.bashrc` and `~/.profile`.
+To target only one file:
+```bash
+bash <installpath>/profile/profile.sh --install --bashrc
+bash <installpath>/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 <installpath>/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 `<command> --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).
+`pkgs` uses `get_pkgmgr` to detect the active package manager and delegates
-If your distribution uses a different package manager (pacman, apk, brew …)
+to the appropriate tool. Supported families: `apt` (Debian/Ubuntu),
-it is not yet supported. See `doc/todo.md` for the tracking issue.
+`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`.
 
 ---
 

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
   `<Tab>` works on all public functions. **[medium]**