Updating the Base

The base branch is the foundation that your feature branches build upon. Keeping it updated and managing it properly is crucial for a smooth workflow.

Understanding the Base Branch

The base branch is typically your main development branch that acts as the basis for all your local branches.

In practice, this is actually the branch on whatever server you're using to collaborate and merge changes into, so generally it's actually origin/main or origin/master.

When GitButler is first initialized in a project, you are asked to choose a branch to target, as everything in your working directory that doesn't exactly match the tip of this branch is technically a fork of what is considered production. Whatever that target branch looks like when you choose it is set as your 'base'.

When you start working, everything that is different from that base goes into a branch based off of it.

Setting a base from a target branch, then doing some work

Understanding Upstream

When you first set your base branch (ie, origin/main), we record the state of the branch at that time.

However, if someone else merges work into that branch while you're working, the base branch moves forward, but the work you're doing is still based off of where it was. We call this 'upstream' work.

Some work has been merged in upstream, now our branch is out of date

The problem is that now the stuff we're working on is out of date. It may conflict with what is upstream, it may need the work that is upstream, etc. So how do we get our branch up to date?

Viewing Upstream

You can see what is upstream and if you're out of date by running but base check. This will essentially fetch origin/main (or whatever your targeted base branch is) and see if there is anything there that is newer than your base.

Let's take a look at what this looks like. Let's say that our project is at this state:

╭┄00 [Unassigned Changes] 
┊   wu M README-es.md 🔒 da42d06
┊   te A README.new.md 
┊   rt A app/views/bookmarks/index.html.erb 
┊
┊╭┄t5 [gemfile-fixes]  
┊●   da42d06 Add Spanish README and bookmarks feature    
┊●   fdbd753 just the one    
┊│
┊├┄qz [feature-bookmarks]  
┊●   223fdd6 feat: Add bookmarks table to store user-tweet rela    
├╯
┊
┊╭┄q6 [sc-branch-26]  
┊●   58d78ca add bookmark model and associations    
├╯
┊
● 204e309 (common base) [origin/main] Merge pull request #10 from schacon/sc-description

Let's see if we're up to date with but base check:

🔍 Checking base branch status...

📍 Base branch:		origin/main
⏫ Upstream commits:	2 new commits on origin/main

	204e309 Merge pull request #10 from schacon/sc-description  Add user description
	a76a41a Merge pull request #11 from schacon/sc-branch-11  Add notifications tabl
	249c8fd Merge pull request #12 from schacon/sc-branch-10  sc-branch-10

Active Branch Status

🔄 feature-bookmarks (Integrated)

✅ gemfile-fixes (Updatable)

❗️ sc-branch-26 (Conflicted (Not Rebasable))

Run `but base update` to update your branches

This will also check that upstream work against your currently applied branches to see if anything has been integrated (and thus we can remove), anything conflicts with upstream work, or a merge/rebase should work cleanly.

In this example, we can see that feature-bookmarks has been integrated (merged) upstream already, sc-branch-26 is conflicted with upstream work and gemfile-fixes can be cleanly rebased or merged.

Updating the Base

When you feel like you want to get your active branches up to date, you can run but base update. This will rebase your branches on top of the new base commit.

Rebasing our work onto the new upstream work, updating our base

Let's run it in our example.

🔄 Updating branches...

╭┄00 [Unassigned Changes] 
┊   wu M README-es.md 🔒 6291859
┊   te A README.new.md 
┊   rt A app/views/bookmarks/index.html.erb 
┊
┊╭┄t5 [gemfile-fixes]  
┊●   6291859 Add Spanish README and bookmarks feature    
┊●   0b92478 just the one    
├╯
┊
┊╭┄q6 [sc-branch-26]  
┊●   f3641af add bookmark model and associations  {conflicted}  
├╯
┊
● 32a2175 (common base) [origin/main] Merge pull request #65 from schacon/feature-bookma

OK, now we can see that our integrated branch was removed, our gemfile-fixes branch was successfully rebased and our sc-branch-26 work is marked as conflicted. We'll see how to deal with that state in a minute.