fflow-cli 1.0.0

FlutterFlow Git workflow CLI — manage feature branches, exports, staging and pushes.

fflow — FlutterFlow Dev Workflow Tool

Automates the FlutterFlow → VS Code → Git workflow for teams.
Designed for developers who export FlutterFlow code via CLI and push to GitLab.

---

Installation

Works on Windows, Mac, and Linux.

cd ~/Development/fflow
python install.py

This installs fflow as a global command and installs dependencies.

---

One-time Setup (per repository)

cd /path/to/your/git/repo
fflow setup

You will be asked for:

1. Your FlutterFlow CLI export command (paste it once — token is stored securely)
2. GitLab repository URL
3. Parent branches (uat, migrated_uat, migrated_prod)
4. Any hand-written custom files to protect from FF overwrites

---

Daily Usage

Every time you work — just run:

fflow

fflow reads your current git state and guides you through every step with y/n prompts:

1. Creates your branch (IABCP2-1234-uat)
2. Runs FlutterFlow export
3. Restores your custom code files automatically
4. Asks which pages/folders you worked on
5. Shows exact file list before staging
6. Detects if someone pushed to parent branch mid-work
7. Safely syncs (rebases) without losing your work
8. Commits with correct format (IABCP2-1234 LoginPage changes)
9. Pushes to GitLab

---

Commands

Command	When to use
fflow	Every time — main workflow
fflow setup	Once per repository
fflow register <file>	When you create a new hand-written file
fflow unregister <file>	Remove a file from custom registry
fflow doctor	When something looks broken
fflow --abort	Cancel a paused sync

---

Branch & Commit Format

• Branch: IABCP2-1234-uat
• Commit: IABCP2-1234 LoginPage, ProfilePage changes

---

Files Created in Your Repo

File	Purpose	Git-tracked?
.fflow.json	Project config (branches, endpoint, project ID)	✔ Yes
.fflow.env	Your FF token (secret)	✖ No (gitignored)
.fflow_registry.json	List of your custom files	✔ Yes
.fflow_state.json	Current task session state	✖ No (gitignored)
.fflow_custom_backup/	Backup of custom files before FF export	✖ No (gitignored)

---

How Custom File Protection Works

1. You run fflow register lib/utils/custom_helper.dart
2. Before every FF export, fflow backs up all registered files
3. After export, fflow restores them — even if FF overwrote them
4. Your hand-written code is never lost

---

How Mid-Process Sync Works

If someone pushes to the parent branch while you're working:

1. fflow detects it automatically before every step
2. Warns you with number of new commits
3. fflow → syncs: stashes your changes → rebases → re-applies your changes → restores custom files
4. FF-generated file conflicts are auto-resolved
5. Your file conflicts are shown clearly for manual resolution
6. After resolving, run fflow again to continue

---

Requirements

• Python 3.7+
• Git
• FlutterFlow CLI installed and in PATH