### Install Topgrade with Pacstall

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install the topgrade-bin package on Ubuntu using Pacstall. This command uses a pacscript to install the binary.

```bash
pacstall -I topgrade-bin
```

--------------------------------

### Install Topgrade with Scoop

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade on Windows using the Scoop package manager. This command adds the main bucket and then installs topgrade.

```bash
scoop bucket add main && scoop install main/topgrade
```

--------------------------------

### Install Topgrade with xbps

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade on Void Linux using the xbps package manager. This command installs the topgrade package.

```bash
sudo xbps-install -S topgrade
```

--------------------------------

### Install Topgrade with Winget

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade on Windows using the Windows Package Manager (winget). This command installs the topgrade-rs.topgrade package.

```bash
winget install --id=topgrade-rs.topgrade  -e
```

--------------------------------

### Install Topgrade via PyPI

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Installs Topgrade on any platform using pipx, which provides isolated Python environments. This is a convenient way to install Python-based tools.

```bash
pipx install topgrade
```

--------------------------------

### Install Topgrade via Winget (Windows)

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Installs Topgrade on Windows using the Windows Package Manager (winget). The `-e` flag ensures exact matching.

```powershell
winget install --id=topgrade-rs.topgrade -e
```

--------------------------------

### Install Topgrade with Cargo

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade from source using Cargo, Rust's package manager. Ensure you have Rust and Cargo installed.

```bash
cargo install topgrade
```

--------------------------------

### Install Topgrade with Nix

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade on NixOS or Nix environments. This command refers to the package available in nixpkgs.

```bash
topgrade
```

--------------------------------

### Zigup Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Zigup installation directory, path link, and cleanup behavior.

```toml
[zigup]
target_versions = ["master", "0.13.0"]
install_dir = "~/.zig"
path_link = "~/.bin/zig"
cleanup = false

```

--------------------------------

### Install Topgrade with Chocolatey

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade on Windows using the Chocolatey package manager. This command installs the topgrade package from the community repository.

```bash
choco install topgrade
```

--------------------------------

### Install Topgrade via AUR (Arch Linux)

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Installs Topgrade on Arch Linux using an AUR helper like `yay`. Choose `topgrade` for the latest version or `topgrade-bin` for a pre-compiled binary.

```bash
yay -S topgrade        # or topgrade-bin
```

--------------------------------

### Install Topgrade with pip/pipx/uv

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade using Python's package managers like pip, pipx, or uv tool. This is useful for Python environments.

```bash
install topgrade
```

--------------------------------

### Install Topgrade with deb-get

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade on Debian/Ubuntu systems using the deb-get package manager. This command fetches and installs the topgrade package.

```bash
deb-get install topgrade
```

--------------------------------

### Install Topgrade with MacPorts

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade on macOS using the MacPorts package manager. This command installs the topgrade port.

```bash
sudo port install topgrade
```

--------------------------------

### Install Topgrade with Copr

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Enable the Topgrade Copr repository and install topgrade on Fedora/RHEL/AlmaLinux/CentOS-Stream systems. This command adds the repository and then installs the package.

```bash
sudo dnf copr enable lilay/topgrade && sudo dnf install topgrade
```

--------------------------------

### Define first and last steps in Topgrade config

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify steps that should always run first or last, overriding the default ordering. This allows for critical setup or cleanup tasks.

```toml
first = ["chezmoi", "rustup"]
last = ["system", "custom_commands"]
```

--------------------------------

### Install Topgrade with apk

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade on Alpine Linux using the apk package manager. This command installs the topgrade package from the community repository.

```bash
sudo apk add topgrade
```

--------------------------------

### Install Topgrade with Homebrew

Source: https://github.com/topgrade-rs/topgrade/blob/main/README.md

Install Topgrade on macOS or Linux using Homebrew. This command adds topgrade to your system's package management.

```bash
brew install topgrade
```

--------------------------------

### Deno Version Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify the Deno version to install or update to.

```toml
[deno]
version = "stable"

```

--------------------------------

### Configure Cargo and Rustup Updates

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Enable updates for Git-sourced Cargo installs and specify Rustup channels to update. Options for passing arguments to cargo install.

```toml
[cargo]
git = true      # Also update git-sourced cargo installs
quiet = false

[rustup]
channels = ["stable", "nightly"]   # empty = update all installed channels
```

--------------------------------

### Pass Options to Cargo Install via Environment

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Set environment variables to pass custom options to `cargo install` commands executed by Topgrade.

