分享用 Git 管理 OneDrive 的方法 (OneDrive + Git + mklink) - Windows

這裡分享一下我對 OneDrive 用 Git 配合 Windows 的 mklink 指令做版本管理的方法

環境：

1. 我的電腦系統是 Windows11。
2. 電腦上有登入 Microsoft 帳號的 OneDrive 同步資料夾。
3. OneDrive 上有程式碼，且是多人共用。

雖然我個人是不太喜歡把程式放在 OneDrive 中，因為 OneDrive 沒有像 Git 一樣的管控概念，比較像是注重同步檔案功能的工具而已，雖然 OneDrive 可以去看檔案的各個版本及修改時間，但是沒有辦法像 Git 一樣很方便地看到哪一批檔案在哪個時間、被誰修改、修改了哪幾行。

OneDrive 也沒有辦法像 Git 一樣先對檔案進行修改不要同步，等修改確定後再同步，也沒辦法開 Branch 做多 feature 開發管理。

不過因為公司有特別需求 (比如檔案使用者有非RD人員不會用 Git、檔案很少修改、程式內容不多之類的) 所以在這部份採用了 OneDrive，為了我自己能夠較好的管理對 OneDrive 裡各 feature 需求的版本控管，我開始想方法用 Git 來對 OneDrive 進行管理。

我的需求是：

1. 希望能針對不同的 feature 開發建立 branch 來控管並開發，但各 feature branch 在開發時能不修改到 OneDrive 的檔案，希望等到開發完後才將 branch 的修改 merge 至 OneDrive 中的檔案。
2. 不希望新增目前沒有在 OneDrive 中的不必要檔案，例如 Git 的 .git, .gitnore 等檔案。
3. OneDrive 中的檔案變動 (例如可能別人修改了檔案) 能夠即時的反映在 Git repository 中，方便我知道別人修改了哪些檔案，在 feature branch merge 時能夠被檔下來得到提醒告知之類的，也要有能處理 conflict 的能力。

最後這是我想到的，利用了 Windows mklink 指令來把 Git repository directory 跟 OneDrive 資料夾同步，並配合 Git worktree 做 feature branch 版控的方法，特此分享：

假設 OneDrive 資料夾位置在

C:\Users\<userName>\xxx-onedrive-folder

先建立資料夾，例如: D:\MyOneDriveRepository\masterBranch
用 git init 把資料夾設定成 git repository，假設一開始的 branch 叫做 master。

然後執行以下指令 (/J 代表 Directory Junction)：

mklink /J D:\MyOneDriveRepository\masterBranch\repoLinkToOneDrive C:\Users\<userName>\xxx-onedrive-folder

這樣就會得到一個被建立起來的資料夾：
D:\MyOneDriveRepository\masterBranch\repoLinkToOneDrive

並且 C:\Users\<userName>\xxx-onedrive-folder 和

D:\MyOneDriveRepository\masterBranch\repoLinkToOneDrive
會連結起來成為同步狀態

把 D:\MyOneDriveRepository\masterBranch\repoLinkToOneDrive 連同裡面的檔案都進行第一次的
git commit 就可以開始進行 Git 版本控管了。

因為 OneDrive 可能會跟別人一起合作共用，所以如果在開發新 feature 前我們不希望對 OneDrive 裡的檔案做修改，
也就是說記住不要隨便切換

D:\MyOneDriveRepository\masterBranch

的 branch，讓它永遠在 master branch。

如果有要開發新 feature，我們可以用 git branch <feature branch> 建立新 branch (不要切換過去)，例如新 branch 叫 featureBranch，

用 git branch featureBranch 建立新 branch 後，再利用 git worktree 的方式在另外一個資料夾 checkout featureBranch 去開發，
例如開發路徑是 D:\MyOneDriveRepository\otherBranch\repoLinkToOneDrive，
可以執行

git worktree add D:\MyOneDriveRepository\otherBranch featureBranch

這樣就會得到一個被建立的資料夾：

D:\MyOneDriveRepository\otherBranch

我們就可以在裡面開發 featureBranch 的程式了。

最後等 feature 開發完後，可以再回到

D:\MyOneDriveRepository\masterBranch

用 git merge featureBranch --no-ff

來把 featureBranch merge 至 master branch 來改變 OneDrive 的檔案。

這邊放上一張圖解示意圖，可以更好地理解資料夾 Directory Junction 和 Git worktree 等之間的關係：

這樣的作法有幾點好處：

1. 如果有別人修改了 OneDrive 中的檔案，因為有 Git 管理的關係，我們也可以很容易的發現，例如 git merge 時會因為改到同一個檔案而被擋下來。
2. 可以把別人的修改 commit 至 master branch 做記錄，雖然不能容易地知道哪幾行是何時被誰修改的有點可惜 (還要特別去 OneDrive 網頁裡查 log 有點太麻煩了 )。
3. git 生成出來的 .git 檔案不會被上傳到 OneDrive 上，因為我們是對跟 OneDrive 做 Directory Junction 的資料夾的外層資料夾做 git init，所以 .git 並不在跟 OneDrive 做 Directory Junction 的資料夾之中。

