an example commit, with most of the stuff

content/docs/commands/but-absorb.mdx

@@ -0,0 +1,26 @@
+---
+title: "`but absorb`"
+description: "Amends changes into the appropriate commits where they belong."
+---
+
+Amends changes into the appropriate commits where they belong.
+
+The semantic for finding "the appropriate commit" is as follows:
+
+- Changes are amended into the topmost commit of the leftmost (first) lane (branch)
+- If a change is assigned to a particular lane (branch), it will be amended into a commit there
+- If there are no commits in this branch, a new commit is created
+- If a change has a dependency to a particular commit, it will be amended into that particular commit
+
+Optionally an identifier to an Uncommitted File or a Branch (stack) may be provided.
+
+- If an Uncommitted File id is provided, absorb will be peformed for just that file
+- If a Branch (stack) id is provided, absorb will be performed for all changes assigned to that stack
+- If no source is provided, absorb is performed for all uncommitted changes
+
+**Usage:** `but absorb [SOURCE]`
+
+## Arguments
+
+* `<SOURCE>` — If the Source is an uncommitted change - the change will be absorbed. If the Source is a stack - anything assigned to the stack will be absorbed accordingly. If not provided, everything that is uncommitted will be absorbed
+

content/docs/commands/but-base.mdx

@@ -1,51 +1,41 @@
 ---
-title: 'but base'
-description: 'Commands for managing the base branch'
+title: "`but base`"
+description: "Commands for managing the base target branch."
 ---
 
-## Usage
+Commands for managing the base target branch.
 
-```
-but base <SUBCOMMAND>
-```
+Every branch managed by GitButler is based off a common base branch on your remote repository (usually origin/main or origin/master). This is the target branch that all changes will eventually be integrated into.
 
-## Subcommands
+The base subcommand allows you to manage and update this base branch.
+
+When you run but base update, GitButler will fetch the latest changes from the remote and rebase all your applied branches on top of the updated base branch. You will want to do this regularly to keep your branches up to date with the latest changes from the main development line.
 
-### check
+You can also use but base check to verify that your branches can be cleanly merged into the base branch without conflicts and see what work is upstream an not yet integrated into your branches.
 
-Fetches remotes from the remote and checks the mergeability of the branches in the workspace.
+**Usage:** `but base <COMMAND>`
+
+## Subcommands
 
-```
-but base check
-```
+### `but base check`
 
-Shows the status of the base branch including:
+Fetches from the remote and checks the mergeability of the branches in the workspace.
 
-- Base branch name
-- Number of upstream commits
-- Recent commits
-- Status of active branches (updatable, integrated, conflicted, etc.)
+This will see if the target branch has had new work merged into it, and if so, it will check if each branch in the workspace can be cleanly merged into the updated target branch.
 
-### update
+It will also show what work is upstream that has not yet been integrated into the branches.
 
-Updates the workspace (with all applied branches) to include the latest changes from the base branch.
+**Usage:** `but base check`
 
-```
-but base update
-```
+### `but base update`
 
-Integrates upstream changes into your workspace branches, rebasing or deleting branches as appropriate.
+Updates all applied branches to be up to date with the target branch
 
-## Examples
+This fetches the latest changes from the remote and rebases all applied branches on top of the updated target branch.
 
-Check base branch status:
+You should run this regularly to keep your branches up to date with the latest changes from the main development line.
 
-```
-but base check
-```
+You can run but base check first to see if your branches can be cleanly merged into the target branch before running the update.
 
-Update workspace with base branch changes:
+**Usage:** `but base update`
 
-```
-but base update
-```

content/docs/commands/but-branch.mdx

@@ -1,124 +1,133 @@
 ---
-title: 'but branch'
-description: 'Commands for managing branches'
+title: "`but branch`"
+description: "Commands for managing branches."
 ---
 
-## Usage
+Commands for managing branches.
 
-```
-but branch <SUBCOMMAND>
-```
+This includes creating, deleting, listing, showing details about, and applying and unapplying branches.
+
+By default without a subcommand, it will list the branches.
+
+**Usage:** `but branch <COMMAND>`
 
 ## Subcommands
 
