GitHub 項目推送與拉取等操作使用隨記

本小記適用于個人項目或組織項目，涵蓋 GitHub 推送、拉取、分支管理、.gitignore 設置等常見需求。

---

1. 將已有本地工程推送至 GitHub 新倉庫

1.1 前提條件

• 本地項目結構完整，已準備好；
• 本地已安裝 Git，配置了用戶名郵箱：

  git config --global user.name "你的用戶名"
  git config --global user.email "你的郵箱"
  

• 已在 GitHub 創建新倉庫（可勾選 README）；

---

1.2 操作步驟

A. GitHub 網站端

1. 登錄 GitHub；
2. 點擊右上角 + → New repository；
3. 填寫倉庫信息；
4. 可選擇勾選 “Add a README file”；
5. 點擊【Create repository】；
6. 復制 HTTPS 地址（如：https://github.com/YourName/RepoName.git）；

B. 本地終端操作

# 在本地的工程目錄下打開終端
cd /你的本地工程目錄 
git init
# 若有.gitignore，可在其中添加工程中可忽略的文件
echo ".metadata/" >> .gitignore   # 忽略 .metadata
git remote add origin https://github.com/YourName/RepoName.git
git pull origin main --allow-unrelated-histories  # 若遠程含 README
git add .
git commit -m "init: 初始化本地項目"
git push -u origin main

---

2. 遠程倉庫含 README，本地合并推送處理

2.1 前提條件

• GitHub 倉庫已初始化 README；
• 本地項目也有初始代碼。

2.2 操作步驟

git pull origin main --allow-unrelated-histories
# 解決沖突后
git add .
git commit -m "merge: 合并遠程 README 與本地代碼"
git push origin main

---

3. 修改本地分支名 master ? main 并同步遠程

3.1 前提條件

• 本地分支仍是默認 master；
• GitHub 新倉庫使用 main 分支。

3.2 操作步驟

git branch -m master main             # 重命名分支
git push -u origin main               # 推送新分支
git push origin --delete master      # 刪除舊遠程分支（可選）
# GitHub 設置：Settings → Branches → 修改默認分支為 main

---

4. 添加 .gitignore 忽略無關目錄或文件

4.1 前提條件

• 項目含 .metadata/、.vscode/ 等非必要文件；

4.2 操作步驟

# 使用echo命令可將非必要文件寫入.gitignore，也可直接打開文件進行寫入
echo ".metadata/" >> .gitignore
echo ".vscode/" >> .gitignore
echo "__pycache__/" >> .gitignore
# 若之前已經添加這些文件，可使用下面命令刪除
git rm -r --cached .metadata
git rm -r --cached .vscode
# 添加最新的.gitignore
git add .gitignore
git commit -m "chore: 更新 .gitignore"
git push

---

5. 推送失敗：權限拒絕（組織倉庫）

5.1 前提條件

• 倉庫歸屬某個組織；
• 你不是組織成員或無寫入權限；
• 報錯信息示例：

  ERROR: Write access to repository not granted.
  

5.2 操作步驟

git remote -v                    # 檢查當前遠程地址
git remote set-url origin https://github.com/OrgName/RepoName.git# 若仍失敗：
## 聯系組織管理員添加你為協作者或團隊成員
## 或 Fork 項目到你賬號下再開發

---

6. 項目結構建議與 .gitignore 示例

6.1 推薦目錄結構

# YourProject是github倉庫名，即推送的最好是本地工程目錄下的內容（而非用工程目錄名包裹的內容），這樣打開github倉庫時映入眼簾的就是內部的重要文件夾，便于閱讀YourProject/
├── README.md
├── .gitignore
├── requirements.txt
├── /src
├── /scripts
├── /config
├── /docs
└── ...

6.2 .gitignore 內容示例

.metadata/
.vscode/
__pycache__/
*.log
.DS_Store

---

7. 在 VS Code 中執行推送流程

7.1 前提條件

• 已在本地安裝 Git；
• VS Code 安裝了官方擴展：GitHub Pull Requests and Issues；
• 項目文件夾已通過 VS Code 打開；

7.2 操作步驟

A. 初始化 Git 倉庫

1. 在 VS Code 左側點擊 Source Control（源代碼管理圖標）
2. 如果尚未初始化，會提示 “Initialize Repository” → 點擊
3. 選擇當前打開的文件夾作為 Git 根目錄

B. 連接 GitHub 倉庫

1. 打開命令面板（Ctrl+Shift+P 或 F1）
2. 輸入并選擇：Git: Add Remote
3. 輸入遠程名稱（一般為 origin）
4. 粘貼 GitHub 倉庫地址（如 https://github.com/YourName/Repo.git）

C. 拉取遠程 README（若遠程已存在）

1. 打開終端（Ctrl+` ）

2. 執行：

   git pull origin main --allow-unrelated-histories
   

D. 添加 .gitignore（忽略無關文件）

1. 在項目根目錄新建 .gitignore 文件

2. 添加如下內容：（示例）

   .metadata/
   .vscode/
   __pycache__/
   

E. 提交代碼

1. 左側 Source Control 看到所有變更
2. 輸入提交信息，如 init: 初始化項目
3. 點擊 √ 圖標（提交）

F. 推送至遠程倉庫

1. 點擊...三點菜單 → Push

2. 若首次推送，自動提示選擇遠程和分支（選 origin/main）

3. 也可在終端執行：

   git push -u origin main
   

---

8. 附錄：常用命令

# 初始化本地倉庫
git init# 添加遠程倉庫
git remote add origin <倉庫地址># 添加所有改動文件
git add .# 提交說明
git commit -m "備注信息"# 推送到遠程分支
git push -u origin main# 拉取并允許無共同歷史
git pull origin main --allow-unrelated-histories# 重命名分支
git branch -m master main

---

9. 總結

本筆記整理了將本地項目推送到 GitHub 的完整流程，主要包括：

1. 本地 Git 初始化與遠程倉庫建立連接；
2. 處理已有 README 的遠程倉庫合并問題；
3. 設置 .gitignore 忽略無關文件；
4. 重命名本地分支為 main 并同步推送；
5. 針對組織倉庫的權限問題做出說明；
6. 補充了 VS Code 下的操作方法，適合圖形化管理項目。

---

筆者能力有限，以上內容難免存在不足和紕漏，僅供參考，各位閱讀時請帶著批判性思維學習，遇到問題多查查，謝謝。