docs/commands/upstream.md
Manage upstream fork workflow.
Set up and sync forks with their upstream repositories. Creates a local upstream branch to cleanly track the original repo, making merges easier.
# Set up upstream tracking
f upstream setup --upstream-url https://github.com/original/repo
# Pull latest from upstream
f upstream pull
# Full sync: pull, merge, push
f upstream sync
| Command | Description |
|---|---|
status | Show current upstream configuration |
setup | Set up upstream remote and local tracking branch |
pull | Pull changes from upstream into local 'upstream' branch |
sync | Full sync: pull upstream, merge to dev/main, push to origin |
Configure upstream tracking for a forked repository:
# Basic setup
f upstream setup --upstream-url https://github.com/original/repo
# Specify branch (if not main)
f upstream setup --upstream-url https://github.com/original/repo --upstream-branch master
| Option | Short | Description |
|---|---|---|
--upstream-url <URL> | -u | URL of the upstream repository |
--upstream-branch <BRANCH> | -b | Branch name on upstream (default: auto-detected) |
upstream remote pointing to original repoupstream branch tracking the upstream's default branch.git/configPull latest changes from upstream into local upstream branch:
# Pull into upstream branch
f upstream pull
# Pull and also merge into specific branch
f upstream pull --branch main
| Option | Short | Description |
|---|---|---|
--branch <BRANCH> | -b | Also merge into this branch after pulling |
Full sync workflow - pulls upstream, merges to your branch, and pushes:
# Full sync (pull, merge, push)
f upstream sync
# Sync without pushing (for review first)
f upstream sync --no-push
| Option | Description |
|---|---|
--no-push | Skip pushing to origin |
upstream branchmain)--no-push)Flow auto-detects the upstream default branch:
refs/remotes/upstream/HEADupstream/main or upstream/master existsmain as final fallbackShow current upstream configuration:
f upstream status
Output:
Upstream Configuration
Remote: https://github.com/original/repo
Branch: main
Local tracking: upstream -> upstream/main
Last sync: 2 hours ago
# 1. Clone your fork
git clone https://github.com/youruser/project
cd project
# 2. Set up upstream tracking
f upstream setup --upstream-url https://github.com/original/project
# 3. Verify
f upstream status
# When you want to sync with upstream:
f upstream sync
# Or if you want to review before pushing:
f upstream sync --no-push
git log --oneline main..upstream # See what's new
git push # Push when ready
If sync encounters merge conflicts:
$ f upstream sync
Merging upstream into main...
CONFLICT (content): Merge conflict in src/lib.rs
# Fix conflicts manually
vim src/lib.rs
git add src/lib.rs
git commit
# Then push
git push
Upstream configuration is stored in .git/config:
[remote "upstream"]
url = https://github.com/original/repo
fetch = +refs/heads/*:refs/remotes/upstream/*
[branch "upstream"]
remote = upstream
merge = refs/heads/main
You can also manually configure:
git remote add upstream https://github.com/original/repo
git fetch upstream
git branch upstream upstream/main
Run f upstream setup first with the upstream URL.
This can happen if there were no changes to stash. Flow handles this automatically by tracking stash state.
Flow auto-detects the default branch. If detection fails, specify explicitly:
f upstream setup --upstream-url https://github.com/original/repo --upstream-branch master
Resolve conflicts manually:
git add <files>git commitgit push