```bash
# Pass extra options to cargo install via environment:
CARGO_INSTALL_OPTS="--locked --jobs 4" topgrade --only cargo
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/topgrade-rs/topgrade/blob/main/CONTRIBUTING.md

Install pre-commit hooks locally to ensure code quality before submitting changes. Alternatively, run cargo fmt, cargo clippy, and cargo test manually.

```shell
$ cargo fmt
$ cargo clippy
$ cargo test
```

--------------------------------

### Automated Daily Updates with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Example of running Topgrade as a cron job or systemd timer for automated daily updates. The `--yes` flag confirms all prompts, `--no-self-update` prevents Topgrade from updating itself during the run, and `--notify-end on_failure` sends a notification if the update process fails.

```bash
topgrade --yes --no-self-update --notify-end on_failure
```

--------------------------------

### Configure Zigup for Zig Version Management

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure zigup settings for updating Zig versions. Specify target versions, installation directory, path link, and cleanup options.

```toml
[zigup]
target_versions = ["master", "0.13.0"]   # Zig versions to update
install_dir = "~/.zig"
path_link = "~/.bin/zig"
cleanup = false   # Run zigup clean after updating
```

--------------------------------

### Cache sudo credentials with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Pre-emptively cache sudo credentials at the start of the Topgrade run. This avoids repeated password prompts during the upgrade process.

```bash
topgrade --sudoloop
```

--------------------------------

### Implement Update Function for New Step

Source: https://github.com/topgrade-rs/topgrade/blob/main/CONTRIBUTING.md

Implement the update function for a new step, typically named `run_xxx()`. This function should check for installation, print a separator, and execute the update command.

```rust
pub fn run_xxx(ctx: &ExecutionContext) -> Result<()> {
    // Check if this step is installed, if not, then this update will be skipped.
    let xxx = require("xxx")?;

    // Print the separator
    print_separator("xxx");

    // Invoke the new step to get things updated!
    ctx.execute(xxx)
       .arg(/* args required by this step */)
       .status_checked()
}
```

--------------------------------

### Windows-Specific Configuration for Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Topgrade for Windows updates, including package managers like winget and scoop, and WSL updates. Options control auto-reboot and silent installations.

```toml
[windows]
accept_all_updates = true
updates_auto_reboot = "no"    # "yes" | "no" | "ask"
open_remotes_in_new_terminal = false
wsl_update_pre_release = false
wsl_update_use_web_download = false
winget_install_silently = true
winget_use_sudo = false
# Required when installed via Scoop or Cargo to allow self-upgrade
self_rename = true
```

--------------------------------

### Distribution Summary and Nix Handler

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Enable display of distribution-specific summaries and configure the Nix handler.

```toml
# Show distribution-specific summary (e.g. .pacsave/.pacnew files on Arch)
show_distribution_summary = true

# NixOS/home-manager handler: "autodetect" | "nh" | "vanilla"
nix_handler = "autodetect"

```

--------------------------------

### Configure Distrobox/Toolbx for Container Management

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure distrobox settings, including whether to use root and which containers to manage.

```toml
[distrobox]
use_root = false
containers = ["archlinux-latest", "ubuntu-22.04"]
```

--------------------------------

### Julia Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Enable or disable startup file updates for Julia.

```toml
[julia]
startup_file = true

```

--------------------------------

### Print Topgrade config reference

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Display the built-in reference for Topgrade's configuration options. This is helpful for understanding available settings.

```bash
topgrade --config-reference
```

--------------------------------

### Mandb and Pkgfile Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Enable or disable mandb and pkgfile updates.

```toml
[mandb]
enable = false  # mandb is updated by systemd timers on most systems

[pkgfile]
enable = false

```

--------------------------------

### Run Windows-Specific Steps with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Command-line option to specify which Windows-specific package managers or tools Topgrade should update.

```bash
# Windows-only steps:
topgrade --only winget chocolatey scoop microsoft_store wsl wsl_update powershell
```

--------------------------------

### Pre-commands Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Define commands to be executed before any update steps begin.

```toml
# Commands run before any step
[pre_commands]
"Backup Emacs elpa" = "cp -rl ~/.emacs.d/elpa ~/.emacs.d/elpa.bak"

```

--------------------------------

### Flatpak Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure whether to use sudo for Flatpak updates.

```toml
[flatpak]
use_sudo = false

