update doc and release 4.1.0
This commit is contained in:
fatalerrors
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`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user