A.5 雲端同步與 GitHub 協作:跨國資產託管與遠端推送

學完本節,你能夠:

  1. 把本地版本庫連到 GitHub,用 git push 上傳、git pull 下載、git clone 複製整個專案。
  2. 說明 git pull 實際上做了哪兩件事,以及推送被拒絕時該怎麼處理。
  3. 判斷哪些資料不能推送到 GitHub,並知道推送後才發現時該怎麼辦。

壹、開場情境:只存在一台筆電裡的報價歷史

📌 以下為教學情境(依實務改編)。

到 A.4 為止,報價表的所有歷史都存在台北業務 Mia 的筆電裡。這帶來兩個問題:

  • 德國業務 Anna 看不到 Mia 的修改,只能等 Mia 寄檔案;她自己的修改也要寄回來,再由 Mia 手動合併。
  • 筆電遺失或硬碟損壞,所有歷史紀錄跟著消失。

本節要解決的問題: 讓台北與德國共用同一份版本庫,各自修改、各自存檔,再透過雲端同步,而且任何一台電腦壞掉都不會失去歷史。


貳、遠端版本庫的運作方式

GitHub 是最常見的 Git 雲端託管服務,可以把版本庫放在網路上,設定成私人(只有受邀的人看得到)或公開。在 Git 裡,這個雲端版本庫叫做遠端(remote),習慣命名為 origin。