```

--------------------------------

### Vagrant Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify Vagrant directories and control power-on and suspend behavior.

```toml
[vagrant]
directories = ["~/projects/vm1", "~/projects/vm2"]
power_on = true
always_suspend = false

```

--------------------------------

### Post-commands Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Define commands to be executed after all update steps have completed.

```toml
# Commands run after all steps
[post_commands]
"Cleanup old backups" = "find ~/backups -mtime +30 -delete"

```

--------------------------------

### Use alternative config file with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify a custom configuration file to use for the Topgrade run. This allows for different sets of configurations without modifying the default.

```bash
topgrade --config /path/to/custom.toml
```

--------------------------------

### Dry run with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Simulate an upgrade process without making any changes to your system. This is useful for previewing what actions Topgrade would take.

```bash
topgrade --dry-run
```

--------------------------------

### Show skipped steps with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Display the reasons why certain update steps were skipped during the run. This provides transparency into Topgrade's decision-making.

```bash
topgrade --show-skipped
```

--------------------------------

### Distrobox Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Distrobox to use root and specify containers for updates.

```toml
[distrobox]
use_root = false
containers = ["archlinux-latest", "ubuntu-22.04"]

```

--------------------------------

### Run macOS-Specific Steps with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Command-line option to specify which macOS-specific package managers or tools Topgrade should update.

```bash
# macOS-only steps available:
topgrade --only brew_formula brew_cask mas macports xcodes sparkle microsoft_office
```

--------------------------------

### Define Custom Commands for Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Add custom commands to run before, after, or inline with Topgrade's built-in steps. Use descriptive names for these commands.

```toml
# Run before any step
[pre_commands]
"Snapshot dotfiles" = "git -C ~/dotfiles stash"

# Run after all steps
[post_commands]
"Notify done" = "notify-send 'Topgrade finished'"

# Inline custom steps (run as part of the CustomCommands step in default order)
[commands]
"Update Python venv" = "~/dev/.venv/bin/pip install -U -r ~/dev/requirements.txt"
# Run with interactive shell to source ~/.zshrc etc.
"Interactive update" = "-i my_custom_updater"
```

--------------------------------

### Basic Configuration Options

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

These options control general behavior like setting the terminal title, displaying times, auto-yes prompts, and handling step failures.

```toml
set_title = true        # Set terminal title
display_time = true     # Show time in step headers
assume_yes = false      # Auto-yes for all prompts
ask_retry = true        # Ask what to do after a step fails
auto_retry = 0          # Auto-retry count for failed steps (default: 0)
show_skipped = false    # Show reason for skipped steps
cleanup = false         # Run cleanup steps (e.g. brew autoremove)

```

--------------------------------

### Configure Container Updates with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify the container runtime (Docker or Podman) and configure system pruning. Options to ignore specific containers and use sudo if necessary.

```toml
[containers]
runtime = "podman"   # "docker" (default) | "podman"
ignored_containers = [
    "ghcr.io/rancher-sandbox/rdx-proxy:latest",
    "docker.io/myorg/*"
]
system_prune = true   # Run docker/podman system prune after update
use_sudo = false      # Required for non-rootless installs
```

--------------------------------

### Vim Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Force Vim Plug update behavior.

```toml
[vim]
force_plug_update = false   # Use PlugUpdate! instead of PlugUpdate

```

--------------------------------

### Perform a Dry Run of Topgrade Commands

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Simulate the Topgrade update process by printing the commands that would be executed without actually running them.

```bash
# Dry run: print commands without executing
topgrade -n
topgrade --dry-run
```

--------------------------------

### Run Subset of Steps in Custom Order

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Combine CLI options to execute only a specified subset of steps, maintaining their default relative order.

```bash
# Combined with CLI to run only a subset in a custom order:
topgrade --only cargo rustup vim
# (steps execute in their default relative order within the allowed set)
```

--------------------------------

### NPM and Yarn Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure whether to use sudo for NPM and Yarn updates.

```toml
[npm]
use_sudo = false

[yarn]
use_sudo = false

```

--------------------------------

### Pixi Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Control whether to include release notes for Pixi updates.

```toml
[pixi]
include_release_notes = false

```

--------------------------------

### Lensfun Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure whether to use sudo for Lensfun updates.

```toml
[lensfun]
use_sudo = false

```

--------------------------------

### Custom Commands Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Add custom update steps or scripts to be run alongside default updates.

```toml
# Custom update steps inserted among the default steps
[commands]
"Python Dev Env" = "~/dev/.env/bin/pip install -U -r requirements.txt"
# Prefix with -i to use an interactive shell (sources rc files):
"Custom interactive" = "-i my_upgrade_script.sh"

