善用開放原始碼的力量～歡迎來到Ubuntu的世界～

Ubuntu 安裝與使用 Git 教學：從 git clone 指令到常見錯誤解決全攻略

開發環境設置
目次

1. 前言

近年來，無論是在軟體開發、學術研究還是個人專案中，「Git」都已成為不可或缺的工具。特別是作為全球廣泛使用的版本控制系統，Git 在團隊協作及開源專案中的程式碼共享與管理方面發揮了重要作用。

本文將以 Ubuntu 這個熱門的 Linux 發行版為例，為初學者詳細介紹如何使用「git clone」指令來複製（clone）Git 儲存庫。
「git clone」是將遠端儲存庫（例如 GitHub 或 GitLab 上公開的專案）完整複製到本地環境時最基本的指令。

Ubuntu 用戶學會活用「git clone」後，不僅可以順利安裝各種開源軟體，也能更有效地建立個人開發環境。
同時，參與團隊協作或社群貢獻也會變得更加便利。

本文將從 Git 的安裝、基本的「git clone」用法，到常見錯誤的解決方式，全面介紹相關操作。
不論你是第一次在 Ubuntu 上接觸 Git，還是希望整理既有知識的使用者，都能在此獲得實用資訊。

2. 前置條件與環境設置

在 Ubuntu 上使用「git clone」前，必須先安裝 Git 本體。此外，初次存取遠端儲存庫時的基本設置與認證準備也很重要。本章將逐步說明環境建置流程。

2.1 Git 的安裝方法

在 Ubuntu 上，可以透過官方儲存庫輕鬆安裝 Git。請開啟終端機並依序執行以下指令：

sudo apt update
sudo apt install git

安裝完成後，請輸入下列指令以確認 Git 是否安裝成功：

git --version

只要能正確顯示版本號，就代表安裝無誤。

2.2 設定使用者名稱與電子郵件

Git 會在記錄檔案變更時保存「誰、什麼時候、做了什麼」。因此，首次使用 Git 時請先設定使用者名稱及電子郵件。

git config --global user.name "你的名字"
git config --global user.email "your.email@example.com"

這個設定只需做一次，日後所有 Git 操作都會套用。如欲針對特定專案另設，可省略 --global，於專案目錄中執行指令。

2.3 選擇與準備認證方式

存取遠端儲存庫時，Git 主要有「HTTPS」與「SSH」兩種認證方式：

  • HTTPS
    像瀏覽器一樣透過 URL 連線。GitHub、GitLab 等近年已停止密碼登入，建議使用 Personal Access Token（PAT）。
  • SSH
    使用公開金鑰與私密金鑰進行認證。安全性高，設定好後無需每次輸入密碼，適合經常使用 Git 的用戶。

2.4 使用 Git Credential Manager（GCM）（視需求而定）

若想更安全、便利地管理密碼或存取權杖（Token），也可以考慮安裝 Git Credential Manager（GCM）。
有了 GCM，可將認證資訊安全儲存，省去每次手動輸入。Ubuntu 可參考官方說明或套件安裝。

至此，Ubuntu 環境下使用「git clone」的前置準備已完成。
下一章將介紹實際執行「git clone」複製儲存庫的步驟。

3. git clone 的基本用法

「git clone」是將遠端儲存庫內容完整複製到本地電腦最基本的指令。當你想使用開源專案或團隊成員建立的儲存庫時，首先就需要執行「git clone」。

3.1 基本指令語法

最簡單的用法如下：

git clone <儲存庫網址>

例如，若要複製 GitHub 上公開的儲存庫：

git clone https://github.com/exampleuser/sample-project.git

執行後，當前目錄下會新建一個「sample-project」資料夾，並下載所有檔案與目錄至其中。

3.2 透過 HTTPS 複製

多數服務會建議用 HTTPS 連線，網址以「https://」開頭。首次操作時，可能會要求輸入認證資訊（如帳號、PAT 等）。

git clone https://github.com/使用者名稱/儲存庫名稱.git

3.3 透過 SSH 複製

若已註冊 SSH 金鑰，可更安全、免密碼地複製。SSH 連線的網址格式如「git@github.com:」開頭。

git clone git@github.com:使用者名稱/儲存庫名稱.git

要使用 SSH 複製，請事先將公開金鑰上傳到 GitHub、GitLab 等。

3.4 複製後的儲存庫結構

執行「git clone」時，除專案檔案外，還會一併複製版本管理資訊所在的「.git」目錄。

  • .git 資料夾
    儲存所有版本歷史與設定，這個資料夾的存在讓該目錄受 Git 管理。
  • 工作目錄
    平時編輯的原始碼、說明文件等。

3.5 複製時注意當前目錄