flowchart LR T["台北 Mia 的筆電
本地版本庫"] -->|"git push 上傳"| G["GitHub
origin(私人版本庫)"] G -->|"git pull 下載"| T D["德國 Anna 的筆電
本地版本庫"] -->|"git push 上傳"| G G -->|"git pull 下載"| D
指令 方向 做什麼 什麼時候用
git remote add — 登記遠端的網址 第一次連結時
git push 本地 → 雲端 上傳你的新 commit 存檔後要讓同事看到
git fetch 雲端 → 本地 只下載同事的新 commit,不動你的檔案 想先看看再決定
git pull 雲端 → 本地 git fetch + 合併到目前分支 開始工作前同步
git clone 雲端 → 新電腦 下載整個版本庫與全部歷史 新同事第一天

每一台電腦上都有完整的歷史,所以 GitHub 不是唯一的備份;但 GitHub 是團隊約定的「正式版本」所在處。


參、把規則寫下來:什麼可以上雲端?

公司口頭說法 需要追問的問題 寫成規格
「放到 GitHub 上」 公開還是私人? 報價、成本資料一律私人版本庫,只邀請相關人員
「大家都可以改」 可以直接推送到 main 嗎? 本節先允許;A.6 改為必須經過審核
「每天同步」 什麼時候同步? 開始工作前 git pull;下班前 git push
(沒人說) 密碼、API 金鑰可以放進去嗎? 🛑 不行。金鑰另外存放,並把檔名列進 .gitignore

⚠️ 推上去的東西,刪掉也還在歷史裡

如果把 API 金鑰(例如第 1.3 節抓匯率可能用到的金鑰)commit 並推送,之後再刪掉檔案,舊的 commit 裡仍然有它。正確處理是立刻到服務商那裡把金鑰作廢、換一組新的,而不是只刪檔案。


肆、動手做

1. 在 GitHub 建立版本庫並連結

  1. 註冊並登入 GitHub。
  2. 建立新版本庫(New repository),名稱 global-trade-ops,選 Private,不要勾選自動產生 README(避免和本地歷史分岔)。
  3. 複製頁面上顯示的網址,格式像 https://github.com/<你的帳號>/global-trade-ops.git。

如果電腦上安裝了 GitHub 官方命令列工具 gh,也可以請代理代勞:

對代理說:「在我的 GitHub 帳號建立一個叫 global-trade-ops 的私人版本庫,並把它設成這個資料夾的遠端 origin。」

# 方式一:已在網頁建立好版本庫
git remote add origin https://github.com/<你的帳號>/global-trade-ops.git

# 方式二:用 gh 工具建立並連結(需先執行 gh auth login 登入)
gh repo create global-trade-ops --private --source=. --remote=origin

# 確認連結
git remote -v

💡 登入與授權

GitHub 自 2021 年起,不再接受用帳號密碼直接推送。第一次推送時,常見的情況是跳出瀏覽器請你登入 GitHub 並授權(取決於電腦上安裝的憑證管理工具),或改用 gh auth login、個人存取權杖(Personal Access Token)、SSH 金鑰等方式。代理遇到需要登入的畫面時,會停下來等你操作;不要把密碼或權杖貼進對話框。

2. 第一次推送

對代理說:「把 main 推送到 origin,並設定之後預設推送到這裡。」

git push -u origin main

-u 會記住「本地 main 對應雲端 origin/main」,之後只要打 git push、git pull 即可。推送成功後,git status 會顯示:

On branch main
Your branch is up to date with 'origin/main'.

3. 新同事加入:git clone

Anna 被邀請加入版本庫後,在她的電腦上:

對代理說:「把 global-trade-ops 這個版本庫 clone 到我的電腦。」

git clone https://github.com/<帳號>/global-trade-ops.git

她會得到一個 global-trade-ops 資料夾,裡面有全部檔案與完整歷史,遠端 origin 也已自動設定好。

4. 推送被拒絕:先拉再推

Anna 在 terms.md 加了一條付款條件並推送。稍後 Mia 改了 C 款報價,也想推送:

git push
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://github.com/<帳號>/global-trade-ops.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. If you want to integrate the remote changes, use
hint: 'git pull' before pushing again.

GitHub 拒絕的原因:雲端上有 Anna 的新 commit,Mia 的電腦裡還沒有。如果直接覆蓋,Anna 的修改就不見了。

對代理說:「先把雲端的更新拉下來合併,再推送。」

git pull --no-rebase --no-edit
git push

💡 --no-rebase 指定用合併方式整合(若已照 A.2 設定 pull.rebase false 可省略);--no-edit 讓 Git 直接使用預設的合併訊息,不打開編輯器。

git pull 先下載 Anna 的 commit,再與 Mia 的 commit 合併。兩人改的是不同檔案,所以自動合併成功;如果改到同一行,就會出現 A.4 的衝突,照 A.4 的步驟處理即可。

⚠️ 不要用 git push --force 解決被拒絕

強制推送會讓雲端直接變成你的版本,同事已經推上去的 commit 會從 main 上消失。若代理建議使用 --force,請先停下來問清楚原因。


伍、跑跑看、壞給你看

不用真的開兩台電腦:在同一台電腦 clone 兩份到不同資料夾,就能模擬台北和德國。

實驗 操作 預期結果 想想看
① 忘了 push Mia commit 後不推送,Anna 執行 git pull Anna 拿不到 Mia 的修改 commit 和 push 的差別,你能用一句話向主管解釋嗎?
② 拒絕推送 兩人各自 commit,後推的人 git push 出現 [rejected] ... (fetch first) Git 為什麼不讓後推的人直接覆蓋?
③ fetch 不合併 Anna 推送後,Mia 只執行 git fetch 再 git status 顯示 Your branch is behind 'origin/main' by 1 commit 什麼時候你會想先 fetch 而不是直接 pull?
④ 兩人改同一行 兩人都改 A 款價格,後推的人 git pull --no-rebase --no-edit 出現 A.4 的合併衝突 誰該負責解決:先推的人,還是後推的人?

陸、回到情境與小結

現在台北與德國共用同一個私人版本庫:每個人都有完整歷史,誰的筆電壞了都只要重新 clone;同事的修改不會被默默覆蓋,因為 Git 會要求你先合併再推送。

限制 後果 在哪一節解決
任何成員都能直接推送到 main 未經審核的報價直接成為正式版本 A.6 Pull Request 與分支保護
只能看出誰推送、看不出誰核准 出事時無法區分「自己改」與「主管同意後改」 A.6
誰能看、誰能改的權限需要管理 離職員工若沒移除,仍可存取報價 第 9 章 權限與內部控制

本節小結

  1. GitHub 是雲端上的遠端版本庫(origin),push 上傳、pull 下載、clone 複製整個專案。
  2. git pull = git fetch + 合併;推送被拒絕時,先 pull 再 push,不要用 --force。
  3. 公司資料用私人版本庫;密碼與金鑰永遠不進版本庫,誤推後要立刻作廢換新。
  4. 代理遇到登入授權會交給你處理,不要把密碼或權杖貼進對話。

柒、練習

  1. 讀狀態(5 分鐘):git status 顯示 Your branch is ahead of 'origin/main' by 3 commits.,代表發生了什麼事?下一步該做什麼?如果顯示的是 behind ... by 3 commits 呢?
  2. 兩地協作模擬(20 分鐘):在 GitHub 建立一個私人版本庫,在電腦上 clone 成 taipei 與 germany 兩個資料夾。讓兩邊各改一個不同檔案並推送,重現「推送被拒絕 → pull → push」的流程。
  3. 管理反思(討論):公司要求「下班前一定要 push」。請從資料備份、半成品外流、同事干擾三個角度討論這條規則的好處與副作用,並思考 A.3 的分支能怎麼搭配這條規則。

國立臺中科技大學 國際貿易系 / 企業管理系 專用教材

《現代軟體工程:商學院的 AI 系統思維與 Agent 實踐》

作者:陳俊智 博士 Dr. Chun-Chih Chen

本書章節架構改編自陳鍾誠教授(金門大學)開源課程《現代軟體工程》(github.com/ccc115a/se,MIT 授權),內容針對商學院全面改寫與擴充。