```

--------------------------------

### Configure Remote Topgrade Execution

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify remote hosts and paths for running Topgrade via SSH. Configure SSH arguments for connection settings.

```toml
[misc]
remote_topgrades = ["pi.local", "nas", "user@office-machine"]
remote_topgrade_path = ".cargo/bin/topgrade"
ssh_arguments = "-o ConnectTimeout=3 -o BatchMode=yes"
```

--------------------------------

### Configure Mise for Version Management

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure mise settings for managing tool versions. Options include bumping versions in `mise.toml`, setting parallel jobs, and controlling verbosity.

```toml
[mise]
bump = false        # Bump versions in mise.toml to latest available
jobs = 4            # Parallel jobs
interactive = false
quiet = false
silent = false
verbose = false
```

--------------------------------

### Configure Topgrade Notification Settings

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Manage when Topgrade sends notifications. Options include always, never, or only on failure. Configuration can also be set in the TOML file.

```bash
# Always notify at end (default)
topgrade --notify-end always

# Never notify
topgrade --notify-end never

# Only notify on failure
topgrade --notify-end on_failure

# Notify at the start of each individual step
# (config only)
```

```toml
[misc]
notify_each_step = true
notify_end = "on_failure"
```

--------------------------------

### Automatically confirm prompts with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Answer 'yes' to all prompts from package managers during the upgrade process. Use with caution as it bypasses manual confirmation.

```bash
topgrade --yes
```

--------------------------------

### Verbose debug output with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Enable detailed logging of Topgrade's operations. This is helpful for diagnosing issues or understanding the upgrade process.

```bash
topgrade --verbose
```

--------------------------------

### Run specific steps with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Execute only a specified subset of update steps. This allows for targeted upgrades of particular tools or ecosystems.

```bash
topgrade --only cargo rustup vim
```

--------------------------------

### Linux Package Manager Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify package managers and their arguments for Linux systems.

```toml
[linux]
# Arch Linux: "autodetect" | "aura" | "garuda_update" | "pacman" | "pamac" | "paru" | "pikaur" | "shelly" | "trizen" | "yay"
arch_package_manager = "yay"
yay_arguments = "--nodevel"
dnf_arguments = "--refresh"
show_arch_news = true
enable_tlmgr = false
redhat_distro_sync = false
suse_dup = false
rpm_ostree = false
bootc = false
nix_arguments = "--flake"
home_manager_arguments = ["--flake", "path/to/flake"]

```

--------------------------------

### Run Topgrade in a Tmux Session from CLI

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Command-line option to execute Topgrade within a new or existing tmux session.

```bash
# Run in a new tmux session from CLI
topgrade --tmux
```

--------------------------------

### Configure misc settings in Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Set miscellaneous options for Topgrade, such as allowing root execution, caching sudo credentials, or defining sudo command implementations.

```toml
[misc]
allow_root = false
pre_sudo = true
sudo_loop = true
sudo_loop_interval = 240
sudo_command = "sudo"
```

--------------------------------

### Homebrew Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Homebrew update behavior, including greedy updates and autoremoval.

```toml
[brew]
greedy_cask = true          # Update auto-update casks too
greedy_latest = false
greedy_auto_updates = false
autoremove = true
fetch_head = false

```

--------------------------------

### Firmware Update Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Enable or disable firmware updates.

```toml
[firmware]
upgrade = true

```

--------------------------------

### Container Runtime Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify the container runtime and configure ignored containers and system pruning.

```toml
[containers]
# "docker" | "podman"
runtime = "docker"
ignored_containers = ["ghcr.io/rancher-sandbox/*", "docker.io/myrepo/skip*"]
system_prune = false
use_sudo = false

```

--------------------------------

### Control Step Execution Order

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Define lists of steps to run first or last, overriding the default execution order.

```toml
[misc]
# Run chezmoi and rustup before all other steps
first = ["chezmoi", "rustup"]

# Run custom_commands and git_repos after all other steps
last = [["custom_commands", "git_repos"]]
```

--------------------------------

### Control Git Repositories Step in Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Command-line options to disable predefined Git repositories or to run only the Git repos step.

```bash
# Disable predefined repos from CLI
topgrade --disable-predefined-git-repos

