🚀 Flutter Commands Quick Reference

All essential Flutter commands organized by category and frequency of use.

---

📋 All Commands

Command	Purpose	Frequency
Model Generation
flutter pub run build_runner build --delete-conflicting-outputs	Generate .g.dart files (one-time)	After model changes
flutter pub run build_runner watch --delete-conflicting-outputs	Auto-generate on file save	During active development
flutter pub run build_runner clean	Clean generated files	When conflicts occur
Code Quality
dart format .	Format all Dart files	Before commit
dart format lib/	Format specific directory	As needed
flutter analyze	Check for errors and warnings	Before PR
Running App
flutter run	Run in debug mode	Daily
flutter run --profile	Run in profile mode	Performance testing
flutter run --release	Run in release mode	Testing production build
flutter run -d device_id	Run on specific device	Multi-device testing
flutter devices	List available devices	When checking devices
Building
flutter build apk --debug	Build debug APK	Testing
flutter build apk --release	Build release APK	Production
flutter build apk --split-per-abi	Build split APKs (smaller size)	Play Store upload
flutter build appbundle --release	Build App Bundle for Play Store	Play Store upload
flutter build ios --release	Build iOS release	App Store upload
Dependencies
flutter pub get	Install dependencies	After clone/checkout
flutter pub upgrade	Update all packages	Monthly maintenance
flutter pub upgrade package_name	Update specific package	As needed
flutter pub outdated	Check outdated packages	Monthly review
Testing
flutter test	Run all tests	Before PR
flutter test test/widget_test.dart	Run specific test file	During development
flutter test --coverage	Run tests with coverage	CI/CD pipeline
Debugging
flutter doctor	Check environment setup	Setup issues
flutter doctor -v	Verbose environment check	Detailed diagnostics
flutter logs	View app logs	Debugging
flutter attach	Attach to running app	Remote debugging
Cleanup
flutter clean	Clean build cache	Build errors
flutter clean && flutter pub get	Clean and reinstall	Weird build issues
Platform-Specific
flutter open android	Open Android in Android Studio	Android development
flutter open ios	Open iOS in Xcode	iOS development
flutter emulators	List Android emulators	Starting emulator
flutter emulators --launch emulator_id	Launch specific emulator	Testing
xcrun simctl list devices	List iOS simulators	iOS testing
Troubleshooting
killall -9 dart	Kill stuck Dart process	Lock file issues
cd android && ./gradlew clean && cd ..	Clean Android build	Gradle errors
cd ios && pod deintegrate && pod install && cd ..	Reinstall iOS pods	Pod errors

---

⚡ Common Workflows

Workflow	Commands
Start Working	git pull flutter pub get
Before Commit	dart format . flutter analyze
After Model Changes	flutter pub run build_runner build --delete-conflicting-outputs
Build Broken	flutter clean flutter pub get flutter pub run build_runner build --delete-conflicting-outputs

---

🚀 Git Branching Workflow

This document describes the Git branching strategy and workflow for the Gymtaar project.

🔒 Branch Protection Rules

Protected Branches

The following branches are protected and have strict access controls:

• main - Production-ready code
• dev - Testing and staging environment

Protection Policies

✅ No Direct Pushes - No one is allowed to push directly to main or dev
✅ Pull Request Required - All changes must go through pull requests (PRs)
✅ Code Review Required - All PRs must be reviewed before merging
✅ CI/CD Checks - All automated tests must pass before merging

---

🌿 Branching Workflow

1. Branch Hierarchy

main (production)
  ↑
  └── dev (testing/staging)
        ↑
        ├── feature/presence
        ├── feature/profile
        ├── bugfix/login-issue
        └── bugfix/chat-crash

2. Workflow Steps

For Developers

1. Always create branches from dev (never from main)
2. Work on your feature/bug fix in your dedicated branch
3. Create a PR to merge into dev when ready
4. Test thoroughly in dev environment
5. After successful testing, maintainers will create a PR from dev → main