「git clone」會在執行目錄下產生新資料夾。建議先用 cd 指令切換到想存放的位置再執行。

4. 複製特定分支的方法

一個 Git 儲存庫可能有多個分支。一般「git clone」會複製預設分支（如 main 或 master），但有時你只需某特定分支。本章介紹如何指定分支進行複製。

4.1 使用 –branch 參數

「git clone」有 --branch（或縮寫 -b）選項，可直接指定分支。

git clone --branch 分支名稱 儲存庫網址

例如，要複製「develop」分支：

git clone --branch develop https://github.com/exampleuser/sample-project.git

這樣本地端會直接切換到「develop」分支。

4.2 搭配 –single-branch 使用

預設情況下，git clone 會下載所有分支。加入「–single-branch」後，只抓取指定分支，可節省空間與頻寬。

git clone --branch 分支名稱 --single-branch 儲存庫網址

這方法適合只需功能分支或大型儲存庫時使用。

4.3 複製後再抓取其他分支

若之後想用其他分支，在儲存庫內執行：

git fetch --all

然後切換分支：

git checkout 分支名稱

即可。

4.4 注意事項

  • 私有或有限權限儲存庫，需輸入認證資料。
  • 若指定不存在的分支，會發生錯誤。建議事先查閱分支名稱。

善用「git clone」的多元參數，即可有效率地取得想要的分支。

5. 常見錯誤與解決方式

使用「git clone」時，可能因認證、網路或權限等各種因素導致錯誤。以下整理 Ubuntu 用戶常見錯誤及解決方法。

5.1 HTTPS 認證錯誤與 Personal Access Token（PAT）

近年 GitHub、GitLab 為強化資安，已停用舊式密碼認證，必須使用 Personal Access Token（PAT）。
若複製時遇到如下錯誤：

remote: Support for password authentication was removed...
fatal: Authentication failed for 'https://github.com/...'

請前往 GitHub「Settings」>「Developer settings」>「Personal access tokens」申請 PAT，登入時用帳號與 PAT 替代密碼。

5.2 SSH 認證錯誤與金鑰註冊

若透過 SSH 出現「Permission denied (publickey)」錯誤，通常是 SSH 金鑰未正確註冊所致。

【解決方法】

  1. 在終端機產生 SSH 金鑰（如未有）：
   ssh-keygen -t ed25519 -C "your.email@example.com"
  1. 複製公開金鑰內容：
   cat ~/.ssh/id_ed25519.pub
  1. 於 GitHub/GitLab 的設定畫面新增公開金鑰

完成後即可排除 SSH 認證錯誤。

5.3 儲存庫存取權限錯誤

複製私有儲存庫或組織儲存庫時，如遇錯誤訊息：

fatal: repository 'https://github.com/使用者名稱/儲存庫名稱.git/' not found

【解決方法】

  • 確認儲存庫網址是否正確
  • 檢查帳號是否有權限存取該儲存庫
  • 重新輸入認證資料

5.4 網路相關錯誤

遇到「Connection timed out」、「Could not resolve host」等網路錯誤，通常與網路連線或代理設定有關。

【解決方法】

  • 確認網路連線正常
  • 如有使用 VPN 或代理伺服器，請檢查設定
  • 若為 GitHub 端暫時性障礙，請稍候再試

5.5 其他常見錯誤

  • 目錄已存在
    若資料夾已存在，無法重複複製。請更改目錄名或刪除原有資料夾。
  • 磁碟空間不足
    請確認有足夠剩餘空間。

遇到錯誤時，逐步排查原因，大多都能解決。

6. git clone 的實用參數

「git clone」有多種實用選項，能幫你更有效率地取得必要資料、處理帶有子模組的專案等。本章介紹常用的重要參數。

6.1 –depth 參數（淺層複製）

若不需全數歷史，只需最新紀錄，可用「–depth」參數指定取得的提交數。

git clone --depth 1 https://github.com/exampleuser/sample-project.git

本例僅複製最新一次提交，適用於大型專案或 CI 環境下重視速度者。

6.2 –single-branch 參數

預設會下載所有分支，用「–single-branch」只複製特定分支。
常與「–branch」搭配使用。

git clone --branch develop --single-branch https://github.com/exampleuser/sample-project.git

有助於只抓取所需分支。

6.3 –recursive 參數（子模組一併取得）

Git 儲存庫可包含子模組。複製帶子模組的專案時，建議加「–recursive」。

git clone --recursive https://github.com/exampleuser/sample-project.git

如此主儲存庫及所有子模組會一併複製。若忘記加，也可事後執行：

git submodule update --init --recursive

 