# Run only the git repos step
topgrade --only git_repos
```

--------------------------------

### Configure Git Repositories for Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify which Git repositories Topgrade should pull or fetch. Supports glob patterns and concurrency limits. Arguments can be passed to git commands.

```toml
[git]
repos = [
    "~/src/*/",            # Glob: all direct subdirectories of ~/src
    "~/.config/nvim",
    "~/dotfiles"
]
max_concurrency = 8
arguments = "--rebase --autostash"
pull_predefined = true     # Also pull topgrade's own predefined well-known paths
fetch_only = false         # Set true to only fetch without merging
```

--------------------------------

### Cache Sudo Credentials Before Run

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Pre-emptively cache sudo credentials to avoid password prompts during the update process.

```toml
[misc]
# Cache credentials before the run to avoid mid-run password prompts
pre_sudo = true
```

--------------------------------

### Rustup Channels Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify which Rustup channels to update.

```toml
[rustup]
channels = ["stable"]   # Only update these channels; empty = all

```

--------------------------------

### Cleanup files with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Perform cleanup of temporary or old files in addition to running upgrade steps. This can help free up disk space.

```bash
topgrade --cleanup
```

--------------------------------

### Configure remote hosts for Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Define remote hosts where Topgrade should be executed via SSH before running locally. This enables distributed system upgrades.

```toml
remote_topgrades = ["pi.local", "workstation", "user@server.example.com"]
remote_topgrade_path = ".cargo/bin/topgrade"
ssh_arguments = "-o ConnectTimeout=5"
```

--------------------------------

### Enable Sudo Loop from CLI

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Activate the sudo credential loop feature directly from the command line, specifying the interval.

```bash
# Enable sudo loop from CLI
topgrade --sudoloop --sudoloop-interval 120
```

--------------------------------

### Git Repository Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure additional Git repositories to pull and manage, including concurrency and arguments.

```toml
[git]
# Additional git repos to pull/fetch (glob patterns supported)
repos = [
    "~/src/*",
    "~/.config/nvim",
    "~/dotfiles"
]
max_concurrency = 5         # Parallel pulls (default: no limit)
arguments = "--rebase --autostash"
pull_predefined = true       # Pull topgrade's own predefined repos
fetch_only = false           # Only fetch, don't merge

```

--------------------------------

### Cargo Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Enable updating of Git-originating Cargo packages.

```toml
[cargo]
git = true      # Also update git-originating packages
quiet = false

```

--------------------------------

### Force Specific Sudo Binary

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Topgrade to use a specific sudo command, such as 'doas', instead of auto-detection.

```toml
[misc]
# Force a specific sudo binary
sudo_command = "doas"
```

--------------------------------

### Configure Topgrade to Run in Tmux

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Topgrade to run its operations within a tmux session. Options include specifying the tmux socket and the session attachment mode.

```toml
[misc]
run_in_tmux = true
tmux_arguments = "-S /var/tmux.sock"
# "attach_if_not_in_session" | "attach_always"
tmux_session_mode = "attach_if_not_in_session"
```

--------------------------------

### Run Topgrade with a specific run type

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Execute Topgrade with a predefined run type, such as 'dry' for simulation or 'log' for logging-only operations. The default is 'normal'.

```bash
topgrade --run-type dry
```

--------------------------------

### Linux Distribution-Specific Package Manager Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure package managers for various Linux distributions like Arch, Fedora, OpenSUSE, NixOS, and Gentoo. Includes options for arguments and specific behaviors.

```toml
[linux]
# Arch Linux package manager selection
arch_package_manager = "paru"   # autodetect | aura | garuda_update | pacman | pamac | paru | pikaur | shelly | trizen | yay
yay_arguments = "--nodevel --combinedupgrade"
show_arch_news = true

# Fedora/RHEL
dnf_arguments = "--refresh --best"
redhat_distro_sync = true

# OpenSUSE
suse_dup = true

# Atomic/Fedora Silverblue
rpm_ostree = true
bootc = false

# NixOS
nix_arguments = "--flake"
nix_env_arguments = "--prebuilt-only"
home_manager_arguments = ["--flake", "."]
nix_handler = "nh"   # autodetect | nh | vanilla

# Gentoo
emerge_sync_flags = "-q"
emerge_update_flags = "-uDNa --with-bdeps=y world"

# TeX Live
enable_tlmgr = true
```

--------------------------------

### Windows Update Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Windows update behavior, including auto-reboot and winget settings.

```toml
[windows]
accept_all_updates = true
# "yes" | "no" | "ask"
updates_auto_reboot = "no"
open_remotes_in_new_terminal = false
wsl_update_pre_release = false
wsl_update_use_web_download = false
winget_install_silently = true
winget_use_sudo = false
# Required when topgrade is installed via Scoop or Cargo on Windows:
self_rename = false