For Maintainers

• Review and merge feature/bugfix PRs into dev
• Test features in the dev environment
• Create PRs from dev → main for production releases

---

📝 Branch Naming Convention

Use descriptive, lowercase names with hyphens as separators.

For New Features

Format: feature/<feature-name>

Examples:

• feature/presence
• feature/profile
• feature/chat-improvements
• feature/realtime-database
• feature/video-call-ui
• feature/subscription-system

For Bug Fixes / Issue Solving

Format: bugfix/<issue-name>

Examples:

• bugfix/localstorage-data
• bugfix/login-refresh-issue
• bugfix/call-not-working
• bugfix/chat-crash
• bugfix/firebase-connection

---

🚀 Workflow Example (Step-by-Step)

Scenario: Adding a new presence tracking feature

Step 1: Checkout the dev branch

git checkout dev

Step 2: Pull latest changes

git pull origin dev

Step 3: Create a new feature branch

git checkout -b feature/presence

Step 4: Write code and commit changes

# Make your changes
git add .
git commit -m "feat: add presence tracking feature"

Commit Message Convention:

• feat: for new features
• fix: for bug fixes
• docs: for documentation
• refactor: for code refactoring
• test: for adding tests

Step 5: Push your branch to remote

git push -u origin feature/presence

Step 6: Create a Pull Request

• Go to GitHub/GitLab
• Create a PR from feature/presence → dev
• Add description of changes
• Request review from team members

Step 7: Code Review & Merge

• Address review comments
• Once approved, merge into dev

Step 8: Testing in Dev

• Team tests the feature in dev environment
• Fix any issues that arise

Step 9: Production Release (Maintainers Only)

• After successful testing, maintainers create PR: dev → main
• Deploy to production

---

📊 Branch Type Reference

Type	Branch Name Example	Purpose	Merges Into
Feature	feature/presence	Add new presence system	dev
Feature	feature/profile	Add profile management	dev
Feature	feature/chat-improvements	Improve chat functionality	dev
Bug Fix	bugfix/localstorage-data	Fix local storage saving issue	dev
Bug Fix	bugfix/login-refresh-issue	Fix login token refresh	dev
Bug Fix	bugfix/call-not-working	Fix video call connection	dev

---

📋 Rules Summary

Rule	Description
🔴 main = Production	Stable, production-ready code only
🟡 dev = Testing	Testing and staging environment
🟢 feature/xxx	New features and enhancements
🔵 bugfix/xxx	Bug fixes and issue resolutions
❌ No Direct Push	Never push directly to dev or main
✅ PR Required	All work must be submitted via Pull Request
🔄 Flow: feature → dev → main	Changes flow through testing before production

---

🛠️ Quick Reference Commands

Starting New Work

# Get latest dev
git checkout dev
git pull origin dev

# Create your branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b bugfix/your-issue-name

Committing Changes

git add .
git commit -m "feat: descriptive commit message"
git push -u origin feature/your-feature-name

Updating Your Branch with Latest Dev

# While on your feature branch
git fetch origin
git rebase origin/dev

# Or use merge if preferred
git merge origin/dev

Cleaning Up After Merge

# After your PR is merged, delete local branch
git checkout dev
git pull
git branch -d feature/your-feature-name

# Delete remote branch (if not auto-deleted)
git push origin --delete feature/your-feature-name

---

⚠️ Important Notes

1. Never commit directly to main or dev - Always use PRs
2. Keep branches focused - One feature or fix per branch
3. Write descriptive commit messages - Help others understand your changes
4. Update your branch regularly - Rebase or merge from dev to avoid conflicts
5. Delete merged branches - Keep the repository clean
6. Test locally first - Don't push broken code
7. Request reviews early - Get feedback while developing

---

🤝 Getting Help

If you have questions about the workflow:

• Ask in the team chat
• Review existing PRs for examples
• Contact the project maintainers

---

Last Updated: December 6, 2024
Maintained By: Gymtaar Development Team