-### new
+### `but branch new`
+
+Creates a new branch in the workspace
+
+If no branch name is provided, a new parallel branch with a generated name will be created.
+
+You can also specify an anchor point using the --anchor option, which can be either a commit ID or an existing branch name to create the new branch from. This allows you to create stacked branches.
+
+**Usage:** `but branch new [BRANCH_NAME] [OPTIONS]`
+
+**Arguments:**
+
+* `<BRANCH_NAME>` — Name of the new branch
+
+**Options:**
+
+* `-a`, `--anchor` `<ANCHOR>` — Anchor point - either a commit ID or branch name to create the new branch from
+
+### `but branch delete`
+
+Deletes a branch from the workspace
+
+This will remove the branch and all its commits from the workspace. If the branch has unpushed commits, you will be prompted for confirmation unless the --force flag is used.
+
+**Usage:** `but branch delete <BRANCH_NAME> [OPTIONS]`
 
-Creates a new branch in the workspace.
+**Arguments:**
 
-```
-but branch new [OPTIONS] [BRANCH_NAME]
-```
+* `<BRANCH_NAME>` — Name of the branch to delete (required)
 
-#### Arguments
+**Options:**
 
-- `[BRANCH_NAME]` - Name of the new branch (optional, auto-generated if not provided)
+* `-f`, `--force` — Force deletion without confirmation
 
-#### Options
+### `but branch list`
 
-- `-a, --anchor <ANCHOR>` - Anchor point - either a commit ID or branch name to create the new branch from
+List the branches in the repository
 
-### delete
+By default, shows the active branch and the 20 most recently updated branches.
 
-Deletes a branch from the workspace.
+You can use the --all flag to show all branches, --local to show only local branches, or --remote to show only remote branches.
 
-```
-but branch delete [OPTIONS] <BRANCH_NAME>
-```
+You can also filter branch names by specifying a substring, such as but branch list feature to show only branches with "feature" in the name.
 
-Alias: `-d`
+If you want to check for review status, you can add --review to fetch and display pull request or merge request information for each branch. This will make the command slower as it needs to query the forge.
 
-#### Arguments
+By default, the command checks if each branch merges cleanly into the upstream base target branch (not your workspace). You can disable this check with --no-check to make the command faster.
 
-- `<BRANCH_NAME>` - Name of the branch to delete (required)
+By default it also calculates the number of commits each branch is ahead of the base branch. You can disable this with --no-ahead to make the command faster.
 
-#### Options
+**Usage:** `but branch list [FILTER] [OPTIONS]`
 
-- `-f, --force` - Force deletion without confirmation
+**Arguments:**
 
-### list
+* `<FILTER>` — Filter branches by name (case-insensitive substring match)
 
-List the branches in the repository.
+**Options:**
 
-```
-but branch list [OPTIONS]
-```
+* `-l`, `--local` — Show only local branches
+* `-r`, `--remote` — Show only remote branches
+* `-a`, `--all` — Show all branches (not just active + 20 most recent)
+* `--no-ahead` — Don't calculate and show number of commits ahead of base (faster)
+* `--review` — Fetch and display review information (PRs, MRs, etc.)
+* `--no-check` — Don't check if each branch merges cleanly into upstream
 
-#### Options
+### `but branch show`
 
-- `-l, --local` - Show only local branches
+Show commits ahead of base for a specific branch
 
-### unapply
+This shows the list of commits that are on the specified branch but not yet integrated into the base target branch.
 
-Unapply a branch from the workspace.
+You can also choose to fetch and display review information, show files modified in each commit with line counts, generate an AI summary of the branch changes, and check if the branch merges cleanly into upstream.
 
-```
-but branch unapply [OPTIONS] <BRANCH_NAME>
-```
+**Usage:** `but branch show <BRANCH_ID> [OPTIONS]`
 
-#### Arguments
+**Arguments:**
 
-- `<BRANCH_NAME>` - Name of the branch to unapply (required)
+* `<BRANCH_ID>` — CLI ID or name of the branch to show (required)
 