6.4 其他常用選項

  • –origin 選項
    若想將遠端名稱設定為非預設（origin），可加上此參數。
  • 指定資料夾名稱
    想自訂複製後的資料夾名稱，指令最後加上目標資料夾名即可。
  git clone https://github.com/exampleuser/sample-project.git 自訂資料夾名稱

靈活運用多項選項，能大幅提升「git clone」效率與彈性。

7. 使用 GUI 工具進行 git clone

不擅長指令操作或想更直觀管理 Git 時，可利用 GUI（圖形介面）工具。在 Ubuntu 上，有幾款 GUI 工具能輕鬆執行「git clone」。

7.1 常見 GUI 工具介紹

  • Gittyup
    輕量簡單的 Git 客戶端，可從 Ubuntu 官方套件庫或 Flatpak 安裝。
  • Visual Studio Code（VS Code）
    極受開發者歡迎，透過擴充功能能直觀操作 Git。
  • GitKraken
    視覺化操作豐富、功能完整，個人用途免費。

7.2 用 Gittyup 複製儲存庫

  1. 安裝 Gittyup（例如 sudo apt install gittyup 或經 Flatpak）。
  2. 啟動應用程式，點選「Clone Repository」等按鈕。
  3. 輸入儲存庫網址，選擇資料夾，執行即可下載專案。

7.3 用 Visual Studio Code 複製儲存庫

  1. 啟動 VS Code，點擊左側「來源控制」圖示。
  2. 點選上方「Clone Repository」按鈕。
  3. 貼上儲存庫網址並按 Enter，選擇儲存位置即開始複製。
  4. 複製完成後，能直接於 VS Code 內編輯、提交、推送。

7.4 GUI 工具的優點與注意事項

  • 優點
    無需輸入指令，圖形化介面友善，易於上手；差異比較、歷史紀錄一目了然。
  • 注意事項
    各工具功能與介面不盡相同，請依需求選擇。建議初學者可先從 GUI 入門，逐步熟悉指令列操作，提升彈性。

善用 GUI 工具，能讓 Ubuntu 上的「git clone」及各種 Git 操作更直觀高效。結合指令列與圖形介面運用，將大幅提升開發效率。

8. 總結

本文詳細說明了在 Ubuntu 環境下活用「git clone」的基礎到進階方法。
內容涵蓋 Git 安裝流程、HTTPS/SSH 複製、分支管理、實用選項，以及 GUI 工具操作等完整流程。

「git clone」對於導入開源專案、團隊開發或自學都十分重要。熟練掌握後，將能應對各種開發情境、順利推動專案進行。

尤其初學者，建議遇到問題可直接搜尋錯誤訊息或查閱官方文件；漸漸熟悉後，可多加利用進階選項及 GUI 工具，穩步提升技能。

如有未能解決的疑問或遇新問題，歡迎查閱 FAQ、GitHub 官方說明或參考社群討論。
持續結合 Ubuntu 與 Git 的優勢，讓你的開發與學習之路更加順利！

9. FAQ（常見問題與解答）

Q1: 如何在 Ubuntu 安裝 Git？
A1: 請依序於終端機執行下列指令：

sudo apt update
sudo apt install git

安裝後可用 git --version 查詢版本。

Q2: 想只複製特定分支怎麼做？
A2: 使用 --branch（或 -b）選項並指定分支名稱，如：

git clone --branch 分支名稱 儲存庫網址

如需僅抓取該分支，請同時加上 --single-branch。

Q3: 用 HTTPS 複製時出現認證錯誤怎麼辦？
A3: GitHub、GitLab 等已改用 Personal Access Token（PAT）。請至設定頁申請 PAT，於密碼欄位貼上。

Q4: 如何建立 SSH 金鑰並註冊？
A4: 在終端機執行下列指令產生金鑰：

ssh-keygen -t ed25519 -C "your.email@example.com"

然後將 ~/.ssh/id_ed25519.pub 內容註冊至 GitHub/GitLab。

Q5: 如何查詢 clone 下來儲存庫的遠端 URL？
A5: 於儲存庫資料夾內執行：

git remote -v

即可顯示遠端儲存庫網址。

Q6: 若目錄名稱已存在會發生什麼？
A6: git clone 時，如目標目錄已存在會顯示錯誤。請改用其他名稱或刪除舊目錄。

Q7: 如何正確複製帶有子模組的儲存庫？
A7: clone 時加 --recursive 參數：

git clone --recursive 儲存庫網址

如已複製完成，可再執行：

git submodule update --init --recursive

Q8: Ubuntu 上有哪些推薦的 Git GUI 工具？
A8: 推薦 Gittyup、Visual Studio Code（含 Git 擴充）、GitKraken 等，請依需求選擇。

Q9: 複製後想切換其他分支怎麼做？
A9:

git fetch --all
git checkout 分支名稱

即可切換。