update doc and release 4.1.0
This commit is contained in:
fatalerrors
35
README.md
35
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 <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 |
|
||||
| `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 <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
|
||||
|
||||
@@ -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
|
||||
|
||||
120
doc/FAQ.md
120
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).
|
||||
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`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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]**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user