@willh/git-setup/README.md

A utility that helps to setup common Git config and alias settings

# git-setup

本工具會全自動設定 Git 版控環境，並且跨平台支援 Windows, Linux, macOS 等作業系統的命令列環境，尤其針對中文環境經常會出現亂碼的問題都會完美的解決。

## 先決條件

- [Node.js](https://nodejs.org/en/) 10.13.0 以上版本
- [Git](https://git-scm.com/) 任意版本 (建議升級到最新版)

## 使用方式

```sh
npx @willh/git-setup
```

或者直接指定名稱與 Email:

```sh
npx @willh/git-setup --name "Your Name" --email your.email@example.com
```

- 設定過程會詢問你的 `user.name` 與 `user.email` 資訊
  - 如果在命令列中使用 `--name` 與 `--email` 參數，則不會詢問
  - Email 會進行格式驗證，格式錯誤會拒絕設定下去
- 所有 Git 設定都會以 `--global` 為主 (`~/.gitconfig`)
- Windows 平台會自動設定 `LC_ALL` 與 `LANG` 使用者環境變數
  - Linux, macOS 平台會提醒進行設定

## 設定內容

若為 Windows 平台，請記得使用 Command Prompt 執行以下命令，並跳過 Linux/macOS 專屬的命令。

```sh
git config --global user.name  ${name}
git config --global user.email  ${email}

# 設定打錯命令時 3 秒內會自動做出判斷
git config --global help.autocorrect 30

# 設定預設分支名稱為 main
git config --global init.defaultBranch main

# 統一使用 LF 作為行尾字元，避免跨平台協作時的問題
git config --global core.autocrlf input
git config --global core.safecrlf true

# 為了能正確顯示 UTF-8 中文字
git config --global core.quotepath false

# 在命令列環境下自動標示顏色
git config --global color.diff auto
git config --global color.status auto
git config --global color.branch auto

# 常用的 Git Alias 命令
git config --global alias.ci   commit
git config --global alias.cm   "commit --amend -C HEAD"
git config --global alias.co   checkout
git config --global alias.st   status
git config --global alias.sts  "status -s"
git config --global alias.br   branch
git config --global alias.re   remote
git config --global alias.di   diff
git config --global alias.type "cat-file -t"
git config --global alias.dump "cat-file -p"
git config --global alias.lo   "log --oneline"
git config --global alias.ls   "log --show-signature"
git config --global alias.ll   "log --pretty=format:'%h %ad | %s%d [%Cgreen%an%Creset]' --graph --date=short"
git config --global alias.lg   "log --graph --pretty=format:'%Cred%h%Creset %ad |%C(yellow)%d%Creset %s %Cgreen(%cr)%Creset [%Cgreen%an%Creset]' --abbrev-commit --date=short"
git config --global alias.alias "config --get-regexp ^alias\."

# 必須是 Windows 平台才會執行以下設定
git config --global alias.ignore "!gi() { curl -sL https://www.gitignore.io/api/$@ ;}; gi"
git config --global alias.iac "!giac() { git init -b main && git add . && git commit -m 'Initial commit' ;}; giac"
git config --global alias.acp "!gacp() { git add . && git commit --reuse-message=HEAD --amend && git push -f ;}; gacp"
git config --global alias.aca "!gaca() { git add . && git commit --reuse-message=HEAD --amend ;}; gaca"
git config --global alias.cc  "!grcc() { git reset --hard && git clean -fdx ;}; read -p 'Do you want to run the <<< git reset --hard && git clean -fdx >>> command? (Y/N) ' answer && [[ $answer == [Yy] ]] && grcc"

# 必須是 Linux/macOS 平台才會執行以下設定
git config --global alias.ignore '!'"gi() { curl -sL https://www.gitignore.io/api/\$@ ;}; gi"
git config --global alias.iac '!'"giac() { git init -b main && git add . && git commit -m 'Initial commit' ;}; giac"
git config --global alias.acp '!'"gacp() { git add . && git commit --reuse-message=HEAD --amend && git push -f ;}; gacp"
git config --global alias.aca '!'"gaca() { git add . && git commit --reuse-message=HEAD --amend ;}; gaca"
git config --global alias.cc  '!'"grcc() { git reset --hard && git clean -fdx ;}; read -p 'Do you want to run the <<< git reset --hard && git clean -fdx >>> command? (Y/N) ' answer && [[ $answer == [Yy] ]] && grcc"

# 必須是 Windows 平台且有安裝 TortoiseGit 才會設定 tlog 這個 alias
git config --global alias.tlog "!start 'C:\\PROGRA~1\\TortoiseGit\\bin\\TortoiseGitProc.exe' /command:log /path:."

# 必須是 Windows 平台才會將預設編輯器設定為 notepad
git config --global core.editor notepad
```

## 其他調整建議

1. `core.editor`

    在選擇 `git commit` 所使用的文字編輯器時，每個人都有不同的偏好，但是 Git 預設的 `vim` 應該是大多數人不熟悉的，所以這個工具的預設會選擇 `notepad` (記事本) 為主要編輯器，這是因為在 Windows 作業系統上，這是唯一所有人都有的應用程式，不需要額外安裝。

    如果你想調整用 Visual Studio Code 作為預設編輯器，可以執行以下指令：

    ```sh
    git config --global core.editor "code --wait"
    ```

    如果習慣用 Visual Studio Code Insider 版本，可以執行以下指令：

    ```sh
    git config --global core.editor "code-insiders --wait"
    ```

2. `core.autocrlf` 與 `core.safecrlf`

    本工具採用跨平台統一的行尾字元處理方式，設定 `core.autocrlf=input` 與 `core.safecrlf=true`。

    - `core.autocrlf=input`：將工作目錄中的 CRLF 轉換為 LF 後存入版本庫，檢出時保持 LF 不變
    - `core.safecrlf=true`：避免混合行尾字元被意外提交到版本庫

    由於現在大多數 Windows 編輯器都已經能正確處理 LF 字元，這樣的設定可以確保：
    - 版本庫內所有文字檔都使用 LF 行尾（跨平台一致）
    - 避免因不同平台的行尾字元造成的 diff 問題
    - 配合 `.gitattributes` 可以更精確控制特定檔案的行尾處理

    如果因特殊需求需要調整回舊版設定，可以執行：

    ```sh
    git config --global core.autocrlf false
    git config --global core.safecrlf false
    ```

3. `pull.rebase`

    在 `git pull` 時，預設會使用 `merge` 的方式合併分支，但是有些人習慣使用 `rebase` 的方式合併分支，這樣可以讓歷史紀錄更加乾淨，不會有多餘的合併紀錄。

    如果你想調整為 `rebase` 的方式，可以執行以下指令：

    ```sh
    git config --global pull.rebase true
    ```

## .gitattributes 設定建議

為了更精確地控制檔案的行尾字元處理，建議在專案根目錄建立 `.gitattributes` 檔案：

```txt
# --- 基本：自動偵測文字檔並正規化至 LF（倉庫內） ---
* text=auto

# --- 一致化 LF（跨平台工具與 CI 友善） ---
*.sh         text eol=lf
*.bash       text eol=lf
*.zsh        text eol=lf
*.fish       text eol=lf
Makefile     text eol=lf
Dockerfile   text eol=lf
.dockerignore text eol=lf
.editorconfig text eol=lf
.gitattributes text eol=lf
.gitignore   text eol=lf
*.md         text eol=lf
*.txt        text eol=lf
*.json       text eol=lf
*.jsonc      text eol=lf
*.yaml       text eol=lf
*.yml        text eol=lf
*.toml       text eol=lf
*.ini        text eol=lf
*.cfg        text eol=lf
*.properties text eol=lf
*.env        text eol=lf
*.rc         text eol=lf

# 程式碼檔案
*.c          text eol=lf
*.h          text eol=lf
*.cpp        text eol=lf
*.hpp        text eol=lf
*.cc         text eol=lf
*.cs         text eol=lf
*.go         text eol=lf
*.java       text eol=lf
*.kt         text eol=lf
*.kts        text eol=lf
*.js         text eol=lf
*.jsx        text eol=lf
*.ts         text eol=lf
*.tsx        text eol=lf
*.mjs        text eol=lf
*.cjs        text eol=lf
*.py         text eol=lf
*.rb         text eol=lf
*.php        text eol=lf
*.rs         text eol=lf
*.swift      text eol=lf
*.m          text eol=lf
*.mm         text eol=lf
*.scala      text eol=lf
*.r          text eol=lf
*.pl         text eol=lf
*.lua        text eol=lf
*.gradle     text eol=lf

# 標記與前端相關
*.css        text eol=lf
*.scss       text eol=lf
*.less       text eol=lf
*.html       text eol=lf
*.xhtml      text eol=lf
*.xml        text eol=lf
*.svg        text eol=lf

# --- Windows 專用腳本與專案檔案：檢出時使用 CRLF ---
*.bat        text eol=crlf
*.cmd        text eol=crlf
*.ps1        text eol=crlf
*.sln        text eol=crlf
*.vcxproj    text eol=crlf
*.vcproj     text eol=crlf
*.csproj     text eol=crlf
*.vbproj     text eol=crlf
*.props      text eol=crlf
*.targets    text eol=crlf

# --- 二進位檔案：停用行尾與 diff ---
# 影像
*.png  binary
*.jpg  binary
*.jpeg binary
*.gif  binary
*.webp binary
*.ico  binary
*.psd  binary
*.ai   binary
*.eps  binary

# 影音
*.mp3  binary
*.wav  binary
*.flac binary
*.ogg  binary
*.mp4  binary
*.mov  binary
*.avi  binary
*.mkv  binary

# 字型
*.ttf  binary
*.otf  binary
*.woff binary
*.woff2 binary

# 文件與試算表
*.pdf  binary
*.doc  binary
*.docx binary
*.xls  binary
*.xlsx binary
*.ppt  binary
*.pptx binary

# 壓縮與封裝
*.zip  binary
*.7z   binary
*.rar  binary
*.gz   binary
*.bz2  binary
*.tar  binary
*.jar  binary
*.apk  binary
*.ipa  binary

# 執行檔與目標檔
*.exe  binary
*.dll  binary
*.pdb  binary
*.so   binary
*.dylib binary
*.a    binary
*.lib  binary
*.o    binary

# 資料庫與快取
*.sqlite binary
*.db     binary

# --- 降噪：縮小無意義 diff ---
*.min.js -diff
*.min.css -diff
*.map    -diff

# --- 選用：Git LFS（如已啟用，再解除註解） ---
#*.psd filter=lfs diff=lfs merge=lfs -text
#*.mp4 filter=lfs diff=lfs merge=lfs -text
#*.zip filter=lfs diff=lfs merge=lfs -text

# --- 選用：打包時不包含開發輔助檔 ---
#/.github        export-ignore
#/.gitignore     export-ignore
#/.gitattributes export-ignore
#/.editorconfig  export-ignore
```

### 使用方式

- **新專案**

    將上述檔案加入後直接提交，版本庫內會以 LF 正規化文字行尾，檢出時依規則輸出 LF 或 CRLF。

- **既有專案**

    加入 `.gitattributes` 後，執行以下命令套用正規化並提交一次性變更：

    ```sh
    git add --renormalize .
    git commit -m "chore: normalize line endings via .gitattributes"
    ```

## 提供建議

如果您對本工具有任何想法，歡迎到[這裡](https://github.com/doggy8088/git-setup/issues)留言討論！

## 作者資訊

- **Will 保哥**
- 部落格：https://blog.miniasp.com
- 粉絲團：https://www.facebook.com/will.fans
- 線上課程：https://learn.duotify.com

## 相關連結

- [2.7 Git 基礎 - Git Aliases](https://git-scm.com/book/zh-tw/v2/Git-%E5%9F%BA%E7%A4%8E-Git-Aliases)
- [Creating CLI Executable global npm module](https://medium.com/@thatisuday/creating-cli-executable-global-npm-module-5ef734febe32)