# Git Remote 指令整理

[TOC]

`git remote` 命令用於管理 Git 專案中的 **遠端倉庫 (Remote Repositories)**。它提供了查看、添加、重新命名和刪除遠端倉庫的功能。

## 1. 常用指令速查表

| 指令 | 說明 |
| :--- | :--- |
| `git remote` | 列出目前倉庫中已配置的遠端倉庫名稱（如 origin）。 |
| `git remote -v` | 列出已配置的遠端倉庫，並顯示其對應的 URL (Fetch/Push)。 |
| `git remote add <name> <url>` | 新增一個遠端倉庫。指定名稱（通常是 origin）和 URL。 |
| `git remote rename <old> <new>` | 重新命名已配置的遠端倉庫。 |
| `git remote remove <name>` | 刪除指定的遠端倉庫（解除連結，不會刪除遠端實際代碼）。 |
| `git remote set-url <name> <url>` | 修改指定遠端倉庫的 URL (例如從 HTTPS 改為 SSH)。 |
| `git remote show <name>` | 顯示指定遠端倉庫的詳細資訊（含分支追蹤狀況）。 |

---

## 2. 應用實例 (詳細解說)

本章節內容將以 GitHub 作為遠端倉庫來操作。

### 顯示所有遠端倉庫
使用 `git remote -v` 可以查看目前倉庫中配置的列表以及它們的 URL。這在確認你推送 (push) 或拉取 (fetch) 的目標時非常有用。

**操作範例：**
我們先載入一個遠端倉庫，然後查看資訊：

$git clone [https://github.com/tianqixin/runoob-git-test$](https://github.com/tianqixin/runoob-git-test$) cd runoob-git-test
$ git remote -v
origin  [https://github.com/tianqixin/runoob-git-test](https://github.com/tianqixin/runoob-git-test) (fetch)
origin  [https://github.com/tianqixin/runoob-git-test](https://github.com/tianqixin/runoob-git-test) (push)

說明： origin 是 Git 預設給複製 (clone) 下來的遠端倉庫的別名。

顯示特定遠端倉庫的詳細資訊
當你需要檢查分支的追蹤關係（Local ref configured for 'git push'），或者確認遠端分支是否過期時使用。

語法：

git remote show [remote_name]

範例：

$ git remote show origin
* remote origin
  Fetch URL: [https://github.com/tianqixin/runoob-git-test](https://github.com/tianqixin/runoob-git-test)
  Push  URL: [https://github.com/tianqixin/runoob-git-test](https://github.com/tianqixin/runoob-git-test)
  HEAD branch: master
  Local ref configured for 'git push':
    master pushes to master (local out of date)

新增遠端版本庫
如果你是在本地先 git init 建立專案，後來才想上傳到 GitHub，就需要使用此指令。

語法：

Bash

git remote add <remote_name> <remote_url>
<remote_name>：遠端倉庫的別名，習慣上主要倉庫會命名為 origin，但你也可以自定義。

<remote_url>：支援 HTTPS、SSH 或 Git 協定連結。

範例：

# 連結到 Github
$ git remote add origin [e-mail]:tianqixin/runoob-git-test.git

# 第一次推送時加上 -u 參數來建立追蹤關係
$ git push -u origin master
添加後，你就可以使用 git push、git pull 等命令與遠端進行互動。

其他管理命令
刪除遠端倉庫連結：

git remote remove origin

# 或者舊寫法
git remote rm origin

修改倉庫名稱：
git remote rename origin new-origin

## 3. 💡 額外補充：實務開發必備技巧
除了上述基本操作，以下是你在團隊協作或開源專案中很常會用到的補充技巧：

### A. 清理無效的遠端分支參照 (prune)
當遠端（如 GitHub）上的某個分支已經被刪除，但你的本地電腦用 git branch -r 查看時，該分支卻還在列表中。這時就需要「修剪」一下。

# 清理 origin 中已經不存在的遠端分支參照
git remote prune origin
這是一個保持本地環境乾淨非常重要的指令。

### B. 設定雙遠端 (Fork 模式常用)
如果你參與開源專案，通常會有兩個遠端：

==origin==：你 Fork 回來自己的倉庫（你有讀寫權限）。

==upstream==：原始的官方倉庫（你通常只有讀取權限，用來同步最新代碼）。

# 查看現有 origin
git remote -v

# 加入上游倉庫，並命名為 upstream
git remote add upstream [https://github.com/original-owner/repo.git](https://github.com/original-owner/repo.git)

# 確認是否加入成功
git remote -v
# 輸出應包含 origin 和 upstream 兩組

### C. 快速切換 HTTPS 與 SSH
有時候剛開始用 HTTPS Clone 下來，後來想改用 SSH 金鑰驗證以免一直輸入密碼，可以直接修改 URL 而不用刪除重加。

#將 origin 從 HTTPS 改為 SSH
git remote set-url origin [e-mail]:username/repo.git

### D. 查詢遠端倉庫的詳細網址 (不含 push/fetch 標籤)
如果你只想單純取得 URL 用於腳本處理：

git remote get-url origin