```

--------------------------------

### Desktop Notification Settings

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure when and how desktop notifications are displayed for update processes.

```toml
# Desktop notifications
notify_each_step = false
notify_end = "always"   # "always" | "never" | "on_failure"

```

--------------------------------

### Include additional config files in Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify paths to additional TOML configuration files that should be included and merged with the main configuration. These are processed before the main file.

```toml
[include]
paths = ["/etc/topgrade.toml", "~/.config/topgrade.work.toml"]
```

--------------------------------

### Self-Update and Logging Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Control Topgrade's self-update behavior and set detailed logging filters for debugging.

```toml
# Self-update behavior
no_self_update = false

# Extra tracing directives (see tracing-subscriber EnvFilter)
log_filters = ["topgrade::command=debug", "warn"]

```

--------------------------------

### Mise Tool Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Mise tool update behavior, including job count and verbosity.

```toml
[mise]
bump = false
jobs = 4
interactive = false
quiet = false
silent = false
verbose = false

```

--------------------------------

### Composer Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure whether to perform a self-update for Composer.

```toml
[composer]
self_update = false

```

--------------------------------

### Generate Shell Completions for Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Commands to generate shell completion scripts for Bash and Zsh. Output should be redirected to the appropriate shell configuration file.

```bash
# Bash
topgrade --gen-completion bash >> ~/.bash_completion

# Zsh
topgrade --gen-completion zsh > ~/.zfunc/_topgrade
echo 'fpath+=~/.zfunc' >> ~/.zshrc && autoload -U compinit && compinit
```

--------------------------------

### Doom Emacs Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Doom Emacs update behavior, specifically passing the --aot flag.

```toml
[doom]
aot = false     # Pass --aot to doom upgrade

```

--------------------------------

### Locale Handling: Check Command Output Robustness

Source: https://github.com/topgrade-rs/topgrade/blob/main/CONTRIBUTING.md

When checking command output, be aware that strings like 'help' might be translated in non-English locales (e.g., '帮助' in Chinese). This code snippet demonstrates a basic check that may fail in localized environments.

```rust
let output = Command::new("xxx").arg("--help").output().unwrap();
let stdout = from_utf8(output.stdout).expect("Assume it is UTF-8 encoded");

if stdout.contains("help") {
// xxx works
}
```

--------------------------------

### Conda Environment Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify Conda environment names and paths to manage.

```toml
[conda]
env_names = ["Toolbox", "PyTorch"]
env_paths = ["~/webserver/.conda/"]

```

--------------------------------

### Pass Environment Variables to Child Processes

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Set environment variables for all child processes launched by Topgrade during its execution.

```bash
# Pass environment variables to all child processes during the run
topgrade --env HTTP_PROXY=http://proxy:3128 --env CARGO_TERM_COLOR=always
```

--------------------------------

### Edit Topgrade config file

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Open the current Topgrade configuration file in your default editor. This provides a quick way to modify settings.

```bash
topgrade --edit-config
```

--------------------------------

### VSCode Profile Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify a VSCode profile for extension updates.

```toml
[vscode]
profile = ""    # Update extensions for a specific VSCode profile

```

--------------------------------

### Conditionally confirm prompts with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Automatically answer 'yes' only for specified update steps. This provides a balance between automation and control.

```bash
topgrade --yes cargo npm
```

--------------------------------

### Chezmoi Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Control whether to exclude encrypted files during Chezmoi updates.

```toml
[chezmoi]
exclude_encrypted = false

```

--------------------------------

### Misc Configuration for Step Control

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Control which update steps are run, their order, and failure handling.

```toml
# Example: run only these two steps
[misc]
only = ["cargo", "rustup"]

# Example: always run chezmoi first and git_repos last
first = ["chezmoi"]
last = ["git_repos"]

# Example: ignore failures from powershell
ignore_failures = ["powershell"]

```

--------------------------------

### Go Package Management Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify Go packages to exclude from updates.

```toml
[go]
gup_exclude = ["kind", "pkgsite"]