-#### Options
+**Options:**
 
-- `-f, --force` - Force unapply without confirmation
+* `-r`, `--review` — Fetch and display review information
+* `-f`, `--files` — Show files modified in each commit with line counts
+* `--ai` — Generate AI summary of the branch changes
+* `--check` — Check if the branch merges cleanly into upstream and identify conflicting commits
 
-## Examples
+### `but branch apply`
 
-Create a new branch with auto-generated name:
+Apply a branch to the workspace
 
-```
-but branch new
-```
+If you want to apply an unapplied branch to your workspace so you can work on it, you can run but branch apply <branch-name>.`
 
-Create a new branch with a specific name:
+This will apply the changes in that branch into your working directory as a parallel applied branch.
 
-```
-but branch new my-feature
-```
+**Usage:** `but branch apply <BRANCH_NAME>`
 
-Create a new branch from a specific commit:
+**Arguments:**
 
-```
-but branch new my-feature --anchor abc123
-```
+* `<BRANCH_NAME>` — Name of the branch to apply (required)
 
-Delete a branch with confirmation:
+### `but branch unapply`
 
-```
-but branch delete my-feature
-```
+Unapply a branch from the workspace
 
-Force delete a branch without confirmation:
+If you want to unapply an applied branch from your workspace (effectively stashing it) so you can work on other branches, you can run but branch unapply <branch-name>.
 
-```
-but branch delete my-feature --force
-```
+This will remove the changes in that branch from your working directory and you can re-apply it later when needed. You will then see the branch as unapplied in but branch list.
 
-List all branches:
+**Usage:** `but branch unapply <BRANCH_NAME> [OPTIONS]`
 
-```
-but branch list
-```
+**Arguments:**
 
-List only local branches:
+* `<BRANCH_NAME>` — Name of the branch to unapply (required)
 
-```
-but branch list --local
-```
+**Options:**
 
-Unapply a branch from the workspace:
+* `-f`, `--force` — Force unapply without confirmation
 
-```
-but branch unapply my-feature
-```

content/docs/commands/but-commit.mdx

@@ -1,53 +1,29 @@
 ---
-title: 'but commit'
-description: 'Commit changes to a stack'
+title: "`but commit`"
+description: "Commit changes to a stack."
 ---
 
-## Usage
+Commit changes to a stack.
 
-```
-but commit [OPTIONS]
-```
+The but commit command allows you to create a new commit on a specified branch (stack) with the current uncommitted changes.
 
-## Options
-
-### `-m, --message <MESSAGE>`
-
-Commit message.
-
-- **Type:** String
-- **Required:** Optional
-
-### `--branch <BRANCH>`
+If there is only one branch applied, it will commit to that branch by default.
 
-Branch CLI ID or name to derive the stack to commit to.
+If there are multiple branches applied, you must specify which branch to commit to, or if in interactive mode, you will be prompted to select one.
 
-- **Type:** String
-- **Required:** Optional
+By default, all uncommitted changes and all changes already assigned to that branch will be included in the commit. If you only want to commit the changes that are already assigned to that branch, you can use the --only flag.
 
-### `-o, --only`
+It will not commit changes assigned to other branches.
 
-Only commit assigned files, not unassigned files.
+**Usage:** `but commit [BRANCH] [OPTIONS]`
 
-- **Type:** Flag (boolean)
-- **Default:** `false`
+## Arguments
 
-## Examples
+* `<BRANCH>` — Branch CLI ID or name to derive the stack to commit to
 
-Commit with a message:
-
-```
-but commit -m "Add new feature"
-```
-
-Commit to a specific branch:
-
-```
-but commit -m "Fix bug" --branch my-feature-branch
-```
+## Options
 
-Commit only assigned files:
+* `-m`, `--message` `<MESSAGE>` — Commit message
+* `-c`, `--create` — Whether to create a new branch for this commit. If the branch name given matches an existing branch, that branch will be used instead. If no branch name is given, a new branch with a generated name will be created
+* `-o`, `--only` — Only commit assigned files, not unassigned files
 
-```
-but commit -m "Update docs" --only
-```