GitHub 初學者指南
非官方社群技能。標記 (V) 的事實已與 GitHub 官方文件核對。不構成法律建議。
風格（嚴格遵守）
- 假設使用者一無所知，且不想學習 Git。他們只想要結果。
- 一次只給一個步驟。明確說出他們會看到的按鈕或連結文字。等待他們告知步驟完成後，再給下一步。
- 以一行摘要開頭。只有在被問到時才提供細節。
- 如果他們傳送螢幕截圖，請閱讀並在給出下一步指示前，告知他們目前所在位置。
- 如果你（助手）有儲存庫存取權限可以自行執行該步驟，請主動提出協助。透過適當的工具或登入流程請求存取權限。絕不要求他們將密碼或存取權杖貼到對話中。
1. 建立儲存庫
- 按下 github.com 右上角的 +，然後選擇「New repository」。
- 名稱：簡短、小寫、使用連字號（例如
my-plugin）。 - 選擇 Public（任何人都能看到）或 Private。
- 勾選「Add a README」。從下拉選單中選擇授權條款（參見第 5 節）。
- 按下「Create repository」。
一個空的儲存庫會顯示「Quick setup」頁面，上面有命令列框。初學者可以忽略上面的所有內容，改用「uploading an existing file」連結。
2. 將檔案放入儲存庫（網頁方式，不需 Git）
在儲存庫頁面上：按下「Add file」，然後選擇「Upload files」。接著拖曳檔案或按下「choose your files」。
限制（V：GitHub 文件，Adding a file to a repository）：
- 透過瀏覽器上傳時，每個檔案上限為 25 MiB。
- 每次上傳最多 100 個檔案。
- 更大的檔案（每個最多 100 MiB）需要使用命令列；超過 100 MiB 的檔案需要 Git Large File Storage。
- 受保護的分支無法透過網頁上傳編輯。
- 推送保護可能會封鎖包含支援機密（例如令牌）的檔案。
資料夾：文件說你可以拖曳一個檔案或資料夾。如果使用者的瀏覽器無法接受資料夾，請改用以下其中一種方法：
- 在網頁編輯器中建立資料夾：按下「Add file」->「Create new file」，在名稱方塊中輸入
foldername/filename.md（輸入斜線會建立資料夾），加入內容，然後提交。請檢查目前 UI 的實際行為。 - 解壓縮資料夾，然後分批上傳檔案，保留其資料夾路徑，或使用 GitHub Desktop。
- 如果助手有儲存庫存取權限，讓助手推送檔案。
壓縮檔會以單一檔案形式儲存；GitHub 不會自動解壓縮。請上傳解壓縮後的內容。
最後輸入提交訊息（簡短說明變更內容），然後按下「Commit changes」按鈕。
檢查結果：打開儲存庫頁面，比較檔案列表與預期內容。常見錯誤：檔案被放在根目錄而非其應有的資料夾中。
3. 版本發布與下載（提供使用者下載的內容）
版本發布是基於 Git 標籤的標籤式下載頁面（V：GitHub 文件，About releases）。
- 在儲存庫頁面上按下右側的「Releases」，然後選擇「Draft a new release」。
- 選擇一個標籤，例如
v1.0.0（輸入新標籤名稱，然後按下「Create new tag」）。 - 標題與說明：說明這是什麼、如何三步驟安裝、以及變更內容。
- 將檔案拖曳到資產方塊中。對初學者友善的版本發布應包含針對每個作業系統的建置安裝程式或檔案、一份簡短手冊，以及安裝說明，而非只是單一裸檔或原始碼。
- 按下「Publish release」。
限制（V）：每個檔案小於 2 GiB，每個版本最多 1000 個資產，無總大小或頻寬限制。
版本發布說明範本：
- 這是什麼（一行）
- 下載：選擇你的系統（Windows、macOS、Linux）
- 三步驟安裝
- 每個檔案的校驗碼（SHA-256）
- 已知問題
4. 授權條款與 README 基本概念
- 沒有授權條款的儲存庫不是開放原始碼；其他人沒有重複使用的權利。請審慎選擇。
- MIT：非常寬鬆、簡短。AGPL-3.0 或 GPL：著佐權。基於 JUCE 並使用其開放原始碼選項建置的專案受 AGPLv3 規範（V：JUCE 論壇，工作人員），因此在選擇前請檢查目前的 JUCE 授權條款。
- 絕對不要發布你不擁有權利的第三方檔案（手冊、出廠預設、標誌、二進位檔）。請改用連結方式。
- README 必須回答：這是什麼、如何安裝、如何使用、授權條款、如何回報問題。
5. 避免洩漏私人資訊（最重要）
在首次公開推送前，搜尋每個檔案以及提交身分中是否包含：真實姓名、個人電子郵件、電話、地址、雇主、令牌、密碼、包含使用者名稱的本地路徑。
提交身分：
- 使用 GitHub 的 noreply 地址，可在 Settings -> Emails 中看到，並勾選「Keep my email addresses private」。格式為：
<數字 ID>+<使用者名稱>@users.noreply.github.com。 - 在提交前進行設定：
git config user.name "<使用者名稱>"和git config user.email "<ID>+<使用者名稱>@users.noreply.github.com"。在推送前使用git log --format='%an <%ae>'檢查。 - 當助手代使用者提交時，必須使用此身分，絕不能使用使用者的真實電子郵件。
如果私人資料已公開（V：GitHub 文件，Removing sensitive data from a repository）：
- 如果是憑證，請先撤銷或輪換它。這本身可能就足夠了。
- 使用
git-filter-repo（2.47 或更新版本才有--sensitive-data-removal選項）在本地重寫歷史。使用--invert-paths --path移除檔案，或使用--replace-text取代文字。 - 強制推送以覆寫 GitHub 上的儲存庫。
- 聯絡 GitHub 支援以移除快取檢視和拉取請求引用；提供他們儲存庫名稱、受影響的 PR 數量，以及工具輸出中的首次變更提交。
- 分支複本會保留資料；要求分支擁有者移除它。協作者必須重新基底（rebase），而非合併（merge）。
- 文件警告：其他人的複製會保留資料，而重寫歷史可能會揭示被移除的內容。請假設資料已被看到。
僅修正最近的提交只對分支頂端有效；舊的提交仍可能透過其直接連結被存取，直到 GitHub 清理為止，因此第 4 步驟仍然適用。
5b. 選擇要公開的內容
- 研究筆記、擷取的裝置資料、個人筆記和聊天記錄不屬於公開儲存庫，除非使用者明確表示。
- 在發布任何非為公開而寫的內容之前，請先詢問使用者。
6. 日常任務（一次一個）
- 在網頁上編輯檔案：開啟檔案，按下鉛筆圖示，進行變更，然後提交變更。
- 刪除檔案：開啟檔案，按下三個點，選擇「Delete file」，然後提交。
- 重新命名或移動：編輯檔案名稱方塊，輸入新路徑；然後提交。
- 將儲存庫固定在個人檔案頁面：前往個人檔案頁面，選擇「Customize your pins」。
- 啟用專案網頁（GitHub Pages）：Settings -> Pages，選擇分支和資料夾。請檢查目前的 UI。
- 回報或追蹤問題：使用 Issues 標籤頁。建議為錯誤回報提供議題範本。
7. 當發生錯誤時
- 上傳被拒絕：檢查檔案大小（網頁限制 25 MiB）、檔案數量（100 個），以及是否為受保護的分支。
- 資料夾遺失：檔案被扁平化上傳；透過「Create new file」重新建立路徑，或重新上傳。
- 推送被拒絕並出現機密警告：移除機密、輪換它，然後重試。
- 絕對不要建議停用安全提示。
參考資料
- GitHub 文件，Adding a file to a repository：https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository
- GitHub 文件，About releases：https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
- GitHub 文件，Removing sensitive data from a repository：https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository