diff --git a/content/docs/commands/but-absorb.mdx b/content/docs/commands/but-absorb.mdx new file mode 100644 index 0000000..7ba5d87 --- /dev/null +++ b/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 + +* `` — 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 + diff --git a/content/docs/commands/but-base.mdx b/content/docs/commands/but-base.mdx index 0d0add9..d383626 100644 --- a/content/docs/commands/but-base.mdx +++ b/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 -``` +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 ` + +## 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 -``` diff --git a/content/docs/commands/but-branch.mdx b/content/docs/commands/but-branch.mdx index 0f1e231..cd9059c 100644 --- a/content/docs/commands/but-branch.mdx +++ b/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 -``` +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 ` ## 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:** + +* `` — Name of the new branch + +**Options:** + +* `-a`, `--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 [OPTIONS]` -Creates a new branch in the workspace. +**Arguments:** -``` -but branch new [OPTIONS] [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 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] -``` +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. -- `` - 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 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] -``` +**Usage:** `but branch show [OPTIONS]` -#### Arguments +**Arguments:** -- `` - Name of the branch to unapply (required) +* `` — 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 .` -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 ` -Create a new branch from a specific commit: +**Arguments:** -``` -but branch new my-feature --anchor abc123 -``` +* `` — 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 . -``` -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 [OPTIONS]` -``` -but branch list -``` +**Arguments:** -List only local branches: +* `` — 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 -``` diff --git a/content/docs/commands/but-commit.mdx b/content/docs/commands/but-commit.mdx index 52e9354..76d6e7e 100644 --- a/content/docs/commands/but-commit.mdx +++ b/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 ` - -Commit message. - -- **Type:** String -- **Required:** Optional - -### `--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 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` `` — 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 -``` diff --git a/content/docs/commands/but-describe.mdx b/content/docs/commands/but-describe.mdx index 1e0eaec..b0aac81 100644 --- a/content/docs/commands/but-describe.mdx +++ b/content/docs/commands/but-describe.mdx @@ -1,41 +1,19 @@ --- -title: 'but describe' -description: 'Edit the commit message of a specified commit' +title: "`but describe`" +description: "Edit the commit message of the specified commit." --- -## Usage +Edit the commit message of the specified commit. -``` -but describe -``` +You can easily change the commit message of any of your commits by running but describe and providing a new message in the editor. -## Alias +This will rewrite the commit with the new message and then rebase any dependent commits on top of it. -This command can also be invoked using the shorter alias `desc`: +You can also use but describe to rename the branch. -``` -but desc -``` +**Usage:** `but describe ` ## Arguments -### `` +* `` — Commit ID to edit the message for, or branch ID to rename (required) -Commit ID to edit the message for, or branch ID to rename. - -- **Type:** String -- **Required:** Yes - -## Examples - -Edit a commit message: - -``` -but describe abc123 -``` - -Rename a branch: - -``` -but describe my-feature-branch -``` diff --git a/content/docs/commands/but-forge.mdx b/content/docs/commands/but-forge.mdx index ead9925..9501bb6 100644 --- a/content/docs/commands/but-forge.mdx +++ b/content/docs/commands/but-forge.mdx @@ -1,64 +1,41 @@ --- -title: 'but forge' -description: 'Commands for interacting with forges like GitHub, GitLab, etc.' +title: "`but forge`" +description: "Commands for interacting with forges like GitHub, GitLab (coming soon), etc." --- -## Usage +Commands for interacting with forges like GitHub, GitLab (coming soon), etc. -``` -but forge -``` +The but forge tools allow you to authenticate with a forge from the CLI, which then enables features like creating pull requests with the but review commands. -## Subcommands - -### auth - -Authenticate with your forge provider (at the moment, only GitHub is supported). +Start by running but forge auth to authenticate with your forge. -``` -but forge auth -``` +You can also authenticate several different users on a forge and see them listed with but forge list-users or forget a user with but forge forget. -Initiates a device OAuth flow to authenticate with GitHub. You'll be provided with a code and URL to complete the authentication process. +Currently only GitHub is supported, but more forges will be added in the near future. -### list-users +**Usage:** `but forge ` -List authenticated forge accounts known to GitButler. - -``` -but forge list-users -``` - -Displays a list of all GitHub usernames that have been authenticated with GitButler. +## Subcommands -### forget +### `but forge auth` -Forget a previously authenticated forge account. +Authenticate with your forge provider (at the moment, only GitHub is supported) -``` -but forge forget -``` +**Usage:** `but forge auth` -#### Arguments +### `but forge list-users` -- `` - The username of the forge account to forget (required) +List authenticated forge accounts known to GitButler -## Examples +**Usage:** `but forge list-users` -Authenticate with GitHub: +### `but forge forget` -``` -but forge auth -``` +Forget a previously authenticated forge account -List authenticated users: +**Usage:** `but forge forget [USERNAME]` -``` -but forge list-users -``` +**Arguments:** -Forget a GitHub account: +* `` — The username of the forge account to forget If not provided, you'll be prompted to select which account(s) to forget. If only one account exists, it will be forgotten automatically -``` -but forge forget octocat -``` diff --git a/content/docs/commands/but-gui.mdx b/content/docs/commands/but-gui.mdx new file mode 100644 index 0000000..6cea1c8 --- /dev/null +++ b/content/docs/commands/but-gui.mdx @@ -0,0 +1,15 @@ +--- +title: "`but gui`" +description: "Open the GitButler GUI for the current project." +--- + +Open the GitButler GUI for the current project. + +Running but gui will launch the GitButler graphical user interface in the current directory's GitButler project. + +This provides a visual way to manage branches, commits, and uncommitted changes, complementing the command-line interface. + +You can also just run but . as a shorthand to open the GUI. + +**Usage:** `but gui` + diff --git a/content/docs/commands/but-init.mdx b/content/docs/commands/but-init.mdx index 1774913..093a2ef 100644 --- a/content/docs/commands/but-init.mdx +++ b/content/docs/commands/but-init.mdx @@ -1,33 +1,21 @@ --- -title: 'but init' -description: 'Initialize a GitButler project from a git repository' +title: "`but init`" +description: "Initializes a GitButler project from a git repository in the current directory." --- -## Usage +Initializes a GitButler project from a git repository in the current directory. -``` -but init [OPTIONS] -``` +If you have an existing Git repository and want to start using GitButler with it, you can run this command to set up the necessary configuration and data structures. -## Options - -### `-r, --repo` +This is automatically run when you run any other but command in a git repository that is not yet initialized with GitButler. -Also initializes a git repository in the current directory if one does not exist. +Note: Currently, if there is no Git repository already, you will need to initialize it with git init and add a remote first, as GitButler needs a remote to base the branches on. -- **Type:** Flag (boolean) -- **Default:** `false` +We are working on removing this limitation, but for now this is something to be aware of. -## Examples +**Usage:** `but init [OPTIONS]` -Initialize GitButler in an existing git repository: - -``` -but init -``` +## Options -Initialize both git and GitButler: +* `-r`, `--repo` — Also initializes a git repository in the current directory if one does not exist -``` -but init --repo -``` diff --git a/content/docs/commands/but-lazy.mdx b/content/docs/commands/but-lazy.mdx new file mode 100644 index 0000000..41b0720 --- /dev/null +++ b/content/docs/commands/but-lazy.mdx @@ -0,0 +1,6 @@ +--- +title: "`but lazy`" +description: "Launch a lazygit-style TUI for GitButler" +--- + +**Usage:** `but lazy` diff --git a/content/docs/commands/but-mark.mdx b/content/docs/commands/but-mark.mdx index 9dd0597..0005452 100644 --- a/content/docs/commands/but-mark.mdx +++ b/content/docs/commands/but-mark.mdx @@ -1,46 +1,23 @@ --- -title: 'but mark' -description: 'Create or remove a rule for auto-assigning or auto-committing' +title: "`but mark`" +description: "Mark a commit or branch for auto-assign or auto-commit." --- -## Usage +Mark a commit or branch for auto-assign or auto-commit. -``` -but mark [OPTIONS] -``` +Creates or removes a rule for auto-assigning or auto-committing changes to the specified target entity. -## Arguments - -### `` - -The target entity that will be marked. - -- **Type:** String -- **Required:** Yes - -## Options +If you mark a branch, new unassigned changes that GitButler sees when you run any command will be automatically assigned to that branch. -### `-d, --delete` +If you mark a commit, new uncommitted changes will automatically be amended into the marked commit. -Deletes a mark. +**Usage:** `but mark [OPTIONS]` -- **Type:** Flag (boolean) -- **Default:** `false` - -## Examples - -Create a mark: - -``` -but mark my-feature-branch -``` +## Arguments -Delete a mark: +* `` — The target entity that will be marked (required) -``` -but mark my-feature-branch --delete -``` +## Options -## Related Commands +* `-d`, `--delete` — Deletes a mark -- [`but unmark`](but-unmark) - Removes all marks from the workspace diff --git a/content/docs/commands/but-mcp.mdx b/content/docs/commands/but-mcp.mdx deleted file mode 100644 index 084fb00..0000000 --- a/content/docs/commands/but-mcp.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: 'but mcp' -description: 'Start up the MCP server' ---- - -## Usage - -``` -but mcp [OPTIONS] -``` - -## Description - -Starts the Model Context Protocol (MCP) server for GitButler, enabling integration with AI assistants and other tools that support the MCP protocol. - -## Options - -### `-i, --internal` - -Starts the internal MCP server which has more granular tools. - -- **Type:** Flag (boolean) -- **Default:** `false` -- **Note:** This option is hidden from standard help output - -## Examples - -Start the standard MCP server: - -``` -but mcp -``` - -Start the internal MCP server with more granular tools: - -``` -but mcp --internal -``` diff --git a/content/docs/commands/but-new.mdx b/content/docs/commands/but-new.mdx index 179faef..f4ab8d1 100644 --- a/content/docs/commands/but-new.mdx +++ b/content/docs/commands/but-new.mdx @@ -1,33 +1,19 @@ --- -title: 'but new' -description: 'Insert a blank commit before a specified commit or at the top of a stack' +title: "`but new`" +description: "Insert a blank commit before the specified commit, or at the top of a stack." --- -## Usage +Insert a blank commit before the specified commit, or at the top of a stack. -``` -but new -``` +This is useful for creating a placeholder commit that you can then amend changes into later using but mark, but rub or but absorb. -## Arguments - -### `` - -Commit ID to insert before, or branch ID to insert at top of stack. +You can modify the empty commit message at any time using but describe. -- **Type:** String -- **Required:** Yes +This allows for a more Jujutsu style workflow where you create commits first and then fill them in as you work. Create an empty commit, mark it for auto-commit, and then just work on your changes. Write the commit message whenever you prefer. -## Examples +**Usage:** `but new ` -Insert a blank commit before a specific commit: - -``` -but new abc123 -``` +## Arguments -Insert a blank commit at the top of a branch's stack: +* `` — Commit ID to insert before, or branch ID to insert at top of stack (required) -``` -but new my-feature-branch -``` diff --git a/content/docs/commands/but-oplog.mdx b/content/docs/commands/but-oplog.mdx index c939af3..2b38602 100644 --- a/content/docs/commands/but-oplog.mdx +++ b/content/docs/commands/but-oplog.mdx @@ -1,43 +1,19 @@ --- -title: 'but oplog' -description: 'Show operation history' +title: "`but oplog`" +description: "Show operation history." --- -## Usage +Show operation history. -``` -but oplog [OPTIONS] -``` +Displays a list of past operations performed in the repository, including their timestamps and descriptions. -## Description +This allows you to restore to any previous point in the history of the project. All state is preserved in operations, including uncommitted changes. -Displays the operation log (oplog) which tracks all operations performed in your GitButler workspace. This is useful for understanding what changes have been made and for potentially undoing or restoring to previous states. +You can use but restore to restore to a specific state. -## Options - -### `--since ` - -Start from this oplog SHA instead of the head. - -- **Type:** String -- **Required:** Optional - -## Examples +**Usage:** `but oplog [OPTIONS]` -Show recent operation history: - -``` -but oplog -``` - -Show operation history from a specific point: - -``` -but oplog --since abc123def456 -``` +## Options -## Related Commands +* `--since` `` — Start from this oplog SHA instead of the head -- [`but undo`](but-undo) - Undo the last operation -- [`but restore`](but-restore) - Restore to a specific oplog snapshot -- [`but snapshot`](but-snapshot) - Create an on-demand snapshot diff --git a/content/docs/commands/but-publish.mdx b/content/docs/commands/but-publish.mdx deleted file mode 100644 index 3dc8b6d..0000000 --- a/content/docs/commands/but-publish.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 'but publish' -description: 'Publish review requests for active branches in your workspace' ---- - -## Usage - -``` -but publish [OPTIONS] -``` - -## Description - -By default, publishes reviews for all active branches in your workspace. You can optionally specify a single branch to publish. - -## Options - -### `-b, --branch ` - -Publish reviews only for the specified branch. - -- **Type:** String -- **Required:** Optional - -### `-f, --with-force` - -Force push even if it's not fast-forward. - -- **Type:** Flag (boolean) -- **Default:** `true` - -### `-s, --skip-force-push-protection` - -Skip force push protection checks. - -- **Type:** Flag (boolean) -- **Default:** `false` - -### `-r, --run-hooks` - -Run pre-push hooks. - -- **Type:** Flag (boolean) -- **Default:** `true` - -## Examples - -Publish all active branches: - -``` -but publish -``` - -Publish a specific branch: - -``` -but publish --branch my-feature -``` - -Publish without running hooks: - -``` -but publish --run-hooks=false -``` diff --git a/content/docs/commands/but-push.mdx b/content/docs/commands/but-push.mdx index b2b3929..8a15807 100644 --- a/content/docs/commands/but-push.mdx +++ b/content/docs/commands/but-push.mdx @@ -1,115 +1,25 @@ --- -title: 'but push' -description: 'Push a branch/stack to remote' +title: "`but push`" +description: "Push changes in a branch to remote." --- -## Usage +Push changes in a branch to remote. -``` -but push [OPTIONS] -``` +but push will update the remote with the latest commits from the specified branch. -## Arguments - -### `` - -Branch name or CLI ID to push. - -- **Type:** String -- **Required:** Yes - -## Options - -### `-f, --with-force` - -Force push even if it's not fast-forward. - -- **Type:** Flag (boolean) -- **Default:** `true` - -### `-s, --skip-force-push-protection` - -Skip force push protection checks. - -- **Type:** Flag (boolean) -- **Default:** `false` - -### `-r, --run-hooks` - -Run pre-push hooks. - -- **Type:** Flag (boolean) -- **Default:** `true` - -## Gerrit Options - -The following options are only available when Gerrit mode is enabled for your repository: - -### `-w, --wip` - -Mark change as work-in-progress (Gerrit). Mutually exclusive with `--ready`. - -- **Type:** Flag (boolean) -- **Default:** `false` +Whatever the upstream remote is configured for the base branch, that will be used as the remote to push to. -### `-y, --ready` +If you have another remote you want to push to that is different from the target remote (for example, a fork of an open source project), you can set it in the GitButler project settings. (Currently only via the GUI.) -Mark change as ready for review (Gerrit). This is the default state. Mutually exclusive with `--wip`. +**Usage:** `but push [OPTIONS]` -- **Type:** Flag (boolean) -- **Default:** `false` - -### `-a, --hashtag, --tag ` - -Add hashtag(s) to change (Gerrit). Can be used multiple times. - -- **Type:** String (repeatable) -- **Required:** Optional - -### `-t, --topic ` - -Add custom topic to change (Gerrit). At most one topic can be set. Mutually exclusive with `--topic-from-branch`. - -- **Type:** String -- **Required:** Optional - -### `--tb, --topic-from-branch` - -Use branch name as topic (Gerrit). Mutually exclusive with `--topic`. - -- **Type:** Flag (boolean) -- **Default:** `false` - -### `-p, --private` - -Mark change as private (Gerrit). - -- **Type:** Flag (boolean) -- **Default:** `false` - -## Examples - -Push a branch: - -``` -but push my-feature-branch -``` - -Force push without running hooks: - -``` -but push my-feature-branch --with-force --run-hooks=false -``` +## Arguments -Push with Gerrit flags (when Gerrit mode is enabled): +* `` — Branch name or CLI ID to push (required) -``` -but push my-feature-branch --ready --hashtag bug-fix --hashtag security -``` +## Options -## Notes +* `-f`, `--with-force` — Force push even if it's not fast-forward (default: `true`) +* `-s`, `--skip-force-push-protection` — Skip force push protection checks +* `-r`, `--run-hooks` — Run pre-push hooks (default: `true`) -- Gerrit push flags (`--wip`, `--ready`, `--hashtag/--tag`, `--topic`, `--topic-from-branch`, `--private`) can only be used when gerrit_mode is enabled for the repository -- `--wip` and `--ready` are mutually exclusive. Ready is the default state. -- `--topic` and `--topic-from-branch` are mutually exclusive. At most one topic can be set. -- Multiple hashtags can be specified by using `--hashtag` (or `--tag`) multiple times. diff --git a/content/docs/commands/but-restore.mdx b/content/docs/commands/but-restore.mdx index f868fef..c9c173e 100644 --- a/content/docs/commands/but-restore.mdx +++ b/content/docs/commands/but-restore.mdx @@ -1,48 +1,21 @@ --- -title: 'but restore' -description: 'Restore to a specific oplog snapshot' +title: "`but restore`" +description: "Restore to a specific oplog snapshot." --- -## Usage +Restore to a specific oplog snapshot. -``` -but restore [OPTIONS] -``` +This command allows you to revert the repository to a previous state captured in an oplog snapshot. -## Arguments +You need to provide the SHA of the oplog entry you want to restore to, which you can find by running but oplog. -### `` +**Usage:** `but restore [OPTIONS]` -Oplog SHA to restore to. +## Arguments -- **Type:** String -- **Required:** Yes +* `` — Oplog SHA to restore to (required) ## Options -### `-f, --force` - -Skip confirmation prompt. - -- **Type:** Flag (boolean) -- **Default:** `false` - -## Examples - -Restore to a specific snapshot (with confirmation): - -``` -but restore abc123def456 -``` - -Restore without confirmation prompt: - -``` -but restore abc123def456 --force -``` - -## Related Commands +* `-f`, `--force` — Skip confirmation prompt -- [`but oplog`](but-oplog) - Show operation history -- [`but undo`](but-undo) - Undo the last operation -- [`but snapshot`](but-snapshot) - Create an on-demand snapshot diff --git a/content/docs/commands/but-review.mdx b/content/docs/commands/but-review.mdx new file mode 100644 index 0000000..48e62a6 --- /dev/null +++ b/content/docs/commands/but-review.mdx @@ -0,0 +1,37 @@ +--- +title: "`but review`" +description: "Commands for creating and publishing code reviews to a forge." +--- + +Commands for creating and publishing code reviews to a forge. + +If you are authenticated with a forge using but forge auth, you can use the but review commands to create pull requests (or merge requests) on the remote repository for your branches. + +**Usage:** `but review ` + +## Subcommands + +### `but review publish` + +Publish review requests for active branches in your workspace. By default, publishes reviews for all active branches + +**Usage:** `but review publish [OPTIONS]` + +**Options:** + +* `-b`, `--branch` `` — Publish reviews only for the specified branch +* `-f`, `--with-force` — Force push even if it's not fast-forward (defaults to true) (default: `true`) +* `-s`, `--skip-force-push-protection` — Skip force push protection checks +* `-r`, `--run-hooks` — Run pre-push hooks (defaults to true) (default: `true`) +* `-t`, `--default` — Use the default content for the review title and description, skipping any prompts. If the review contains only a single commit, the commit message will be used for the review title and description (default: `false`) + +### `but review template` + +Configure the template to use for review descriptions. This will list all available templates found in the repository and allow you to select one + +**Usage:** `but review template [TEMPLATE_PATH]` + +**Arguments:** + +* `` — Path to the review template file within the repository + diff --git a/content/docs/commands/but-rub.mdx b/content/docs/commands/but-rub.mdx index d682a61..3cd1c83 100644 --- a/content/docs/commands/but-rub.mdx +++ b/content/docs/commands/but-rub.mdx @@ -1,67 +1,41 @@ --- -title: 'but rub' -description: 'Combine two entities together to perform an operation' +title: "`but rub`" +description: "Combines two entities together to perform an operation." --- -## Usage +Combines two entities together to perform an operation. -``` -but rub -``` +The rub command is a simple verb that helps you do a number of editing operations by doing combinations of two things. -## Description +For example, you can "rub" a file onto a branch to assign that file to the branch. You can also "rub" a commit onto another commit to squash them together. You can rub a commit onto a branch to move that commit. You can rub a file from one commit to another. -The `rub` command is a versatile operation that combines two entities together to perform various operations depending on the types of entities provided. +Non-exhaustive list of operations: -### Supported Operations + │Source │Target + ──────┼───────────┼────── + Amend │File,Branch│Commit + Squash│Commit │Commit + Assign│File,Branch│Branch + Move │Commit │Branch -| Source | Target | Operation | -| ------ | ------ | --------- | -| File | Commit | Amend | -| Branch | Commit | Amend | -| Commit | Commit | Squash | -| File | Branch | Assign | -| Branch | Branch | Assign | -| Commit | Branch | Move | +**Usage:** `but rub ` ## Arguments -### `` - -The source entity to combine. - -- **Type:** String -- **Required:** Yes - -### `` - -The target entity to combine with the source. - -- **Type:** String -- **Required:** Yes +* `` — The source entity to combine (required) +* `` — The target entity to combine with the source (required) ## Examples -Amend a file to a commit: - -``` -but rub path/to/file.txt abc123 -``` +Squashing two commits into one (combining the commit messages): -Squash two commits: + but rub 3868155 abe3f53f -``` -but rub abc123 def456 -``` +Amending a commit with the contents of a modified file: -Assign a file to a branch: + but rub README.md abe3f53f -``` -but rub path/to/file.txt my-feature-branch -``` +Moving a commit from one branch to another: -Move a commit to a different branch: + but rub 3868155 feature-branch -``` -but rub abc123 my-other-branch -``` diff --git a/content/docs/commands/but-snapshot.mdx b/content/docs/commands/but-snapshot.mdx index 3ac1526..20857fd 100644 --- a/content/docs/commands/but-snapshot.mdx +++ b/content/docs/commands/but-snapshot.mdx @@ -1,43 +1,17 @@ --- -title: 'but snapshot' -description: 'Create an on-demand snapshot with optional message' +title: "`but snapshot`" +description: "Create an on-demand snapshot with optional message." --- -## Usage +Create an on-demand snapshot with optional message. -``` -but snapshot [OPTIONS] -``` +This allows you to create a named snapshot of the current state, which can be helpful to always be able to return to a known good state. -## Description +You can provide an optional message to describe the snapshot. -Creates a snapshot of the current workspace state in the operation log. This is useful for creating manual checkpoints before making significant changes. +**Usage:** `but snapshot [OPTIONS]` ## Options -### `-m, --message ` +* `-m`, `--message` `` — Message to include with the snapshot -Message to include with the snapshot. - -- **Type:** String -- **Required:** Optional - -## Examples - -Create a snapshot without a message: - -``` -but snapshot -``` - -Create a snapshot with a descriptive message: - -``` -but snapshot -m "Before refactoring authentication module" -``` - -## Related Commands - -- [`but oplog`](but-oplog) - Show operation history -- [`but undo`](but-undo) - Undo the last operation -- [`but restore`](but-restore) - Restore to a specific oplog snapshot diff --git a/content/docs/commands/but-status.mdx b/content/docs/commands/but-status.mdx index 8b6d21d..38e8a5b 100644 --- a/content/docs/commands/but-status.mdx +++ b/content/docs/commands/but-status.mdx @@ -1,67 +1,27 @@ --- -title: 'but status' -description: 'Overview of the uncommitted changes in the repository' +title: "`but status`" +description: "Overview of the project workspace state." --- -## Usage +Overview of the project workspace state. -``` -but status [OPTIONS] -``` +This shows unassigned files, files assigned to stacks, all applied branches (stacked or parallel), commits on each of those branches, upstream commits that are unintegrated, commit status (pushed or local), and base branch information. -## Alias - -This command can also be invoked using the shorter alias `st`: - -``` -but st [OPTIONS] -``` - -## Example Output - -```ansi but-st-c43eb45a -but status -``` +**Usage:** `but status [OPTIONS]` ## Options -### `-f, --files` - -Determines whether the committed files should be shown as well. - -- **Type:** Flag (boolean) -- **Default:** `false` - -### `-v, --verbose` - -Show verbose output with commit author and timestamp. - -- **Type:** Flag (boolean) -- **Default:** `false` - -### `-r, --review` - -Show the forge review information. - -- **Type:** Flag (boolean) -- **Default:** `false` +* `-f` — Determines whether the committed files should be shown as well (default: `false`) +* `-v`, `--verbose` — Show verbose output with commit author and timestamp (default: `false`) +* `-r`, `--review` — Show the forge review information (default: `false`) ## Examples -Show basic status: - -``` -but status -``` +Normal usage: -Show status with files: + but status -``` -but status --files -``` +Shorthand with listing files modified -Show verbose status with review information: + but status -f -``` -but status -v -r -``` diff --git a/content/docs/commands/but-undo.mdx b/content/docs/commands/but-undo.mdx index 0a7de20..31cd318 100644 --- a/content/docs/commands/but-undo.mdx +++ b/content/docs/commands/but-undo.mdx @@ -1,32 +1,11 @@ --- -title: 'but undo' -description: 'Undo the last operation by reverting to the previous snapshot' +title: "`but undo`" +description: "Undo the last operation by reverting to the previous snapshot." --- -## Usage +Undo the last operation by reverting to the previous snapshot. -``` -but undo -``` +This is a shorthand for restoring to the last oplog entry before the current one. It allows you to quickly undo the most recent operation. -## Description +**Usage:** `but undo` -Reverts the workspace to the state it was in before the last operation. This uses the operation log (oplog) to roll back changes. - -## Options - -This command takes no specific options. - -## Examples - -Undo the last operation: - -``` -but undo -``` - -## Related Commands - -- [`but oplog`](but-oplog) - Show operation history -- [`but restore`](but-restore) - Restore to a specific oplog snapshot -- [`but snapshot`](but-snapshot) - Create an on-demand snapshot diff --git a/content/docs/commands/but-unmark.mdx b/content/docs/commands/but-unmark.mdx index d1073b8..1123886 100644 --- a/content/docs/commands/but-unmark.mdx +++ b/content/docs/commands/but-unmark.mdx @@ -1,30 +1,11 @@ --- -title: 'but unmark' -description: 'Remove all marks from the workspace' +title: "`but unmark`" +description: "Removes any marks from the workspace" --- -## Usage +Removes any marks from the workspace -``` -but unmark -``` +This will unmark anything that has been marked by the but mark command. -## Description +**Usage:** `but unmark` -This command removes all auto-assign and auto-commit rules (marks) from the workspace. - -## Options - -This command takes no specific options. - -## Examples - -Remove all marks: - -``` -but unmark -``` - -## Related Commands - -- [`but mark`](but-mark) - Creates or removes a rule for auto-assigning or auto-committing diff --git a/content/docs/commands/meta.json b/content/docs/commands/meta.json index 455dbdf..f075643 100644 --- a/content/docs/commands/meta.json +++ b/content/docs/commands/meta.json @@ -2,7 +2,6 @@ "title": "Commands", "defaultOpen": false, "pages": [ - "commands-overview", "---Basics---", "but-init", "---Inspection---", @@ -19,14 +18,17 @@ "but-new", "---Forge Stuff---", "but-push", - "but-publish", "but-forge", "---Operations Log---", "but-oplog", "but-undo", "but-restore", "but-snapshot", - "---AI Tools---", - "but-mcp" + "---Miscellaneous---", + "but-absorb", + "but-gui", + "but-lazy", + "but-review", + "commands-overview" ] }