2025 iThome鐵人賽
「 Flutter ：30天打造念佛App，跨平台從Mobile到VR，讓極樂世界在眼前實現！」
Day 4
「 Flutter Git 實戰入門篇—穿越到Coding世界的勇者啊，你需要這套神裝(2) 」

前言

我們昨天已經成功建立本機儲存庫並且完成了第一次提交。
今天我們要先把昨天的神裝元件✨進行強化+1✨！
進一步了解 「儲存庫 Repository」 在Git中扮演的角色。
接著我們就可以來獲取神裝元件(2)，
認識 「gitignore & Conventional Commits 」，
讓我們的儲存庫可以保持乾淨整齊！

Day4 文章目錄：
一、 Repository
二、 gitignore
三、 Conventional Commits

一、儲存庫 Repository

儲存庫 Repository / Repo ，也被稱為 倉庫、代碼庫、版本庫，
用途是儲存程式碼、歷史紀錄和版本資訊。

初始化 Git 建立本機儲存庫後，專案中就可以看見儲存庫，一個叫 .git 的隱藏資料夾。
mac 可以用Finder開啟專案資料夾，按下 cmd + shift + . 顯示所有隱藏資料夾進行查看。

.git 這個隱藏的資料夾，就是本機的儲存庫。
它就像一個隱藏的小世界，在背後幫我們進行專案記錄。
如果把它刪除，我們就會失去專案的歷史紀錄。

二、 gitignore

1. 簡介

.gitignore 是 Git 在專案中的特殊檔案，用來告訴 Git：
「 哪些檔案或資料夾不要被追蹤、不要寫入版本歷史。 」
這麼做可以保持儲存庫乾淨，避免把不必要或機密內容推到遠端。

常見需要忽略的檔案包含：
- 個人設定檔（例如 IDE 設定）
- 敏感資訊（例如 API 金鑰）
- 編譯產物、暫存檔（例如 build/ 資料夾）
編譯產物是程式編譯或執行後自動生成的結果檔，可以隨時重建，
不需要納入版本控制，以免增加儲存庫大小和污染版本歷史。

2. 參考模板

VS Code 建立的 Flutter 專案會自帶一份基礎 .gitignore，
GitHub官方有更完整的Flutter .gitignore模板可以參考使用。

GitHub官方gitignore範本集
連結：https://github.com/github/gitignore

3. 編輯gitignore

打開Flutter專案根目錄的.gitignore

下面是添加段落註解的 GitHub官方 Flutter .gitignore：
可以直接複製使用

# ================================
# 忽略跨語言、跨編輯器的暫存檔或編譯產物
# ================================
*.class
*.lock
*.log
*.pyc
*.swp
.buildlog/
.history

# ================================
# 忽略 Flutter SDK 自身產生的快取、文件、測試資料
# 這些檔案會隨 SDK 或 CI 環境重新生成，不需版控
# ================================
/bin/cache/
/bin/internal/bootstrap.bat
/bin/internal/bootstrap.sh
/bin/mingit/
/dev/benchmarks/mega_gallery/
/dev/bots/.recipe_deps
/dev/bots/android_tools/
/dev/devicelab/ABresults*.json
/dev/docs/doc/
/dev/docs/flutter.docs.zip
/dev/docs/lib/
/dev/docs/pubspec.yaml
/dev/integration_tests/**/xcuserdata
/dev/integration_tests/**/Pods
/packages/flutter/coverage/
version
analysis_benchmark.json

# 套件檔：記錄 multi-root paths，不適合進版控
.packages.generated

# ================================
# 忽略 Flutter / Dart / Pub 相關產物
# ================================
**/doc/api/
.dart_tool/
.flutter-plugins
.flutter-plugins-dependencies
**/generated_plugin_registrant.dart
.packages
.pub-preload-cache/
.pub/
build/
flutter_*.png
linked_*.ds
unlinked.ds
unlinked_spec.ds

# ================================
# 忽略 Android 專案相關檔案與機敏設定
# ================================
**/android/**/gradle-wrapper.jar
.gradle/
**/android/captures/
**/android/gradlew
**/android/gradlew.bat
**/android/local.properties
**/android/**/GeneratedPluginRegistrant.java
**/android/key.properties
*.jks