```

--------------------------------

### Topgrade with Step-Level Ignore Failures

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configures Topgrade to ignore failures for specific upgrade steps. This prevents a single problematic tool from halting the entire update process. This configuration is typically placed within the Topgrade configuration file.

```toml
step_ignore_failures = ["some_flaky_tool"]
```

--------------------------------

### Ignore failures for specific steps in Topgrade config

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Topgrade to ignore failures for a list of specified steps. This prevents the upgrade process from aborting or prompting when these steps fail.

```toml
ignore_failures = ["powershell", "pip3"]
```

--------------------------------

### Set Topgrade Run Type

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Control how Topgrade executes commands. Use 'dry' for a simulation, 'normal' for default execution, and 'log' to run and log all commands.

```bash
topgrade --run-type dry     # equivalent to --dry-run
topgrade --run-type normal  # default: actually run commands
topgrade --run-type log     # run AND log all commands
```

--------------------------------

### Notify on failure only with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Topgrade to send a desktop notification only when an update step fails. This reduces noise by only alerting on critical events.

```bash
topgrade --notify-end on_failure
```

--------------------------------

### Auto-retry failed steps with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Topgrade to automatically retry steps that fail, up to a specified number of times. This can help overcome transient issues.

```bash
topgrade --auto-retry 3
```

--------------------------------

### Add Step to default_steps()

Source: https://github.com/topgrade-rs/topgrade/blob/main/CONTRIBUTING.md

Include the new step variant in the `default_steps()` function in `step.rs` to make it part of the default upgrade process.

```rust
Xxx,
```

--------------------------------

### Add Match Arm to Step::run()

Source: https://github.com/topgrade-rs/topgrade/blob/main/CONTRIBUTING.md

Add a match arm to the `Step::run()` function to handle the execution of the new step. Use conditional compilation for OS-specific steps.

```rust
Xxx => runner.execute(*self, "xxx", || ItsModule::run_xxx(ctx))?
```

```rust
#[cfg(target_os = "linux")]
{
    // Xxx is Linux-only
    runner.execute(Step::Xxx, "xxx", || ItsModule::run_xxx(&ctx))?;
}
```

--------------------------------

### Keep Sudo Credentials Alive During Run

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Maintain sudo credentials throughout a long Topgrade run, with a configurable interval for refreshing them. Note the security trade-off.

```toml
# Keep credentials alive throughout a long run (security trade-off)
sudo_loop = true
sudo_loop_interval = 180  # refresh every 3 minutes
```

--------------------------------

### Configure tmux session for Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Control whether Topgrade runs within a tmux session and specify arguments for the session. This is useful for managing long-running processes.

```toml
run_in_tmux = false
tmux_arguments = "-S /var/tmux.sock"
tmux_session_mode = "attach_if_not_in_session"
```

--------------------------------

### Python Package Management Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Enable or disable various Python package update tools like pip-review and pipupgrade.

```toml
[python]
enable_pip_review = false
enable_pip_review_local = false
enable_pipupgrade = false
pipupgrade_arguments = "-y -u --pip-path pip"
poetry_force_self_update = false

```

--------------------------------

### Configure Conda and Python Environment Updates

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Specify Conda environments to update and enable Python package reviews or upgrades. Options for pipupgrade arguments and poetry self-update.

```toml
[conda]
env_names = ["base", "Toolbox", "ml-env"]
env_paths = ["~/projects/webserver/.conda/"]

