Branching and committing

Now that your project is set up, you can create a branch and commit your first changes.

Create and commit on a branch

Start by inspecting the workspace:

but status

but status shows the uncommitted area, applied branches and stacks, and the commits that haven't landed in your target branch.

If you have uncommitted changes and no branch yet, create the branch and commit in one command:

but commit -b user-bookmarks -m "Add user bookmarks"

The -b option selects the branch. If user-bookmarks doesn't exist, GitButler creates it. Because the command doesn't include any change IDs, it commits all uncommitted changes.

Commit selected files or hunks

Use but diff to get IDs for the changes you want to commit:

but diff

The first token on each file line is its ID. A hunk ID has the form <file-id>:<hunk-id>, such as q3:5.

Pass the IDs as space-separated positional arguments:

but commit -b user-bookmarks -m "Add bookmark model" q3 w7

That commits only changes q3 and w7. The other changes stay uncommitted.

To commit one hunk without committing the rest of its file:

but commit -b user-bookmarks -m "Validate bookmark URLs" q3:5

Copy IDs from your current but diff output. Don't comma-separate IDs or use line ranges.

Work on parallel branches

Parallel branches hold independent work in the same workspace. Suppose user-bookmarks is applied and you start an unrelated liked-tweets change. Inspect the new changes, then commit them to another branch:

but diff
but commit -b liked-tweets -m "Add liked tweets" n2 p8

GitButler creates liked-tweets alongside user-bookmarks. Run but status to see both branches:

but status

When more than one independent stack is applied, always use -b, --above, or --below to say where a commit belongs. GitButler refuses an untargeted commit when the destination is ambiguous.

Stack dependent branches

If the liked-tweets work turns out to depend on user-bookmarks, move that branch above user-bookmarks to turn the two parallel branches into a stack:

but move liked-tweets --above user-bookmarks

Once you've authenticated with but config forge auth, publish the stack from its top branch:

but pr new liked-tweets -t

GitButler pushes the stack and creates the missing reviews from the bottom upward. See Create stacked branches and pull requests for the full stacked-review workflow.