# ================================
# 忽略 iOS / Xcode 產物與使用者設定
# ================================
**/ios/**/*.mode1v3
**/ios/**/*.mode2v3
**/ios/**/*.moved-aside
**/ios/**/*.pbxuser
**/ios/**/*.perspectivev3
**/ios/**/*sync/
**/ios/**/.sconsign.dblite
**/ios/**/.tags*
**/ios/**/.vagrant/
**/ios/**/DerivedData/
**/ios/**/Icon?
**/ios/**/Pods/
**/ios/**/.symlinks/
**/ios/**/profile
**/ios/**/xcuserdata
**/ios/.generated/
**/ios/Flutter/.last_build_id
**/ios/Flutter/App.framework
**/ios/Flutter/Flutter.framework
**/ios/Flutter/Flutter.podspec
**/ios/Flutter/Generated.xcconfig
**/ios/Flutter/ephemeral
**/ios/Flutter/app.flx
**/ios/Flutter/app.zip
**/ios/Flutter/flutter_assets/
**/ios/Flutter/flutter_export_environment.sh
**/ios/ServiceDefinitions.json
**/ios/Runner/GeneratedPluginRegistrant.*

# ================================
# 忽略 macOS 專案產物
# ================================
**/Flutter/ephemeral/
**/Pods/
**/macos/Flutter/GeneratedPluginRegistrant.swift
**/macos/Flutter/ephemeral
**/xcuserdata/

# ================================
# 忽略 Windows 專案自動生成檔案
# ================================
**/windows/flutter/generated_plugin_registrant.cc
**/windows/flutter/generated_plugin_registrant.h
**/windows/flutter/generated_plugins.cmake

# ================================
# 忽略 Linux 專案自動生成檔案
# ================================
**/linux/flutter/generated_plugin_registrant.cc
**/linux/flutter/generated_plugin_registrant.h
**/linux/flutter/generated_plugins.cmake

# ================================
# 忽略測試覆蓋率報告
# ================================
coverage/

# ================================
# 忽略符號檔與混淆檔（可能含機敏資訊）
# ================================
app.*.symbols

# ================================
# 例外條件：保留必要的專案設定檔
# ================================
!**/ios/**/default.mode1v3
!**/ios/**/default.mode2v3
!**/ios/**/default.pbxuser
!**/ios/**/default.perspectivev3
!/packages/flutter_tools/test/data/dart_dependencies_test/**/.packages
!/dev/ci/**/Gemfile.lock

如果你直接使用 GitHub 官方版本的 Flutter .gitignore，
建議也將下面的內容加進 .gitignore。

因為 GitHub 官方 Flutter .gitignore 只負責忽略與 Flutter 或平台相關的產物，
OS / IDE / 個人設定檔的忽略需要另外補上。
例如：.DS_Store是寫在GitHub官方的Global/macOS.gitignore。

# macOS 
.DS_Store
.atom/
.build/
.svn/
.swiftpm/
migrate_working_dir/

# IntelliJ 
*.iml
*.ipr
*.iws
.idea/

# Dart/Flutter
.pub-cache/

# Symbolication related
app.*.map.json

# Android Studio will place build artifacts here
/android/app/debug
/android/app/profile
/android/app/release

# The .vscode folder contains launch configuration and tasks you configure in
# VS Code which you may wish to be included in version control, so this line
# is commented out by default.
#.vscode/

三、Conventional Commits

1. 簡介

Conventional Commits（提交訊息慣例規範），
定義了 Git commit message 的書寫格式。

一致的Commit格式，我們可以：
-版本歷史更易讀
-快速了解每個 commit 目的及影響範圍
-方便 Code Review 與 Bug 追蹤

2. 組成結構

Conventional Commits 基本格式:

<type>(<scope>): <subject>
# 類型    (範圍) : 簡短說明
# <subject> 建議50字內，並且使用祈使句。

Conventional Commits 範例：

#單元測試：登入 
test(auth): add login unit tests

#新功能：Google 登入 
feat(auth): add login with google

#修復Bug：用戶大頭貼無法顯示
fix(ui): display user's profile photo

3. 常見的變更類型 (commit type)

4. 常見的變更範圍 (commit scope)

scope 是選填，不一定必須寫在commit message

5. Conventional Commits 練習

我們一起練習看看吧！

練習1 用戶資料保存到firebase
練習2 修復帳號頁面沒有顯示userId
練習3 變更啟動畫面的背景色

feat(api): store user info to Firebase
fix(auth): display user ID on account page
style(ui): change launch view background color

Day4 重點回顧