參考資料：

1. 理解 Symbolic Link、Hard Link 與 Directory Junction 的差異之處 | The Will Will Web
2. git worktree 簡單介紹與使用. 現在可以在同一個專案之中，一次開啟多個不同的 branch 了。 | by Jui Yuan Liou | Medium

Python 學習紀錄

-------------------------- Python 本身相關 -----------------------------------------------------

#Python 的安裝位置可以自行決定，通常預設在
C:\Users\<userName>\AppData\Local\Programs\Python\Python313

#在環境中安裝套件 (預設是全局安裝，如果虛擬環境被啟動就會安裝在虛擬環境)
pip install <package名>

# sys.path 是一個列表，Python 在查找 module 時會從這列表中去找。
# 當用 python ./xxx/yyy.py 時，./xxx 會被加到 sys.path 中。
# 當用 python -m xxx.yyy ， . (執行命令時所在的路徑)會被加到 sys.path 中

# -m 參數，把 module 當 script 來執行，後面可接 module name，會把當下執行路徑加到 sys.path 中
#例如：當下在 D:\\my-python，然後要執行 D:\\my-python\\module\\module1.py，命令為
python -m module.module1 (或是 python -m module.module1.py)
#然後因為此時 D:\\my-python 會被加到 sys.path 的關係，在 module1.py 中，就可以直接以 D:\\my-python 為起始目錄來 import 其他 module 了

#為一個專案建立虛擬環境 (virtual environment)，會建立一個<虛擬環境名稱>資料夾，其中包括虛擬環境要用的東西，
並且會把<虛擬環境名稱>的全域路徑加到 sys.path 變數中 (因為是全域路徑，所以我想專案移動檔案位置可能會有問題)
pyton -m venv <虛擬環境名稱>
#例：
python -m venv .venv

#啟動虛擬環境 (有些 IDE 可能可以自動識別 .venv，就不用特別下指令啟動虛擬環境)
source .venv/bin/activate

#輸出當前環境安裝 (全域或是虛擬環境中) 的所有套件及其版本到<requirements 套件 list file path>
pip freeze > <requirements 套件 list file path>
#例：
pip freeze > requirements.txt
#讀取<requirements 套件 list file path> 並在環境中安裝套件
pip install <requirements 套件 list file path>
#例：
pip install -r requirements.txt

#官方的套件依賴配置文件，可取代 requirements.txt
pyproject.toml

#依照 pyproject.toml 安裝套件依賴
#參數： -e: 不要把專案原碼放到 .venv/Lib/site-packages 資料夾中
pip install [-e] .

-------------------------- pipx 工具相關 -----------------------------------------------------
官網

pipx — Install and Run Python Applications in Isolated Environments

pipx 是一個可以安裝及管理 Python 工具的工具，它可將要安裝的 Python 工具安裝到不是全域路徑的位置，方便在不汙染全域環境下較好管理工具。

例如 tool_1 依賴 xxx_package v1 ，但 tool_2 依賴 xxx_package v2，如果都裝在全域下可能就會有衝突問題。
工具安裝位置會像這樣：
不安裝到
C:\Users\<userName>\AppData\Local\Programs\Python\Python313\Lib
改安裝到
C:\Users\<user name>\.local\bin

#安裝 pipx 工具
pip intall [--python <python versoin>] pipx

#用 pipx 安裝並管理其他工具
pipx intall <其他工具>
#例如安裝 uv
pipx intall uv

#例出安裝的所有工具(包括各個的 Python 版本)
pipx list

--------------------------- uv 工具相關 ----------------------------------------------------

官網

uv - An extremely fast Python package and project manager, written in Rust.

uv 是一個可以幫助我們管理專案的套件依賴的工具，隔離各專案避免套件依賴裝在全域造成互相衝突。

#安裝 uv 工具
pip intall uv

#例出管理的 Python
uv python list

#安裝移除特定版本的 Python
uv python install <版本號>
uv python uninstall <版本號>

#設定 uv 預設使用的 Python 版本
uv python pin <版本號>

#初始化專案資料夾
uv init

#建立並使用 venv 虛擬環境，等同 python -m venv .venv 加 source .venv/bin/activate
uv venv

#安裝套件，並修改 pyproject.toml
uv add <套件名>

#移除套件，並修改 pyproject.toml
uv remove <套件名>

#讀取 pyproject.toml、建立虛擬環境 (只有建立沒有啟動)、並安裝依賴
uv sync

#在虛擬環境上下文 (Context) 中執行 Python 檔 (啟動虛擬環境、執行 Python 檔、再退出虛擬環境)
uv run <要執行的 python 檔>

#要使用 -m 參數時，例如要執行 python -m xx.yy.zz.py 時可用
uv run python -m xx.yy.zz

uv build

--------------------------  -----------------------------------------------------