[python]
enable_pip_review = true
enable_pip_review_local = false
enable_pipupgrade = false
pipupgrade_arguments = "-y -u --pip-path pip"
poetry_force_self_update = false
```

--------------------------------

### Run Specific Custom Commands

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Execute only a single custom command by its defined name.

```bash
# Run only a specific custom command by name
topgrade --custom-commands "Update Python venv"
```

--------------------------------

### Keep Terminal Open After Run

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Topgrade to keep the terminal open upon completion by setting the TOPGRADE_KEEP_END environment variable.

```bash
# Keep terminal open at end via environment variable
TOPGRADE_KEEP_END=1 topgrade
```

--------------------------------

### Set custom environment variables with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Pass custom environment variables to the update commands executed by Topgrade. This allows for fine-grained control over the execution environment.

```bash
topgrade --env MY_VAR=value --env ANOTHER=val
```

--------------------------------

### macOS-Specific Brew Configuration

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Configure Homebrew package updates on macOS. Options include greedy updates for casks and formulae, autoremove, and fetching HEAD.

```toml
[brew]
greedy_cask = true          # Update casks with auto-update too
greedy_latest = false       # --greedy_latest flag
greedy_auto_updates = false # --greedy_auto_updates flag
autoremove = true           # Run brew autoremove after formula update
fetch_head = false          # Upgrade formulae built from HEAD
```

--------------------------------

### Run Topgrade inside tmux

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Execute Topgrade within a tmux session. This is useful for managing long-running upgrade processes or for remote execution.

```bash
topgrade --tmux
```

--------------------------------

### Disable Self-Update via Environment Variable

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Prevent Topgrade from updating itself by setting the TOPGRADE_NO_SELF_UPGRADE environment variable.

```bash
# Disable self-update via environment variable
TOPGRADE_NO_SELF_UPGRADE=1 topgrade
```

--------------------------------

### Generate shell completion script

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Generate shell completion scripts for various shells (bash, zsh, fish, powershell). This enhances command-line usability by providing auto-completion.

```bash
topgrade --gen-completion bash
```

--------------------------------

### Filter Remote Hosts for Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Limit Topgrade's remote execution to hosts matching a specific regular expression.

```bash
# Only upgrade hosts matching the regex "pi"
topgrade --remote-host-limit "pi"
```

--------------------------------

### Generate Fish Shell Completion

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Generates shell completion scripts for Fish. Save the output to the specified file to enable tab completion for Topgrade commands.

```bash
topgrade --gen-completion fish > ~/.config/fish/completions/topgrade.fish
```

--------------------------------

### Document Breaking Changes

Source: https://github.com/topgrade-rs/topgrade/blob/main/CONTRIBUTING.md

Document any breaking changes introduced in a PR within the `BREAKINGCHANGES_dev.md` file. Ensure the documentation is in Markdown and wrapped at 80 characters.

```markdown
1. The configuration location has been updated to x.

2. The step x has been removed.

3. ...
```

--------------------------------

### Disable retry prompt with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Prevent Topgrade from asking for confirmation before retrying a failed step. This fully automates the retry process.

```bash
topgrade --no-ask-retry
```

--------------------------------

### Disable specific steps globally in Topgrade config

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Globally disable a list of update steps by specifying their names in the configuration file. These steps will not be executed regardless of detection.

```toml
disable = ["system", "emacs", "containers"]
```

--------------------------------

### Generate PowerShell Completion

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Generates shell completion scripts for PowerShell. Append the output to your PowerShell profile to enable tab completion for Topgrade commands.

```powershell
topgrade --gen-completion powershell >> $PROFILE
```

--------------------------------

### Disable specific steps with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Prevent Topgrade from running certain update steps. This is useful for excluding tools or systems you do not want to upgrade automatically.

```bash
topgrade --disable system containers
```

--------------------------------

### Limit remote hosts with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Restrict remote SSH execution to hosts that match a given regular expression. This is useful for targeting specific environments for remote upgrades.

```bash
topgrade --remote-host-limit "prod.*"
```

--------------------------------

### Topgrade Remote Host Limit

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Limits Topgrade to run only on specified SSH hosts. This is useful for fleet management scenarios where you want to update a subset of machines.

```bash
topgrade --remote-host-limit host1,host2
```

--------------------------------

### Add New Step Variant

Source: https://github.com/topgrade-rs/topgrade/blob/main/CONTRIBUTING.md

Define a new variant for the Step enum to represent a new package manager or upgradeable item. Ensure variants remain sorted alphabetically.

```rust
pub enum Step {
    // Existing steps
    // ...

    // Your new step here!
    // Make sure it stays sorted alphabetically because that looks great :)
    Xxx,
}
```

--------------------------------

### I18n: Define Translations in YAML

Source: https://github.com/topgrade-rs/topgrade/blob/main/CONTRIBUTING.md

Add translations to `locales/app.yml`. For messages with arguments, use the `{argument_name}` format in the key and `%{argument_name}` in translations.

```yaml
"hello {name}": # key
  en: "hello %{name}"  # translation
```

--------------------------------

### Suppress self-update step with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Prevent Topgrade from performing its own self-update. This is useful if you manage Topgrade's version separately.

```bash
topgrade --no-self-update
```

--------------------------------

### Keep terminal open after run with Topgrade

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Prevent the terminal from closing automatically after Topgrade finishes. This allows interaction for actions like rebooting or opening a shell.

```bash
topgrade --keep
```

--------------------------------

### Do not run Topgrade inside tmux

Source: https://context7.com/topgrade-rs/topgrade/llms.txt

Explicitly disable running Topgrade within a tmux session, overriding any configuration settings. This ensures the process runs in the current terminal.

```bash
topgrade --no-tmux
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.