Version Control with Subversion

這些會在 Chapter 5, Repository 管理 中討論.

假設你已經正確地安裝 Subversion, 你應該可以開始使用了. 接下來的兩章, 我們會帶領你涵蓋 Subversion 的命令列用戶端程式 svn 的使用.

所有的版本控制系統都必須解決同樣的基本問題: 如何讓使用者分享資料, 但是不讓他們不小心成為彼此的阻礙? 使用者要不小心覆寫掉彼此在檔案庫裡的更動, 實在是太容易了.

考慮一下以下的情景: 假設我們有兩個協同工作人員, Harry 與 Sally. 他們決定同時編輯同一個儲存在檔案庫的檔案. 如果 Harry 先存入檔案庫, (幾個月之後) Sally 很有可能以她自己的新版檔案覆寫過去. 雖然 Harry 的版本並不會就此消失 (因為系統記得每一次的更動), 但是任何 Harry 所作的更動不會出現在 Sally 的新版檔案中, 因為她打從一開始就沒看過 Harry 的更動. 總地來說, Harry 的心血就這麼消失了—至少從該檔案的最新版就遺漏掉了—. 這絕對是我們想要避免的情況!

Figure 2.2. 應避免的問題

許多版本控制系統以鎖定-修改-解鎖的方式 來解決這個問題, 這是個很簡單的解決方案. 在這樣的系統中, 檔案庫在同一時間只允許一個人修改一個檔案. 首先 Harry 必須在他開始更動之前, 先 "鎖定" 該檔案. 鎖定檔案就像從圖書館借書; 如果 Harry 已鎖定一個檔案, 那麼 Sally 就無法對其進行任何更動. 如果她想要鎖定該檔案, 檔案庫會拒絕她的要求. 她所能作的, 就只是讀取這個檔案, 然後等著 Harry 完成他的更動, 解除他設下的鎖定. 在 Harry 解除該檔案的鎖定之後, 他的回合就結束了, 現在輪到 Sally 可以對其進行鎖定並編輯內容.

Figure 2.3. 鎖定-修改-解鎖的解決方案

鎖定-修改-解鎖模型的問題, 在於它的限制多了點, 而且經常會成為使用者的絆腳石:

Subversion, CVS, 還有其它的版本控制系統使用一種 複製-修改-合併的模型, 作為鎖定的取代方法. 在這種模型下, 每一個使用者用戶端會讀取檔案庫, 然後建立檔案或計畫的 工作複本. 然後使用者進行各自的工作, 修改他們自己的私有複本. 最後, 私有複本會合併在一起, 以產生一個新的, 最後的版本. 版本控制系統通常會協助合併的動作, 但是最後人類還是負有讓它能夠產生正確結果的責任.

這裡舉個例子. 假設 Harry 與 Sally 各自從檔案庫 建立同一個專案的工作複本. 他們同時工作, 並對同一個複本中的檔案 "A" 作了修改. Sally 先將她的更動送回檔案庫. 當 Harry 試著要存回他的更動時, 檔案庫會通知他, 他的檔案 A 已經 過時. 換句話說, 檔案庫裡的檔案 A 在他上次產生複本後已經更動過了. 所以 Harry 要求他的用戶端程式, 將檔案庫裡新的更動與他的檔案 A 工作複本 合併 起來. 通常 Sally 的更動與他的更動不會重疊; 所以只要讓兩組更動整合在一起, 他就可以將他的工作複本回存至檔案庫.

Figure 2.4. 複製-修改-合併的解決方案

Figure 2.5. …複製-修改-合併的解決方案 (續)

要是 Sally 的更動真的與 Harry 的更動重疊的話呢? 這該怎麼辦呢? 這種情況稱為 衝突 (conflict), 通常也不會是多大的問題. 當 Harry 要求用戶端程式將最新的檔案庫更動, 合併到他自己的工作複本時, 他自己的檔案 A 會被標示為衝突的狀態: 他可以看到兩邊互相衝突的更動, 然後手動在這兩者之間作選擇. 請注意, 軟體不會自動地解決衝突; 只有人類才有理解能力, 進而作出明智的決定. 當 Harry 手動地解決重疊的更動之後 (也許就是和 Sally 討論這個衝突!), 他就可以安全地將手動合併的檔案存回檔案庫.

複製-修改-合併模型聽起來有點混亂, 但是實務上跑起來可是相當地平順. 使用者可以同時各自工作, 不需等待他人. 當他們同時處理同一個檔案時, 大多數的情況下, 這些同時產生的更動都不會互相重疊; 衝突是相當少見的. 而且解決衝突所需要的時間, 也遠低於鎖定系統所損失的時間.

最後, 這些通通都回歸到一個最重要的因素: 使用者溝通. 當使用者彼此溝通不良時, 語法與語意衝突都會增加. 沒有任何系統能夠強迫使用者完美地溝通, 而且也沒有任何系統能夠偵測出語意衝突. 所以並沒有任何論點, 能夠導出鎖定系統可減少衝突發生的虛假承諾; 實務上, 鎖定系統似乎比其它系統對生產力有更大的傷害.

你已經讀過有關工作複本的部份; 現在我們要示範 Subversion 如何建立並使用它.

Subversion 工作複本就只一個普通的目錄樹, 位於你的本地系統中, 其中包含了一堆檔案. 你可以依你喜好, 自由地編輯這些檔案. 而且如果這些是源碼檔, 你可以依一般的方法編譯它們. 你的工作複本就是你自己的私有工作空間: Subversion 不會將其它人的更動合併進來, 也不會讓你的更動讓他人取得, 除非你明確地要求要這樣作.

你在自己的工作複本檔案中作了一些更動, 並且確認它們都能正常地工作, 此時 Subversion 提供你許多命令, 讓你將這些更動 "發表" 給同一計畫的其他人使用 (藉由寫至檔案庫). 如果別人發表了他們的更動, Subversion 提供你許多命令, 可將這些更動合併至你的工作目錄中 (藉由讀取檔案庫).

工作複本也包含了其它額外的檔案, Subversion 建立並維護這些檔案, 讓它自己可以執行這些命令. 特別一提, 工作複本中的每個目錄都會有一個名為 .svn 的子目錄, 也就是工作複本的 管理目錄. 每個工作目錄中的檔案, 都能夠幫助 Subversion 了解哪些檔案有未出版的更動, 哪些與其他人的工作相比是過時的檔案.

一個典型的 Subversion 檔案庫通常會包含數個專案使用的檔案 (或源碼檔); 一般來講, 每一個專案是檔案庫檔案樹中的子目錄. 在這樣的安排中, 一個使用者的工作複本, 通常對應到檔案庫裡的某一特定的子目錄.

舉例來說, 假設你有一個包含兩個軟體專案的檔案庫.

Figure 2.6. 檔案庫的檔案系統

換句話說, 檔案庫的根目錄有兩個子目錄: paint 與 calc.

要取得一個工作複本, 你必須 取出 (check out) 某個檔案庫裡的子目錄. ("check out" 聽起來有點像是要鎖定或預約某項資源, 但是它不是; 它就只是為你建立一個計畫的私有複本.) 舉個例子, 如果你取出 /calc, 你會得到一個像這樣的工作複本:

$ svn checkout http://svn.example.com/repos/calc
A  calc
A  calc/Makefile
A  calc/integer.c
A  calc/button.c

$ ls -a calc
Makefile  integer.c  button.c  .svn/

這一串字母 A, 表示 Subversion 已經加入幾個物件到你的工作複本之中. 現在你有檔案庫的 /calc 目錄的個人複本, 外加一些額外的東西—.svn— 這裡面有 Subversion 所需的額外資訊, 早先有提到過.

$ svn checkout file:///path/to/repos
…
$ svn checkout file://localhost/path/to/repos
…

C:\> svn checkout file:///X:/path/to/repos
…
C:\> svn checkout "file:///X|/path/to/repos"
…

假設你更動了 button.c. 由於 .svn 目錄會記得檔案的修改日期與原始的內容, Subversion 能夠知道你改了這個檔案. 但是 Subversion 不會讓你的更動公諸於世, 除非你明確地表明要這麼作. 發表你的更動的行為, 通常稱為 送交 (或 存入 (check in)) 更動至檔案庫.

要發表你的更動讓其他人知道, 可以使用 Subversion 的 commit 命令:

$ svn commit button.c
Sending button.c
Transmitting file data..
Committed revision 57.

現在對 button.c 所作的更動, 已經送交至檔案庫了; 如果其他使用者取出 /calc 的工作複本, 他們會在最新版的檔案中看到你的更動.

假設你有個合作伙伴 Sally, 他和你同一時間取出 /calc 的工作複本. 當你送交你對 button.c 的更動, Felix 的工作複本並沒有改變; Subversion 只會依使用者要求來變更工作複本.

要讓她的專案也能跟上變動, Sally 可以藉由使用 Subversion 的 update 命令, 要求 Subversion 更新 他的工作複本. 這會讓你的更動合併到她的工作複本中, 外加他人自上次取出檔案以後所送交的更動.

$ pwd
/home/sally/calc

$ ls -a 
.svn/ Makefile integer.c button.c

$ svn update
U button.c

以上取自svn update命令的輸出, 表示 Subversion 更新了 button.c 的內容. 請注意 Felix 不必指定要更新哪個檔案; Subversion 使用 .svn 目錄與檔案庫裡的額外資訊, 來決定哪些檔案必須更新到最新版.

svn commit的動作, 可以將不限數目的檔案與目錄的更動, 視為單一不可分割的異動以進行發表. 在你的工作複本中, 你可以修改檔案的內容, 建立, 刪除, 更名, 以及複製檔案與目錄, 然後將所有的更動視為一個單位, 一口氣送交回去.

在檔案庫中, 每一次的送交都被視為是一個不可分割的異動: 不是所有送交的更動都成功, 就是全部都不成功. Subversion 會試著維持這樣的不可分割特性, 不管是遭遇程式失敗, 系統當機, 網路有問題, 還是其它使用者進行的動作.

每一次檔案庫接受一個送交的更動, 就會讓檔案樹進入一個新的狀態, 稱之為 修訂版本. 每一個修訂版本都會被賦與一個唯一的, 比前一個修訂版號大一的自然數. 一個新建立的檔案庫的修訂版號為零, 其中除了空的根目錄外, 什麼都沒有.

有一個把檔案庫具象化的好方法, 就是將之視為一系列的樹. 想像有一系列的修訂版號, 自左至右, 由 0 開始. 每一個修訂版號下都有一個檔案系統的樹狀結構, 每一個檔案樹都是每一次送交之後的檔案庫 “快照”.

Figure 2.7. 檔案庫

請特別注意, 工作複本並不見得一定會符合檔案庫某一特定的修訂版; 每個檔案可能會對應到不同的修訂版本. 舉個例子, 假設你的工作目錄, 是從檔案庫登出了 4 號修訂版:

calc/Makefile:4
     integer.c:4
     button.c:4

此時工作目錄對應的是檔案庫的 4 號修訂版. 不過要是你修改了 button.c, 送交這個更動. 假設此時其它人都沒有送交任何更動, 你所送交的更動就會變成檔案庫的第 5 號修訂版, 然後你的工作複本就會變成像這樣:

calc/Makefile:4
     integer.c:4
     button.c:5

假設在這個時候, Sally 送交了 integer.c 的更動, 產生了 6 號修訂版. 如果你以 svn update 更新你的工作目錄, 它看起來就會像這樣:

calc/Makefile:6
     integer.c:6
     button.c:6

Sally 對 integer.c 的更動會出現在你的工作複本中, 而你的更動還是在 button.c 之中. 在這個例子中, 版本 4, 5, 6 的 Makefile 內容都是一樣的, 不過 Subversion 會將工作複本中的 Makefile 標示為版本 6, 表示它還是最新版本. 所以, 在你對工作複本作了一次完整更新之後, 它基本上就是完全對應到檔案庫的某一個版本.

對每個工作目錄中的檔案, Subversion 會在管理區域 .svn/ 中, 記錄兩個重要的資訊:

有了這些資訊, 再藉由諮詢檔案庫, Subversion 就可以決定某個工作檔案是處於下列四個狀態何者之一:

聽起來好像要注意很多東西, 但是 svn status 的命令會顯示任何在工作複本裡的項目的狀態. 欲取得該命令更詳細的資訊, 請參見 the section called “svn status”.

Subversion 的一個基本原則, 就是要盡量地保有彈性. 有一種特別的彈性, 就是工作複本可包含混合修訂版的能力.

一開始可能無法理解, 為什麼這樣的彈性會被視為一項特色, 而不是責任. 在完成至檔案庫的送交動作後, 剛送交的檔案與目錄的修訂版, 會比工作複本其它部份的修訂版還要新. 這看起來有點混亂. 就像我們早先示範過的, 我們永遠都可藉由 svn update, 將工作複本帶回至單一的工作修訂版. 為什麼會有人要 故意 混合不同的工作修訂版呢?

假設你的專案夠複雜, 你發現有時強制將工作複本的某些部份帶回到 “舊版本” 反而更好; 在第 3 章, 你會學到怎麼達成. 也許你想要對早先版本的子模組進行測試, 也許你想要在最新的檔案樹中, 檢視某個檔案幾個過去的版本.

但是, 當你在工作複本中使用混合修訂版時, 這項彈性有幾個限制.

首先, 如果檔案或目錄不全都是最新版本時, 對它們的刪除動作是無法送交的. 如果一個項目在檔案庫中, 存在著比目前更新的版本, 你想要送交的刪除動作會被拒絕, 以防止你不小心毀了還沒看過的更動.

第二, 你無法送交一個對目錄的描述資訊更動, 除非它完全是最新版本的. 你會在第 6 章學到如何將 “性質” 附加到項目. 一個目錄的工作修訂版, 會定義出特定的實體與性質的集合, 因此送交一個對過時目錄的性質更動, 很有可能會毀掉你還沒檢視過的性質.

當你建立了一個新的 Subversion 檔案庫, 它就以修訂版號 0 開始它的生命. 其後的送交動作, 都會讓修訂版號加一. 在你的送交動作完成後, Subversion 用戶端會告知你新的修訂版號:

$ svn commit --message "Corrected number of cheese slices."
Sending        sandwich.txt
Transmitting file data .
Committed revision 3.
      

在未來的某一時間, 如果你想參考到這個版號時 (稍後在本章, 我們會看看如何, 以及為什麼我們會想這樣作), 你可以以 “3” 來指定它.

Subversion 用戶端懂得幾個 修訂版關鍵字. 這些關鍵字可在 --revision 選項中, 用來取代整數引數, 它們將會被 Subversion 轉換成特定的修訂版號:

以下是幾個使用修訂版關鍵字的範例 (如果不懂這些命令, 沒有關係; 藉由本章的引導, 我們會逐步解釋這些命令):

$ svn diff --revision PREV:COMMITTED foo.c
# 顯示最近一次送交 foo.c 所產生的更動

$ svn log --revision HEAD
# 顯示最新的檔案庫送交的記錄訊息

$ svn diff --revision HEAD
# 將工作檔案 (含有本地的修改) 與檔案庫的最新版本作比較

$ svn diff --revision BASE:HEAD foo.c
# 將你的 “原始未更動” foo.c (未含本地修改)
# 與檔案庫裡的最新版本作比較

$ svn log --revision BASE:HEAD
# 顯示自你上次更新後的所有送交訊息

$ svn update --revision PREV foo.c
# 復原上一個 foo.c 的更動
# (foo.c 的工作修訂版本會被減少.)
      

這些關鍵字感覺並不是非常重要, 但是它們可以讓你進行一些常見 (而且有用) 的動作, 而不必先找出確切的修訂版號, 或是記住工作複本確實的修訂版本.

任何你可以指定修訂版號或修訂關鍵字的地方, 你也可以在大括號 “{}” 內指定日期, 就可以指定修訂版日期. 你還可以一起使用日期與修訂版, 以存取檔案庫裡一個範圍的更動.

Subversion 可接受相當多的日期格式— 只要記得將有空白的日期以引號包起來就好. 這裡只是幾個 Subversion 接受的格式的例子而已:

$ svn checkout --revision {2002-02-17}
$ svn checkout --revision {2/17/02}
$ svn checkout --revision {"17 Feb"}
$ svn checkout --revision {"17 Feb 2002"}
$ svn checkout --revision {"17 Feb 2002 15:30"}
$ svn checkout --revision {"17 Feb 2002 15:30:12 GMT"}
$ svn checkout --revision {"10 days ago"} 
$ svn checkout --revision {"last week"} 
$ svn checkout --revision {"yesterday"} 
…
      

當你將日期指定為修訂版時, Subversion 會找出與該日期最接近的檔案庫的修訂版:

$ svn log --revision {11/28/2002}
------------------------------------------------------------------------
r12:  ira | 2002-11-27 12:31:51 -0600 (Wed, 27 Nov 2002) | 6 lines
…
      

你也可以使用一個範圍的日期. Subversion 會找出所有兩個日期之間的修訂版, 包含這兩個日期在內:

$ svn log --revision {2002-11-20}:{2002-11-29}
…
      

就像我們前面指出的, 你也可以混合日期與修訂版號:

$ svn log -r {11/20/02}:4040
      

與一組團隊同時修改同一個專案時, 你會想先 更新 (update) 你的工作複本: 也就是說, 取回同一專案中, 其它發展人員所作的更動. 你可以使用 svn update, 將你的工作複本裡的版本同步至檔案庫的最新修訂版.

$ svn update
U  ./foo.c
U  ./bar.c
Updated to revision 2.
      

在這個例子中, 有人從你上次更新後, 登錄了 foo.c 與 bar.c 所產生的更動, 而且 Subversion 已經更新了工作目錄, 以包含這些新的更動.

讓我們更詳細地檢視 svn update 的輸出. 當伺服器送出更動至你的工作目錄時, 在每一個項目的旁邊, 都有一個字母代碼, 讓你知道 Subversion 會執行什麼動作來更新你的工作目錄.

現在你可以開始工作, 修改工作複本了. 比較好的作法, 是產生特定的一個更動 (或是一組更動), 像是加個新功能, 修正臭蟲等等. 這裡會用到的 Subversion 指令, 有 svn add, svn delete, svn copy, 以及 svn move. 如果你只是要修改一個已在 Subversion 裡的檔案 (或是不只一個檔案), 可能在送交更動前都不會用到這些指令. 你能對工作複本所作的更動:

要產生檔案的更動, 請使用文字編輯程式, 文書處理程式, 圖形程式, 或是你平常使用的任何工具. Subversion 可以很容易地處理二進制檔案, 如同文字檔案一般 —而且一樣有效率.

以下是你最常用來更動目錄結構的四個常用的 Subversion 指令 (我們稍候會講到 svn import 與 svn mkdir).

當你修改完畢後, 你必須將更動送交至檔案庫, 不過在這樣作之前, 先看看自己作了哪些更動, 是個不錯的主意. 在送交前先檢視更動的部份, 讓你可以寫出更清楚的記錄訊息. 你還可能會發現意外更動到的檔案, 這讓你在送交前還有回復這項錯誤的機會. 除此之外, 這也是在發表之前, 仔細檢視並檢查所作的更動的時機. 想要更清楚地了解所作的更動, 你可以藉由 svn status, svn diff, 以及 svn revert 這些命令, 來看看你所作的更動是什麼. 通常你會用前兩個命令, 來找你對工作複本所作的更動, 然後可能用第三個命令來復原這些更動.

Subversion 經過特別調校, 可在不與檔案庫溝通的情況下, 幫你進行以下的工作, 外加許多其它的工作. 尤其是你的工作複本裡, .svn 區域擁有每一個受版本控制的檔案的 “原始未更動” 複本. 也因為如此, Subversion 可以很快地告訴你檔案是如何被更動, 甚至讓你可以取消你所作的變更, 而不需使用到檔案庫.

  L    ./abc.c               # svn 在 .svn 目錄中, 有 abc.c 的鎖定
M      ./bar.c               # bar.c 的內容, 有本地端的變更
 M     ./baz.c               # baz.c 已變更了性質, 但是沒有內容的更動
?      ./foo.o               # svn 並未管理 foo.o
!      ./some_dir            # svn 管理它, 但是不是不見了, 就是不完整
~      ./qux                 # 納入管理的是目錄, 但是這裡是檔案, 或是相反的情況
A  +   ./moved_dir           # 新增項目, 並以來源的歷史紀錄為其歷史紀錄
M  +   ./moved_dir/README    # 新增項目, 使用來源的歷史紀錄, 再加上本地更動
D      ./stuff/fish.c        # 本檔案已預定要被刪除
A      ./stuff/loot/bloo.h   # 本檔案已預定要被新增
C      ./stuff/loot/lump.c   # 這個檔案有因更新而產生的衝突
    S  ./stuff/squawk        # 這個檔案或目錄已切換到分支
        

$ svn status stuff/fish.c
D      stuff/fish.c
        

$ svn status --verbose
M               44        23    sally     ./README
                44        30    sally     ./INSTALL
M               44        20    harry     ./bar.c
                44        18    ira       ./stuff
                44        35    harry     ./stuff/trout.c
D               44        19    ira       ./stuff/fish.c
                44        21    sally     ./stuff/things
A                0         ?     ?        ./stuff/things/bloo.h
                44        36    harry     ./stuff/things/gloo.c
        

$ svn status --show-updates --verbose
M      *        44        23    sally     ./README
M               44        20    harry     ./bar.c
       *        44        35    harry     ./stuff/trout.c
D               44        19    ira       ./stuff/fish.c
A                0         ?     ?        ./stuff/things/bloo.h
        

$ svn diff
Index: ./bar.c
===================================================================
--- ./bar.c
+++ ./bar.c	Mon Jul 15 17:58:18 2002
@@ -1,7 +1,12 @@
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <stdio.h>

 int main(void) {
-  printf("Sixty-four slices of American Cheese...\n");
+  printf("Sixty-five slices of American Cheese...\n");
 return 0;
 }

Index: ./README
===================================================================
--- ./README
+++ ./README	Mon Jul 15 17:58:18 2002
@@ -193,3 +193,4 @@ 
+Note to self:  pick up laundry.

Index: ./stuff/fish.c
===================================================================
--- ./stuff/fish.c
+++ ./stuff/fish.c  Mon Jul 15 17:58:18 2002
-Welcome to the file known as 'fish'.
-Information on fish will be here soon.

Index: ./stuff/things/bloo.h
===================================================================
--- ./stuff/things/bloo.h
+++ ./stuff/things/bloo.h  Mon Jul 15 17:58:18 2002
+Here is a new file to describe
+things about bloo.
        

$ svn diff > patchfile
        

$ svn revert README
Reverted ./README
        

$ svn status foo
?      foo

$ svn add foo
A         foo

$ svn revert foo
Reverted foo

$ svn status foo
?      foo
        

$ svn status README 
       README

$ svn delete README 
D         README

$ svn revert README
Reverted README

$ svn status README
       README
        

我們之前已經看過 svn status -u 如何預測衝突. 假設你執行了 svn update, 然後有趣的事情發生了:

$ svn update
U  ./INSTALL
G  ./README
C  ./bar.c
      

代碼 U 與 G 沒什麼好擔心的; 這幾個檔案都很順利地接受了來自檔案庫的更動. 標示有 U 的檔案, 表示它沒有本地端的更動, 但是更新了檔案庫的更動. G 代表的它已經合併更動, 也就是說有本地端的更動, 但是來自檔案庫的更動並沒有與它重疊.

但是 C 表示有衝突, 也就是說來自伺服器的更動與你的更動有重疊的地方, 而現在你必須手動在這兩者之間作選擇.

不管衝突於哪裡發生, 用戶端的 Subversion 會作三件事:

舉例來說, Sally 對檔案庫中的 sandwich.txt 作了修改. Harry 則剛在他的工作複本中, 修改了這個檔案, 然後將它登錄進去. Sally 在將檔案登錄時, 先執行更新動作, 結果她得到了一個衝突狀況:

$ svn update
C  sandwich.txt
Updated to revision 2.
$ ls -1
sandwich.txt
sandwich.txt.mine
sandwich.txt.r1
sandwich.txt.r2
      

此時, Subversion 將 不 允許你再送交檔案 sandwich.txt, 除非這三個臨時的檔案都被刪除.

$ svn commit --message "Add a few more things"
svn: A conflict in the working copy obstructs the current operation
svn: Commit failed (details follow):
svn: Aborting commit: '/home/sally/svn-work/sandwich.txt' remains in conflict.
      

如果你遇到了衝突, 你必須進行以下三項之一:

當你解決了衝突之後, 你必須執行 svn resolved, 讓 Subversion 知道. 如此會刪除這三個臨時檔案, Subversion 就不會認為這個檔案還是處於衝突的狀態. ^[4]

$ svn resolved sandwich.txt
Resolved conflicted state of sandwich.txt
      

$ cat sandwich.txt
Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2
Creole Mustard
Bottom piece of bread
        

<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======
        

=======
Sauerkraut
Grilled Chickenn
>>>>>>> .r2
        

Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
Salami
Mortadella
Prosciutto
Creole Mustard
Bottom piece of bread
        

$ svn resolved sandwich.txt
$ svn commit -m "Go ahead and use my sandwich, discarding Sally's edits."
        

$ svn update
C  sandwich.txt
Updated to revision 2.
$ ls sandwich.*
sandwich.txt  sandwich.txt.mine  sandwich.txt.r2  sandwich.txt.r1
$ cp sandwich.txt.r2 sandwich.txt
$ svn resolved sandwich.txt
$ svn commit -m "Go ahead and use Sally's sandwich, discarding my edits."
        

$ svn revert sandwich.txt
Reverted sandwich.txt
$ ls sandwich.*
sandwich.txt
        

現在你可以登錄你的更動了. 請注意 svn resolved 並不像本章其它的命令一樣, 它需要一個引數來執行. 不管在什麼情況下, 你必須非常小心, 只有當你非常確定已經解決了檔案中的衝突, 才執行 svn resolved — 當臨時檔案被移除後, 就算檔案中還有衝突標記, Subversion 還是會讓你送交檔案.

終於到這裡了! 你已經完成了你的編輯, 從伺服器合併更動的部份, 並且準備要將你的更動送交至檔案庫.

svn commit 命令會將所有的更動送至檔案庫. 當你送交了一個更動, 你需要給它一個 記錄訊息, 說明一下你的更動. 你的記錄訊息會附在你建立的新修訂版上. 如果記錄訊息很簡短的話, 你可能會希望透過命令列的 --message (或 -m) 選項來指定:

$ svn commit --message "Corrected number of cheese slices."
Sending        sandwich.txt
Transmitting file data .
Committed revision 3.
      

但是如果你是邊工作邊寫記錄訊息的話, 你大概會希望直接告訴 Subversion, 從 --file 選項所指定的檔案來取得記錄訊息:

svn commit --file logmsg 
Sending        sandwich
Transmitting file data .
Committed revision 4.
      

如果你並沒有指定 --message 或 --file, 那麼 Subversion 會自動叫用你偏好的編輯器 (定義於環境變數 $EDITOR 中) 來編輯記錄訊息.

$ svn commit
Waiting for Emacs...Done

Log message unchanged or not specified
a)bort, c)ontinue, e)dit
a
$
        

檔案庫並不會知道, 也不管你的更動是否有意義; 它只會檢查是否有人在你沒注意時, 也修改了你所更動的檔案. 如果有人 也 修改到了, 那麼整個送交就會失敗, 並以一則訊息提示你, 有一個或多個檔案已經過時了:

$ svn commit --message "Add another rule"
Sending        rules.txt
svn: Transaction is out of date
svn: Commit failed (details follow):
svn: out of date: `rules.txt' in txn `g'
$

此時, 你需要執行 svn update, 處理產生的合併或衝突, 然後再試著送交一次.

這樣就涵蓋了 Subversion 的基本工作流程. Subversion 還有許多功能, 可用來管理你的檔案庫與工作複本, 但是我們在本章所介紹的命令, 已足以讓你輕鬆地應付日常工作所需.

要找出某一檔案或目錄的歷史紀錄資訊, 請用 svn log 命令. svn log 可告訴你誰改了檔案或目錄, 該修訂版的日期與時間. 另外, 如果有提供送交時的記錄訊息, 它也會一併顯示出來.

$ svn log
------------------------------------------------------------------------
r3:  sally | Mon, 15 Jul 2002 18:03:46 -0500 | 1 line

Added include lines and corrected # of cheese slices.
------------------------------------------------------------------------
r2:  harry | Mon, 15 Jul 2002 17:47:57 -0500 | 1 line

Added main() methods.
------------------------------------------------------------------------
r1:  sally | Mon, 15 Jul 2002 17:40:08 -0500 | 2 lines

Initial import
------------------------------------------------------------------------
      

請注意預設記錄訊息是以 反向時間順序 顯示的. 如果你希望以特定順序顯示某個範圍的修訂版, 或是僅僅某一個修訂版而已, 請使用 --revision (-r) 選項:

$ svn log --revision 5:19    # 以時間順序, 顯示 5 到 19 的紀錄訊息

$ svn log -r 19:5            # 以反向時間順序, 顯示 5 到 19 的紀錄訊息

$ svn log -r 8               # 顯示修訂版 8 的紀錄訊息
      

你也可以檢視某一個檔案或目錄的訊息歷程. 舉個例子:

$ svn log foo.c
…
$ svn log http://foo.com/svn/trunk/code/foo.c
…
      

這些就 只會 顯示指定檔案 (或是 URL) 變動過的修訂版紀錄訊息.

如果你還想要更多有關於檔案或目錄的資訊, svn log 也有 --verbose (-v) 詳細訊息輸出選項. 由於 Subversion 允許你移動複製檔案或目錄, 追蹤檔案系統內的路徑更動是很重要的, 所以開啟詳細訊息輸出的話, svn log 會在修訂版的輸出中, 包含一串 變動路徑 的列表:

$ svn log -r 8 -v
------------------------------------------------------------------------
r8:  sally | 2002-07-14 08:15:29 -0500 | 1 line
Changed paths:
U /trunk/code/foo.c
U /trunk/code/bar.h
A /trunk/code/doc/README

Frozzled the sub-space winch.

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

$ svn log -r 2
------------------------------------------------------------------------
$
        

我們在前面已經看過 svn diff— 它會以統一差異格式來顯示檔案的差異; 在我們送交至檔案庫之前, 可用來顯示我們對本地的工作複本所作的修改.

事實上, svn diff 總共有 三種 不同的用法:

$ svn diff
Index: rules.txt
===================================================================
--- rules.txt	(revision 3)
+++ rules.txt	(working copy)
@@ -1,4 +1,5 @@
 Be kind to others
 Freedom = Responsibility
 Everything in moderation
-Chew with your mouth open
+Chew with your mouth closed
+Listen when others are speaking
$
        

$ svn diff --revision 3 rules.txt 
Index: rules.txt
===================================================================
--- rules.txt	(revision 3)
+++ rules.txt	(working copy)
@@ -1,4 +1,5 @@
 Be kind to others
 Freedom = Responsibility
 Everything in moderation
-Chew with your mouth open
+Chew with your mouth closed
+Listen when others are speaking
$
        

$ svn diff --revision 2:3 rules.txt 
Index: rules.txt
===================================================================
--- rules.txt	(revision 2)
+++ rules.txt	(revision 3)
@@ -1,4 +1,4 @@
 Be kind to others
-Freedom = Chocolate Ice Cream
+Freedom = Responsibility
 Everything in moderation
 Chew with your mouth closed 
$
        

$ svn diff --revision 4:5 http://svn.red-bean.com/repos/example/trunk/text/rules.txt
…
$
        

如果你想要檢視某一檔案早先的版本, 而不是兩個檔案之間的差異, 你可以使用 svn cat:

$ svn cat --revision 2 rules.txt 
Be kind to others
Freedom = Chocolate Ice Cream
Everything in moderation
Chew with your mouth closed
$
      

你可以將輸出直接重導到一個檔案中:

$ svn cat --revision 2 rules.txt > rules.txt.v2
$
      

你大概在想, 為何我們不使用 svn update --revision 將檔案更新至舊的修訂版. 有幾個理由, 讓我們會想用 svn cat.

首先, 你可能想要使用外部的 diff 程式, 來看一個檔案兩個不同版本之間的差異 (也許是圖形界面的, 也許你的檔案已經是這樣的格式, 輸出統一差異格式是完全沒有意思的). 在這種情況下, 你需要取得舊版本的複本, 重導向至一個檔案中, 然後將它與在你的工作目錄中的檔案一起傳給你的外部 diff 程式.

有的時候直接看整個先前版本的檔案, 要比只看它與其它修訂版的差異要方便得多.

svn list 命令可用來顯示檔案庫的目錄中有什麼檔案, 而不必實際將檔案下載至本地機器中:

$ svn list http://svn.collab.net/repos/svn
README
branches/
clients/
tags/
trunk/
      

如果你想要更詳細的列表, 加上 --verbose (-v) 選項, 就可以取得像這樣的輸出.

$ svn list --verbose http://svn.collab.net/repos/svn
   2755 harry          1331 Jul 28 02:07 README
   2773 sally               Jul 29 15:07 branches/
   2769 sally               Jul 29 12:07 clients/
   2698 harry               Jul 24 18:07 tags/
   2785 sally               Jul 29 19:07 trunk/
      

這些欄位告訴你, 這個檔案或目錄最後一次修改的修訂版, 修改它的使用者, 檔案則會有檔案大小, 上一次更新的日期, 以及該項目的名稱.

除了以上的命令, 你還可以使用 svn update 與 svn checkout, 加上 --revision 選項, 就可以將整個工作複本帶回到 “過去的時間” ^[6]:

$ svn checkout --revision 1729 # 取出修訂版 1729 為新的工作複本
…
$ svn update --revision 1729 # 更新現有的工作複本為修訂版 1729
…
      

當 Subversion 修改你的工作複本時 (或是任何在 .svn 的資訊) 時, 它會試著儘量以安全的方式來進行. 在修改任何東西前, 會先將其意圖寫入一個紀錄檔, 執行紀錄檔裡的命令, 然後刪除紀錄檔 (這很像日誌檔案系統的設計). 如果一個 Subversion 的動作被中斷 (像是你按了 Control-C, 或是機器當掉了), 那麼紀錄檔會繼續存在磁碟之中. 藉由重新執行紀錄檔, Subversion 可以完成先前進行的動作, 而你的工作複本也能回復到一致的狀態.

而這就是 svn cleanup 所作的事: 它會搜尋你的工作複本, 執行任何遺留下來的紀錄檔, 移除動作進行時所使用的鎖定檔. 如果 Subversion 曾說過工作複本的某些地方被 “鎖定” 了, 那麼這就是你該執行的命令. 另外, svn status 也會在被鎖定的項目旁顯示 L:

$ svn status
  L    ./somedir
M      ./somedir/foo.c 

$ svn cleanup
$ svn status
M      ./somedir/foo.c
      

svn import 匯入命令, 是用來將未納入版本控制的檔案樹放進檔案庫的快速方法.

$ svnadmin create /usr/local/svn/newrepos
$ svn import mytree  file:///usr/local/svn/newrepos/fooproject
Adding  mytree/foo.c
Adding  mytree/bar.c
Adding  mytree/subdir
Adding  mytree/subdir/quux.h
Transmitting file data....
Committed revision 1.
      

以上的例子, 是將目錄 mytree 的內容, 直接放至檔案庫的 fooproject 目錄裡:

/fooproject/foo.c
/fooproject/bar.c
/fooproject/subdir
/fooproject/subdir/quux.h
      

建立一個分支相當地容易 — 利用 svn copy 命令, 在檔案庫中建立計劃的複本. Subversion 不僅能夠複製單一檔案, 整個目錄也沒有問題. 既然如此, 你會想要產生一份 /trunk/calc 目錄的複本. 新的複本該放在哪裡? 哪裡都可以 — 這實際上是計劃的原則. 我們假設你所屬團隊的原則, 是將分支置於檔案庫裡的 /branches/calc 區域, 而你想將分支命名為 "my-calc-branch". 你想要建立一個新的目錄 /branches/calc/my-calc-branch, 它一開始為 /trunk/calc 的複本.

建立一份複本有兩種不同的方法. 我們先從麻煩的方法開始, 讓這個概念能夠更清楚. 一開始, 請先取出檔案庫根目錄 (/) 的工作複本:

$ svn checkout http://svn.example.com/repos bigwc
A  bigwc/branches/
A  bigwc/branches/calc
A  bigwc/branches/paint
A  bigwc/trunk/
A  bigwc/trunk/calc
A  bigwc/trunk/calc/Makefile
A  bigwc/trunk/calc/integer.c
A  bigwc/trunk/calc/button.c
A  bigwc/trunk/paint
A  bigwc/trunk/paint/Makefile
A  bigwc/trunk/paint/canvas.c
A  bigwc/trunk/paint/brush.c
Checked out revision 340.

現在, 建立複本就只是將兩個工作複本路徑傳給 svn copy 命令:

$ cd bigwc
$ svn copy trunk/calc branches/calc/my-calc-branch
$ svn status
A  +   branches/calc/my-calc-branch

在這裡, svn copy 命令會將 trunk/calc 工作目錄裡所有的東西複製到 branches/calc/my-calc-branch. 你可以從 svn status 命令看得出來, 新的目錄現在預計要被新增至檔案庫中. 不過請注意字母 A 旁邊的 + 號. 它表示這預計要新增的項目, 實際上是某項目的 複本, 而不是全新的東西. 當你送交你的更動時, Subversion 會在檔案庫複製 /trunk/calc 以建立 /branches/calc/my-calc-branch, 而不是將所有工作複本資料再經由網路重傳一次.

$ svn commit -m "Creating a private branch of /trunk/calc."
Adding      branches/calc/my-calc-branch
Committed revision 341.

現在介紹的是另一個建立分支較容易的方法, 我們該在一開始就告訴你: svn copy 可以處理兩個 URL.

$ svn copy http://svn.example.com/repos/trunk/calc \
           http://svn.example.com/repos/branches/calc/my-calc-branch \
      -m "Creating a private branch of /trunk/calc"

Committed revision 341.

這兩個方法實際上沒什麼差別. 這兩個方法都在修訂版 341 中建立一個新的目錄, 而這個新目錄是 /trunk/calc 的複本. 但是呢, 請注意第二個方法進行的是 立即 送交. ^[7] 這個方法比較容易的原因, 是它不需要你先取出檔案庫的東西. 事實上, 這個技巧甚至不要求你得先有工作複本.

Figure 4.3. 有新複本的檔案庫

現在你已經建立了一個新的計劃分支, 你可以取出新的工作複本, 然後開始使用它:

$ svn checkout http://svn.example.com/repos/branches/calc/my-calc-branch
A  my-calc-branch/Makefile
A  my-calc-branch/integer.c
A  my-calc-branch/button.c
Checked out revision 341.

這個工作複本沒有什麼特殊的地方; 它只是映射出另一個檔案庫的位置. 但是當你送交更動時, Sally 在更新時也不會看到它們. 她的工作複本是在 /trunk/calc.

讓我們假裝一個星期已經過去了, 而我們有以下的送交更動:

現在 integer.c 有兩條獨立的發展支線:

Figure 4.4. 檔案歷史的分支

如果你看看你自己的 integer.c 複本的歷程紀錄, 事情變得滿有趣的:

$ pwd
/home/user/my-calc-branch

$ svn log integer.c
------------------------------------------------------------------------
r343:  user | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines

* integer.c:  frozzled the wazjub.

------------------------------------------------------------------------
r303:  sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98:  sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines

* integer.c:  adding this file to the project.

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

請注意 Subversion 會依時間回溯 integer.c 的歷程紀錄, 直到它被複製之時. (請記得你的分支於修訂版 341 時建立.) 現在看看 Sally 對她自己的檔案複本執行相同命令時, 會發生什麼事:

$ pwd
/home/sally/calc

$ svn log integer.c
------------------------------------------------------------------------
r344:  sally | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines

* integer.c:  fix a bunch of spelling errors.

------------------------------------------------------------------------
r303:  sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98:  sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines

* integer.c:  adding this file to the project.

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

Sally 會看到她自己的修訂版 344 的更動, 但是不會看到你在修訂版 343 的更動. 就 Subversion 的認知, 這兩個送交更動影響的是檔案庫裡不同位置的不同檔案. 但是 Subversion 會 顯示這兩個檔案有共同的歷史. 在修訂版 341 建立分支複本之前, 它們兩個是同一個檔案. 這也是為什麼你和 Sally 兩個都會看到修訂版 303 與 98.

這一節中, 有兩點課題是你應該要記住的.

在前一節中, 我們提到你與 Sally 兩個在不同的分支中, 都修改了 integer.c. 如果你看看 Sally 在修訂版 334 的記錄訊息, 你可以看到她修改了幾個拼字錯誤. 毫無疑問的, 你這相同檔案的複本也還有同樣的拼字錯誤. 很有可能你未來對這個檔案的更動, 是針對有拼字錯誤的地方, 那麼某一天你要合併分支的時候, 也就很有可能會產生衝突. 所以最好是現在就取得 Sally 的更動, 在你開始在同一地方進行大改 之前.

現在該是使用 svn merge 命令的時候. 這個命令結果是很像 svn diff 命令 (這在第 3 章就介紹過了). 這兩個命令都可以比較兩個檔案庫裡物件, 並表示它們之間的差異. 舉個例子, 你可以要求 svn diff 為你顯示 Sally 在修訂版 344 時所作的更動:

$ svn diff -r 343:344 http://svn.example.com/repos/trunk/calc

Index: integer.c
===================================================================
--- integer.c	(revision 343)
+++ integer.c	(revision 344)
@@ -147,7 +147,7 @@
     case 6:  sprintf(info->operating_system, "HPFS (OS/2 or NT)"); break;
     case 7:  sprintf(info->operating_system, "Macintosh"); break;
     case 8:  sprintf(info->operating_system, "Z-System"); break;
-    case 9:  sprintf(info->operating_system, "CPM"); break;
+    case 9:  sprintf(info->operating_system, "CP/M"); break;
     case 10:  sprintf(info->operating_system, "TOPS-20"); break;
     case 11:  sprintf(info->operating_system, "NTFS (Windows NT)"); break;
     case 12:  sprintf(info->operating_system, "QDOS"); break;
@@ -164,7 +164,7 @@
     low = (unsigned short) read_byte(gzfile);  /* read LSB */
     high = (unsigned short) read_byte(gzfile); /* read MSB */
     high = high << 8;  /* interpret MSB correctly */
-    total = low + high; /* add them togethe for correct total */
+    total = low + high; /* add them together for correct total */
 
     info->extra_header = (unsigned char *) my_malloc(total);
     fread(info->extra_header, total, 1, gzfile);
@@ -241,7 +241,7 @@
      Store the offset with ftell() ! */
 
   if ((info->data_offset = ftell(gzfile))== -1) {
-    printf("error: ftell() retturned -1.\n");
+    printf("error: ftell() returned -1.\n");
     exit(1);
   }
 
@@ -249,7 +249,7 @@
   printf("I believe start of compressed data is %u\n", info->data_offset);
   #endif
   
-  /* Set postion eight bytes from the end of the file. */
+  /* Set position eight bytes from the end of the file. */
 
   if (fseek(gzfile, -8, SEEK_END)) {
     printf("error: fseek() returned non-zero\n");

svn merge 幾乎是完全一樣的. 但是它不會在終端機上顯示差異, 而是直接當成 本地修改 套用到你的工作複本上:

$ svn merge -r 343:344 http://svn.example.com/repos/trunk/calc
U  integer.c

$ svn status
M  integer.c

svn merge 的輸出, 顯示了你的 integer.c 複本已經修補過了. 它現在包含了 Sally 的更動 — 這個更動從主幹 "複製" 到你的私有分支內, 並以本地修改的形式存在. 此時, 你可檢視本地的更動, 確認它沒有問題.

在另一個場景中, 事情可能就不會這麼順利, 使得 integer.c 進入了衝突的狀態. 你必須使用標準的步驟 (參見第 3 章) 來解決衝突, 如果你認為合併根本不是個好主意的話, 直接捨棄它, 以 svn revert 來回復本地更動.

不過假裝你已經檢視過合併的更動, 你可以一如往常地使用 svn commit 來送交更動. 此時, 這個更動就被合併到你的 檔案庫分支. 在版本控制的術語中, 這個在不同的分支之間複製更動的動作, 稱為 移植 更動.

$ svn diff -r 343:344 http://svn.example.com/repos/trunk/calc > patchfile
$ patch -p0  < patchfile
Patching file integer.c using Plan A...
Hunk #1 succeeded at 147.
Hunk #2 succeeded at 164.
Hunk #3 succeeded at 241.
Hunk #4 succeeded at 249.
done

有件事要提醒一下: 雖然 svn diff 與 svn merge 的概念很類似, 但是它們在許多情況下的語法並不相同. 請閱讀第 8 章, 或是使用 svn help 以了解細節. 舉個例子, svn merge 需要一個工作複本路徑作為目標, 也就是要套用檔案樹更動的地方. 如果目標沒有指定的話, 它會假設你要執行以下的動作之一:

如果你要合併一個目錄, 但是沒有指定目標路徑的話, svn merge 會假設第一種情況, 試著將更動套用到目前的工作目錄中. 如果你要合併一個檔案, 而那個檔案 (或同名檔案) 存在於目錄的工作目錄中, 那麼 svn merge 會假設第二種情況, 並試著將更動套用到同名的本地端檔案.

如果你要讓更動套用到別的地方, 你要這樣下:

$ svn merge -r 343:344 http://svn.example.com/repos/trunk/calc my-calc-branch
U   my-calc-branch/integer.c

合併更動聽起來很簡單, 但是實務上, 它可能讓你很頭痛. 問題在於如果你將更動從一個分支重覆複製到另一個分支的話, 你很有可能不小心合併相同的更動 兩次. 如果發生的話, 有可能並不會出什麼問題. 當 Subversion 套用更動時, 一般來說, 它會幫你記住這個檔案是已經有這個更動, 如果有的話, 不會發生任何事. 不過這個已套用的更動已經被更動的話, 你就會得到衝突. 理想的狀況下, Subversion 會自動防止重覆套用更動.

這是個困擾許多版本控制軟體的問題, 包括 CVS 與 Subversion. 目前而言, 在 Subversion 中, 唯一防止這個問題的方法, 就是記錄哪些更動已經合併了, 哪些還沒. 當你建立一個分支目錄時, 你必須記錄它是從哪個修訂版產生出來的 — 自己建立在別的地方. 當你合併一個修訂版 (或是一個範圍的修訂版) 到工作複本時, 你也得把它們記錄下來. 如果你忘了任何一個這樣的資訊, 你可以利用 svn log -v 分支目錄 的輸出來重新找出這個資訊. 但是這裡的重點, 是每一個後續的合併必須小心翼翼地手動建立, 以確定之前合併過的修訂版不會再重新合併一遍.

當然囉, Subversion 預計在發行版 1.0 之後, 再來解決這個問題. 所有這樣的合併資訊可以在性質描述資料中找到 (參見 the section called “性質”), 這樣 Subversion 有一天就能夠自動地防止重覆的合併.

要讓我們所舉的實例更完整, 讓我們把時間往後拉. 幾天過去了, 主幹與你的私人分支都有了許多更動. 假設你已經完成你的私有分支; 它該有的功能, 或是臭蟲修正終於完成了, 現在你想把分支裡所有的更動都合併回主幹, 讓別人也能享用.

所以, 這種情況我們該如何使用 svn merge 呢? 請記住這個命令會比較兩個檔案樹, 然後把更動套用到工作複本去. 所以要接收這些更動, 你需要有主幹的工作複本. 我們假設你手邊還有一份 (完全更新的), 或者你已取出一份新的 /trunk/calc 工作複本.

但是要比較哪兩個檔案樹? 隨便一想, 答案似乎很明顯: 比較最新的主幹樹與你最新的分支樹就好了. 但是注意 — 這個想法是 錯的, 而且重創不少初學者! 由於 svn merge 的行為與 svn diff 相似, 比較最新的主幹與分支樹並 不會 直接給你你對分支所產生的更動: 它不只顯示出你新加入的分支更動, 還會 移除 你從未在分支作過的主幹更動.

想要表達只在你的分支中產生的更動, 你必須比較分支的初始狀態, 以及其最終狀態. 對你的分支執行 svn log , 你可以發現分支是在修訂版 341 產生的. 而分支的最終狀態, 只要使用修訂版 HEAD 即可.

那麼, 這就是最後的合併手續:

$ cd trunk/calc

$ svn merge -r 341:HEAD http://svn.example.com/repos/branches/calc/my-calc-bran
ch
U   integer.c
U   button.c
U   Makefile

$ svn status
M   integer.c
M   button.c
M   Makefile

[examine the diffs, compile, test, etc.]

$ svn commit -m "Merged all my-calc-branch changes into the trunk."
…

再一次地, svn copy 又來解救眾生了. 如果你想要建立一個完全符合 HEAD 修訂版的 /trunk/calc 的快照, 那就建立一個它的複本:

$ svn copy http://svn.example.com/repos/trunk/calc \
           http://svn.example.com/repos/tags/calc/release-1.0 \
      -m "Tagging the 1.0 release of the 'calc' project."

Committed revision 351.

這個例子假設 /tags/calc 的目錄已經存在了. 在複製動作完成後, 新的 release-1.0 目錄就永遠是這個計劃的快照, 完全符合你建立複本時的 HEAD 修訂版的內容. 當然囉, 你可能想要更準確地指定你所複製的修訂版, 以免別人在你沒注意時, 又送交了幾個更動. 所以如果你知道 /trunk/calc 的 350 修訂版, 就是你想要的快照的話, 你可以藉由傳給 svn copy 命令的 -r 350 選項來指定它.

不過先等一下: 這個建立標記的步驟, 不是和我們用來建立分支的步驟是一樣的嗎? 沒錯, 事實上, 根本就是一樣的. 在 Subversion 中, 標記與分支是沒有任何分別的. 兩者都只是透過複製而建立的尋常目錄而已. 就像分支一樣, 被複製的目錄之所以為 "標記", 只是因為 人們 決定它是: 只要沒有人再送交更動到這個目錄中, 它就永遠是個快照而已. 如果有人開始送交更動進去, 它就會變成一個分支.

如果你管理一個檔案庫的話, 有兩種方法可以用來管理標記. 第一個方法是 "放任": 把它視為計劃的原則, 決定標記放置的位置, 確定所有的使用者都知道如何處理複製進去的目錄. (也就是說, 確定他們都知道別送交更動進去.) 第二個方法就很偏執: 你可以利用 Subversion 內附的存取控制的腳本檔, 讓別人只能在標記區域建立新的複本, 但是無法送交東西進去. (###cross-ref a section that demonstrates how to use these scripts?). 不過呢, 偏執的方法並不是那麼必要的. 如果一個使用者不小心送交更動到標記目錄, 你只要像前一節所講的, 把它回復回來即可. 畢竟, 這可是版本控制軟體.

有的時候, 你想要你的 "快照" 要比單一修訂版的單一目錄要來得複雜一點.

舉例來說, 假設你的計劃比我們的 calc 例子要大得多: 也許它包含了幾個子目錄, 以及許多的檔案. 在你工作之間, 你可能決定要建立一個工作複本, 它有特定的功能, 以及特定的臭蟲修正. 想要達到這樣的目的, 你可以藉由選擇性地將檔案與目錄固定在某一個修訂版, (大方地使用 svn update -r), 或是將目錄與檔案切換到某一個分支 (使用 svn switch). 當你完成之後, 你的工作複本就會變成來自不同版本的不同檔案庫位置的大雜燴. 但是在測試過後, 你確定這就是你需要的資料組合.

現在是作快照的時候了. 這裡無法將一個 URL 複製到另一個去. 在這個情況中, 你想要建立一個你現在調整的工作複本的快照, 並將它存到檔案庫中. 很幸運的, svn copy 事實上有四種不同的使用方法 (你可以參考第 8 章), 包括將工作複本的檔案樹複製到檔案庫的功能:

$ ls
./    ../   my-working-copy/

$ svn copy my-working-copy http://svn.example.com/repos/tags/calc/mytag

Committed revision 352.

現在在檔案庫中, 有了一個新的目錄 /tags/calc/mytag, 它就是完全符合你的工作複本的快照 — 混合的修訂版, url, 所有的東西.

有別的使用者找出這個功能的有趣用法. 有的情況下, 你的工作複本可能有一群本地更動, 而你想讓你的協同工作者看看. 除了執行 svn diff, 將修補檔送過去以外 (這沒辦法捕捉到檔案樹的變化), 你可以改用 svn copy 來 "上載" 你的工作複本至某一個檔案庫的私有區域. 你的協同工作者就可以取出一個一模一樣的工作複本, 或是利用 svn merge 來接收你所作的更動.

管理檔案庫有數種標準建議的方法. 大多數人會建立一個 trunk 的目錄來放置 "主要" 的發展途徑, 建立一個 branches 目錄來放置分支複本, 以及建立一個 tags 目錄來放置標記複本. 如果一個檔案庫只放置一個計畫, 那麼大多數的人會建立這樣的最頂層目錄:

/trunk
/branches
/tags

如果一個檔案庫包含了多個計劃, 那麼人們建立目錄配置的方法, 會以分支為準:

/trunk/paint
/trunk/calc
/branches/paint
/branches/calc
/tags/paint
/tags/calc

…或是依計劃:

/paint/trunk
/paint/branches
/paint/tags
/calc/trunk
/calc/branches
/calc/tags

當然囉, 你還是有忽略這些常用配置的自由. 你可以自己建立各種變化, 只要最能符合你與你的團隊需要即可. 請記住, 不管你作什麼樣的選擇, 都不表示就永遠都不可變更. 不管何時, 你都可以重新整理你的檔案庫. 由於分支與標記只是普通的目錄, 你可以利用 svn move 命令來移動或更名這些目錄. 從一種配置換到另一種, 只是對伺服端進行一連串的移動而己; 如果你不喜歡檔案庫現在的目錄結構, 直接動它們吧.

另一個Subversion 模型的特色, 就是分支與標記可以是有限生命週期的, 就像其它受控管的項目一樣. 舉個例子, 假設你最後完成了個人 calc 計劃分支裡的工作. 在將你所有的更動送交回 /trunk/calc 後, 你的私有分支目錄就沒有必要再存在了:

$ svn delete http://svn.example.com/repos/branches/calc/my-calc-branch \
             -m "Removing obsolete branch of calc project."

Committed revision 375.

現在, 你的分支就消失了. 它當然不是真的不見了: 這個目錄只是從 HEAD 修訂版消失, 不會再引起別人的注意. 如果你檢視更早一點的修訂版 (使用 svn checkout -r, svn switch -r, 或是 svn list -r), 你還是可以看到以前的分支.

如果只是瀏覽被刪除的目錄還不夠, 你還是可以再讓它回來. Subversion 要恢復舊資料相當地容易. 如果你想把被刪除的目錄 (或檔案) 叫回 HEAD 修訂版, 只要使用 svn copy -r 將它從以前的修訂版複製回來就好了:

$ svn copy -r 374 http://svn.example.com/repos/branches/calc/my-calc-branch \
                  http://svn.example.com/repos/branches/calc/my-calc-branch

Committed revision 376.

在我們的例子中, 你的個人分支有個滿短的生命週期: 你可能只是把它建立起來, 用來修正臭蟲, 或是實作一個新的功能. 在工作完成後, 這個分支也沒有存在的必要了. 不過在軟體發展的過程中呢, 長時間同時有兩個 "主要" 的發展主線也是很常見的. 舉個例子, 假設現在該對外發佈一個穩定的 calc 的版本, 而你也知道大概要花好幾個月才能把臭蟲都清掉. 你不想讓別人對這個計劃加新功能, 但是你也不想叫所有的發展人員都停止工作, 所以你改為計劃建立一個不會有太大變更的 "stable" 分支:

$ svn copy http://svn.example.com/repos/trunk/calc \
         http://svn.example.com/branches/calc/stable-1.0
         -m "Creating stable branch of calc project."

Committed revision 377.

現在設計人員可以繼續自由地將最先進的 (或實驗性的) 功能加到 /trunk/calc 中, 你也可以宣佈 /branches/calc/stable-1.0 只接受臭蟲修正的計劃原則. 也就是說, 大家還是可以繼續對主體工作, 但是選擇性將臭蟲修正移植到穩定分支去. 就算在穩定分支已經送出去了, 你可能還是得繼續維護該分支很長一段時間 — 換句話說, 只要你繼續為客戶支援該發行版本, 就得繼續維護.

就概念來講, Subversion 的檔案庫是一連串的目錄樹. 每一個目錄樹, 就是檔案庫的目錄與檔案於不同時間點的快照. 這些快照是使用者進行作業的結果, 稱為修訂版.

每一個修訂版, 是以異動樹 (transaction tree) 開始其生命週期. 在送交發生時, Subversion 用戶端會建立一個異動, 其中反映了本地端的更動 (以及自用戶端開始進行送交的任何額外更動), 然後指示檔案庫將該樹儲存為下一個快照. 如果送交成功的話, 這個異動就會實際成為新的修訂版樹, 並被賦與新的修訂版號. 如果送交因為某些原因失敗的話, 這個異動會被捨棄, 用戶端會被通知該動作失敗.

更新的動作也類似這樣. 用戶端會建立一個暫時的異動樹, 反映工作複本的狀態. 接著, 檔案庫會將異動樹與指定的修訂版樹作比較 (通常是最新的, 或是 “最年輕的” 樹), 然後送回指示用戶端該如何進行何種更動的資訊, 以將工作複本轉換成該修訂版樹的樣子. 在更新完成後, 這個暫時的異動樹就會被刪除.

使用異動樹, 是對檔案庫的版本控制檔案系統產生永久更動的唯一方法. 但是, 了解異動的生命週期極富彈性是很重要的. 在更動的情況下, 異動只是馬上會被消滅的暫時檔案樹而已. 在送交的情況下, 異動會變成固定的修訂版 (如果失敗的情況下, 則是被移除). 如果有錯誤或是臭蟲的話, 異動很有可能不小心遺留在檔案庫之中 (雖然不會影響什麼東西, 但是會佔用空間).

理論上, 某一天整個流程能夠發展出對異動生命週期能夠有更細部的控制. 可以想像一下成一個系統, 在用戶端已經描述完它對檔案庫所產生的更動後, 每個無法成為修訂版的異動會先放到某個地方. 如此, 每個新的送交就可以被某個人檢閱, 也許是主管, 也許是工程品管小組, 他們可以決定是要接受這個異動成為修訂版, 還是捨棄它.

這些跟檔案庫管理有什麼關係呢? 答案很簡單: 如果你要管理一個 Subversion 的檔案庫, 除了監控檔案庫的情況外, 你還必須檢視修訂版與異動情況.

Subversion 檔案庫的異動與修訂版也可以附加性質上去. 這些性質只是基本的鍵值對應, 可以用來儲存與對應檔案樹有關的資料. 這些鍵值與你的檔案樹資料一樣, 都是儲存在檔案庫的檔案系統之中.

對於儲存某些檔案樹的資料, 但是這些資料並不完全與這些目錄與檔案相關時, 修訂版與異動性質是很有用的 — 像是不被用戶端工作複本管理的性質. 例如, 當一個新的送交異動於檔案庫中建立時, Subversion 會對這個異動新增一個名為 svn:date 的性質 — 一個用來表示異動何時建立的時間戳記. 當送交程序結束後, 而該異動被提昇為一個固定的修訂版時, 這個檔案樹會再多出儲存修訂版作者的使用者名稱性質 (svn:author), 以及一個用來儲存該修訂版的紀錄訊息性質 (svn:log).

修訂版與異動性質都是 無版本控制的性質 (unversioned property) — 因為它們被修改後, 原先的值就永遠被捨棄了. 另外, 雖然修訂版樹本身是不會再變的, 附加在它們上的性質卻不是. 你可以在日後對修訂版性質作新增, 移除, 以及修改的動作. 如果你送交了一個新的修訂版, 但是日後發現紀錄訊息寫錯了, 或是有拼字錯誤的話, 你可以直接以正確的新訊息蓋過 svn:log 的值.

掛勾 (hook) 是某些檔案庫事件所觸發的程式, 像是建立新的修訂版時, 修改未納入版本控制的性質時. 每一個掛勾都會得到足夠的資訊, 可以分辨出得到的是什麼事件, 針對哪個 (哪些) 目錄, 以及被誰觸發. 依掛勾輸出或傳回狀態的不同, 掛勾程式可以繼續, 停止, 或是暫停該動作.

hook 子目錄中, 預設是放置各個檔案庫掛勾的範本.

$ ls repos/hooks/
post-commit.tmpl          pre-revprop-change.tmpl
post-revprop-change.tmpl  start-commit.tmpl
pre-commit.tmpl           

每一個 Subversion 檔案庫實作出來的掛勾, 都各自有對應的範本, 只要檢視這些範本的內容, 你就知道每一個命令稿是被什麼觸發的, 什麼資料會傳給命令稿. 每個範本還包含包含一些範例, 示範如何與其它的 Subversion 隨附工具一同完成某些常見工作. 要安裝一個真正可用的掛勾程式, 只要把可執行檔案或命令稿置於 repos/hooks 目錄下, 並且讓它能以掛勾的名稱 (像是 start-commit 或 post-commit) 執行即可.

在 Unix 平台上, 這表示提供與掛勾完全同名的命令稿或是程式即可 (可以是 shell 命令稿, Python 程式, 編譯過的 C 二進制程式, 或是任何的可能). 當然囉, 範本檔案存在的目的, 並不只有提供資訊而已 — 在 Unix 平台上安裝掛勾最簡單的方法, 就是把適當的範本拷貝成去掉 .tmpl 副檔名的新檔案, 修改掛勾的內容, 然後確定命令稿是可執行的. 但是 Windows 是利用檔案副檔名來決定它是不是可執行檔, 所以你必須提供主檔名為掛勾名稱的程式, 再加上 Windows 認為是可執行檔的副檔名, 像是視為程式的 .exe 或 .com, 以及批次檔的 .bat.

目前 Subversion 檔案庫實作的掛勾有五個:

Subversion 會試著以正在存取 Subversion 檔案庫的使用者身份來執行掛勾程式. 在大多數的情況下, 檔案庫是透過 Apache HTTP 伺服器與 mod_dav_svn 存取的, 所以使用者會與 Apache 執行的使用者身份相同. 掛勾程式本身必須以作業系統層級的權限進行設定, 以便讓使用者可以執行. 另外, 這也表示任何會被掛勾程式直接或間接存取的檔案或程式 (包括 Subversion 檔案庫本身), 都會以同一個使用者的身份來進行存取. 換句話說, 請注意任何因檔案權限而可能造成的潛在問題, 以免掛勾無法進行你想進行的工作.

Berkeley DB 環境有它自己預設的設定值, 像是任何時間可使用的鎖定數目, 或是 Berkeley 日誌記錄檔的截止大小等等. Subversion 檔案系統的程式會額外地為幾個 Berkeley DB 設定選項選擇其它的預設值. 不過, 你的檔案庫可能會有自己獨特的資料集合與存取型態, 也許就需要不同的設置選項數值.

Sleepycat (Berkeley DB 的製造廠商) 的人員瞭解不同的資料庫有不同的需求, 所以他們提供了一種執行時期的機制, 可以更動許多 Berkeley DB 環境的設定選項數值. Berkeley 會檢查每個環境目錄是否存在著一個名為 DB_CONFIG 的檔案, 然後剖析其中的為某個特定 Berkeley 環境所用的選項.

檔案庫的 Berkeley 設定檔位於 db 環境目錄中, 也就是 repos/db/DB_CONFIG. Subversion 在建立檔案庫時, 就會自行建立這個檔案. 這個檔案一開始包含了幾個預設值, 也包含了幾個 Berkeley DB 線上文件的參照, 這樣你可以自己去查這些選項所代表的意義. 當然囉, 你可以任意在 DB_CONFIG 檔案裡加入任何支援 Berkeley DB 選項. 不要請記得, 雖然 Subversion 不會試著去讀取或解讀這個檔案的內容, 或是使用任何裡面的選項, 你還是得避免某些設定選項, 讓 Berkeley DB 產生出 Subversion 不知如何處理的行為. 另外, 對 DB_CONFIG 的更動並不會馬上生效, 除非你回復了資料庫環境 (使用 svnadmin recover.)

一般來講, 在你的 Subversion 檔案庫依你需要作好設定之後, 就不需要太多的注意. 但是有的時候還是會需要管理員的介入. svnadmin 工具提供了幾個有用的功能, 可幫助你進行以下的工作:

也許 svnadmin 最常使用的子命令是 setlog. 當一個異動送交到檔案庫, 並且提升成為修訂版之後, 關聯到新修訂版的描述紀錄訊息 (由使用者提供) 會被儲存為附加到修訂版的未納入版本控制的性質. 換句話說, 檔案庫只會記得該性質的最新值, 直接捨棄前一個值.

有的時候, 使用者的紀錄訊息會出錯 (也許是拼錯字, 或是寫錯資訊). 如果檔案庫設定為 (使用 pre-revprop-change 與 post-revprop-change 掛勾; 請參照 the section called “Hook scripts”) 送交之後還可以接受紀錄訊息的更動, 那麼使用者可以利用 svn 程式的 propset 命令 (請參照 Chapter 8, 完整 Subversion 參考手冊), 從遠端 “修正” 紀錄訊息. 但是呢, 因為有永遠失去資訊的可能, Subversion 檔案庫的預設設定是不允許更動未納入版本控制的性質 — 除非由管理員為之.

如果紀錄訊息必須由管理員來更正, 這可由 svnadmin setlog 來達成. 這個命令會修改檔案庫中, 指定修訂版的紀錄訊息 (svn:log 性質), 並且由提供的檔案中讀取新值.

$ echo "Here is the new, correct log message" > newlog.txt
$ svnadmin setlog myrepos newlog.txt -r 388

另一個 svnadmin 常用的用法, 就是查詢檔案庫中未處理的 — 有可能是已經不再使用了的 — Subversion 異動. 在送交注定失敗的時候, 異動一般都會被清除, 也就是說, 異動本身會自檔案庫移除, 任何與該異動有關 (也只有與其有關) 的資料會被移除. 但是有的時候, 發生的錯誤不會清除異動. 發生的原因有幾種: 也許用戶端的動作被使用者無預期中斷, 或是網路在運作之中突然中斷等等. 不管原因為何, 這些未處理的異動只會分散檔案庫, 只會佔用資源而已.

你可以使用 svnadmin 的 lstxns 命令, 列出目前未處理異動的名稱.

$ svnadmin lstxns myrepos
19
3a1
a45
$

產生的輸出中, 每一個項目都可以供 svnlook 使用 (以及它的 --transaction 選項), 看看是誰建立這個異動, 何時建立, 異動中有哪種類型的更動 — 換句話說, 就是這些異動是不是可以安全地被移除! 如果這樣的話, 異動的名稱可以傳給 svnadmin rmtxns, 用來清除異動. 事實上, rmtxns 子命令可以直接以 lstxns 的輸出作為輸入.

$ svnadmin rmtxns myrepos `svnadmin lstxns myrepos`
$

如果你像這樣使用這兩個子命令的話, 你應該考慮暫時不讓用戶端存取檔案庫. 如此, 在你開始進行清除之前, 沒有人可以進行有效的異動. 以下是簡單的 shell 命令稿, 可以快速地產生每一個檔案庫裡的未處理異動的資訊:

#!/bin/sh

### 產生 Subversion 檔案庫中, 未處理異動的相關訊息.

SVNADMIN=/usr/local/bin/svnadmin
SVNLOOK=/usr/local/bin/svnlook

REPOS=${1}
if [ x$REPOS = x ] ; then
  echo "usage: $0 REPOS_PATH"
  exit
fi

for TXN in `${SVNADMIN} lstxns ${REPOS}`; do 
  echo "---[ Transaction ${TXN} ]-------------------------------------------"
  ${SVNLOOK} info ${REPOS} --transaction ${TXN}
done

你可以以 /path/to/txn-info.sh /path/to/repos 來使用前面的命令檔. 這個輸出基本上是 svnlook info 輸出區塊合併起來而已 (請參考 the section called “svnlook”), 看起來就像這樣:

$ txn-info.sh myrepos
---[ Transaction 19 ]-------------------------------------------
sally
2001-09-04 11:57:19 -0500 (Tue, 04 Sep 2001)
0
---[ Transaction 3a1 ]-------------------------------------------
harry
2001-09-10 16:50:30 -0500 (Mon, 10 Sep 2001)
39
Trying to commit over a faulty network.
---[ Transaction a45 ]-------------------------------------------
sally
2001-09-12 11:09:28 -0500 (Wed, 12 Sep 2001)
0
$

一般來講, 如果你看到一個沒有關聯紀錄訊息的無效異動, 這是一個失敗的更新 (或類似更動) 作業的結果. 這些動作是偷偷使用 Subversion 異動來模仿工作複本的狀態. 由於它們並不打算送交, Subversion 並不要求這些異動要有紀錄訊息. 有紀錄訊息的異動幾乎可以肯定是某種失敗的送交. 還有, 異動的日期戳記可以提供一些有趣的資訊 — 舉個例子, 一個九個月前開始的作業, 仍為有效的可能性有多大?

簡單地說, 是否要清除異動的決定不可輕率為之. 不同的資料來源 — 包括 Apache 的錯誤與存取紀錄, 成功的 Subversion 送交紀錄, 諸如此類的 — 都可以用來幫助你作決定. 最後, 管理員常常只要簡單地跟疑似異動的擁有者溝通 (像是透過電子郵件), 就可以確定這個異動實際上是處於僵屍狀態.

為了要保護檔案庫中的資料, 資料庫後端使用了鎖定的機制. 這個機制保證不會同時有多個資料庫存取者同時修改資料庫的某一部份, 而資料從資料庫讀取出來時, 每一個行程都會看到資料是在正確的狀態. 當一個行程需要修改資料庫裡的東西, 首先會檢查目標資料是否有鎖定. 如果資料沒有被鎖定的話, 行程就會鎖定資料, 產生它想要的更動, 然後解除鎖定. 另一個行程會被迫等待, 直到鎖定解除之後, 它才可以繼續存取該部份的資料庫.

在使用 Subversion 檔案庫的過程中, 嚴重的錯誤 (像是磁碟空間, 或是可用的記憶體耗盡) 或中斷會導致行程沒有機會移除它在資料庫產生的鎖定, 結果就是後端資料庫會 “卡住”. 當這樣的情況發生時, 任何存取檔案庫的嚐試都會無限期停住 (因為每一個新的存取者都在等鎖定解除 — 而這件事不會發生).

如果你的檔案庫發生這樣的情況, 首先請勿慌張. Subversion 的檔案系統充份地利用了資料庫的異動, 檢查點, 以及事先寫入日誌的優點, 以確保只有最嚴重的災難事件 ^[12] 才會永久地毀壞資料庫環境. 一個夠偏執的檔案庫管理員會作出某種形式的 off-site 檔案庫備份, 但是還別忙著找你的系統管理員將磁帶回存回來.

第二, 使用以下的步驟, 試著 “解開” 卡住的檔案庫:

這個程序幾乎能夠解決所有檔案庫鎖死的情況. 請確定你以擁有與管理資料庫的身份來執行這個命令, 而不是只以 root 執行. 修復程序的某些部份會從新建立數個資料庫檔案 (舉例來說, 共用的記憶體部份). 以 root 重建的話, 這些檔案將為 root 所擁有, 這表示就算你重新開放檔案庫供人存取, 一般的使用者也無法存取它.

如果前述的步驟因為某些原因而無法解開你的檔案庫, 你應該作兩件事. 首先, 將已損壞的資料庫移到別的地方, 然後回存最新的備份. 然後, 寄一封電子郵件到 Subversion 發展人員郵件論壇 (在 <dev@subversion.tigris.org>), 詳細地描述你的問題. 對 Subversion 的發展人員來說, 資料完整性有著極高的優先權.

Subversion 檔案系統將其資料散佈在數個資料庫表格之中, 通常只有 Subversion 管理員了解 (也只有他們想了解). 但是有的時候, 我們需要將所有的資料, 或是部份的資料, 集合在單一可移植的平面檔. Subversion 提供這樣的機制, 由兩個 svnadmin 子命令實作出來: dump 以及 load.

傾印與載入 Subversion 檔案庫的最常見原因, 就是 Subversion 本身的改變. 隨著 Subversion 日漸成熟, 有時會因後端資料庫 schema 的改變, 導致 Subversion 與前一版的檔案庫不相容. 當你升級遇到這樣的相容性問題時, 我們建議以下列簡單的步驟來進行:

svnadmin dump 會以 Subversion 自訂的檔案系統傾印檔格式, 輸出一個範圍的檔案庫修訂版. 傾印檔格式會輸出到標準輸出串流, 而資訊訊息會送至標準錯誤串流. 這讓你可以將輸出串流轉向到一個檔案, 但是還能在終端機看到狀況輸出. 舉個例子:

$ svnlook youngest myrepos
26
$ svnadmin dump myrepos > dumpfile
* Dumped revision 0.
* Dumped revision 1.
* Dumped revision 2.
…
* Dumped revision 25.
* Dumped revision 26.

作業結束之後, 你會有一個檔案 (在前述的例子中, 就是 dumpfile), 其中包含所有儲存於要求的檔案庫修訂版範圍的資料.

相對的另一個子命令是 svnadmin load, 它會將標準輸入串流以 Subversion 檔案庫傾印檔案進行剖析, 可以有效地將這些傾印的修訂版重播到目標的檔案庫. 它也會提供資訊訊息, 但是這次是送到標準輸出串流:

$ svnadmin load newrepos < dumpfile
<<< Started new txn, based on original revision 1
     * adding path : A ... done.
     * adding path : A/B ... done.
     …
------- Committed new rev 1 (loaded from original rev 1) >>>

<<< Started new txn, based on original revision 2
     * editing path : A/mu ... done.
     * editing path : A/D/G/rho ... done.

------- Committed new rev 2 (loaded from original rev 2) >>>

…

<<< Started new txn, based on original revision 25
     * editing path : A/D/gamma ... done.

------- Committed new rev 25 (loaded from original rev 25) >>>

<<< Started new txn, based on original revision 26
     * adding path : A/Z/zeta ... done.
     * editing path : A/mu ... done.

------- Committed new rev 26 (loaded from original rev 26) >>>

請注意, 因為 svnadmin 使用標準輸入與輸出串流, 作為傾印與載入作業, 膽子很大的人可以這樣試試 (可能還在管道兩旁使用不同版本的 svnadmin):

$ svnadmin create newrepos
$ svnadmin dump myrepos | svnadmin load newrepos

我們在前面說過, svnadmin dump 會輸出一個範圍的修訂版. 透過 --revision 選項, 可以指定傾印單一修訂版, 或是一個範圍的修訂版. 如果你省略這個選項, 所有檔案庫裡的現有修訂版都會被傾印出來.

$ svnadmin dump myrepos --revision 23 > rev-23.dumpfile
$ svnadmin dump myrepos --revision 100:200 > revs-100-200.dumpfile

雖然 Subversion 會傾印所有的修訂版, 它只會輸出夠用的資訊, 讓後來的載入程式可以依此來進行重建. 換句說, 對任何一個傾印檔裡的修訂版來說, 只有在該修訂版被更動的項目會出現在傾印檔中. 本規則的唯一例外, 就是目前 svnadmin dump 命令所輸出的第一個修訂版.

Subversion 預設並不會將第一個傾印的修訂版, 以可用於一個修訂版的差異輸出. 第一, 在傾印檔中並沒有前一個修訂版! 第二個, Subversion 無法得知後來載入傾印檔時 (如果真的有的話), 載入它的檔案庫的狀態為何. 要確定每一次 svnadmin dump 都能自己自給自足的話, 預設第一個傾印出來的修訂版會完整地表示出該檔案庫修訂版的目錄, 檔案, 以及性質.

但是, 你可以變更這樣的預設行為. 如果在傾印檔案庫時, 加上了 --incremental 選項, svnadmin 會將檔案庫的第一個傾印修訂版, 與檔案庫中前一個修訂版作比較, 就像其它被傾印的修訂版的處理方法一樣. 第一個修訂版的輸出, 就像傾印檔裡其它的修訂版輸出一樣 — 只會顯示該修訂版的更動部份而已. 這樣的好處, 是你可以建立幾個可連續載入的小傾印檔, 而不是一個很大的, 像這樣:

$ svnadmin dump myrepos --revision 0:1000 > dumpfile1
$ svnadmin dump myrepos --revision 1001:2000 --incremental > dumpfile2
$ svnadmin dump myrepos --revision 2001:3000 --incremental > dumpfile3

這些傾印檔可以透過下列一連串的命令, 載入到新的檔案庫中:

$ svnadmin load newrepos < dumpfile1
$ svnadmin load newrepos < dumpfile2
$ svnadmin load newrepos < dumpfile3

另一個可以透過 --incremental 選項的技巧, 就是你可以把新範圍的傾印修訂版附加至現有的傾印檔. 舉個例子, 你可能有一個 post-commit 掛勾, 它就會附加觸動它的修訂版的傾印內容. 或是你可以每晚執行像下面的命令稿, 將檔案庫中, 自上一次執行後新增的修訂版附加至傾印檔.

#!/usr/bin/perl -w

use strict;

my $repos_path  = '/path/to/repos';
my $dumpfile    = '/usr/backup/svn-dumpfile';
my $last_dumped = '/var/log/svn-last-dumped';
 
# Figure out the starting revision. Use 0 if we cannot read the
# last-dumped file, else use the revision in that file incremented
# by 1.
my $new_start = 0;
if (open LASTDUMPED, $last_dumped)
  {
    my $line = <LASTDUMPED>;
    if (defined $line and $line =~ /^(\d+)/)
      {
        $new_start = $1 + 1;
      }
    close LASTDUMPED;
  }

# Query the youngest revision in the repos.
my $youngest = `svnlook youngest $repos_path`;
defined $youngest && $youngest =~ /^\d+$/
  or die "$0: 'svnlook youngest $repos_path' cannot get youngest revision.\n";
chomp $youngest;

# Do the backup.
system("svnadmin dump $repos_path --revision $new_start:$youngest --incremental >> $dumpfile.tmp") == 0
  or die "$0: svnadmin dump to '$dumpfile.tmp' failed.\n";

# Store a new last-dumped revision.
open LASTDUMPED, "> $last_dumped.tmp"
  or die "$0: cannot open '$last_dumped.tmp' for writing: $!\n";
print LASTDUMPED "$youngest\n";
close LASTDUMPED
  or die "$0: error in closing '$last_dumped.tmp' for writing: $!\n";

# Rename to final locations.
rename("$dumpfile.tmp", $dumpfile)
  or die "$0: cannot rename '$dumpfile.tmp' to '$dumpfile': $!\n";
rename("$last_dumped.tmp", $last_dumped)
  or die "$0: cannot rename '$last_dumped.tmp' to '$last_dumped': $!\n";

# All done!

以這樣子使用的話, svnadmin 的 dump 與 load 命令就成了相當有用的工具, 可進行檔案庫更動的備份, 以避免系統當機, 或是其它災難事件所帶來的損害.

最後, 另一個 Subversion 檔案庫傾印檔案格式的可能應用, 就是從不同的儲存機制, 或是不同的版本控制系統進行轉換. 因為傾印檔案格式絕大部份都是人類可懂的, ^[13]

從現代電腦誕生以來, 不過技術有多進步, 有件事情還是很不幸地一直不變 — 有的時候, 事情會有非常非常嚴重的問題. 電力中斷, 網路斷線, 爛掉的記憶體, 墜毀的硬碟, 無論管理員是如何努力作好他們的工作, 還是有可能會遇到這些暗黑命運的魔爪. 所以我們遇到了最重要的課題 — 如何備份你的檔案庫的資料.

基本上, Subversion 檔案庫管理員可以使用兩種備份 — 漸進式與完整式. 我們在本章稍早的章節曾討論過, 如果使用 svnadmin dump --incremental 來進行漸進式備份 (請參見 the section called “匯入檔案庫”). 基本上, 它的概念就是只備份自上次製作備份後, 一定時間內的檔案庫更動.

就跟字面上的意思一樣, 檔案庫的完整備份是整個檔案庫目錄 (這包括了 Berkeley 資料庫環境) 的複製. 現在, 除非你暫時關閉所有其它對檔案庫的存取, 不然直接進行遞迴式的目錄複製的話, 會有得到無效備份的風險存在, 這是因為別人仍有可能正在寫入資料庫.

很幸運地, Sleepcat 的 Berkeley DB 文件載明了以怎麼樣的步驟複製資料庫檔案, 就可以保證取得有效的備份複本. 更好的是你不必親自實作, 因為 Subversion 發展團隊已經作好了. 在 Subversion 源碼的 tools/backup/ 目錄中, 可以找到 hot-backup.py 命令稿. 只要指定一個檔案庫的路徑與備份的位置, hot-backup.py 就會進行必要的步驟, 進行檔案庫的即時備份 — 完全不需要中止所有的公共存取 — 然後會清除檔案庫中無用的 Berkeley 記錄檔.

就算你已經有了漸近式備份, 你還是會想要定期執行這個程式. 舉例來說, 你會想把 hot-backup.py 加進定時執行的程式裡 (像是 Unix 系統的 crond). 或者你偏好可微調的備份方案的話, 可以讓你的 post-commit 掛勾命令稿呼叫 hot-backup.py (請參見 the section called “Hook scripts”), 這樣在每次有新的修訂版出現時, 就會建立檔案庫的新備份. 只要將以下這一行加進你的檔案庫目錄的 hooks/post-commit 命令稿即可:

(cd /path/to/hook/scripts; ./hot-backup.py ${REPOS} /path/to/backups &)

產生出來的備份是完全可用的 Subversion 檔案庫, 在事情無法收拾時, 可以立即用來作為檔案庫的替代品.

這兩種備份方式都有其長處. 目前最簡單的是完整備份, 它一定能夠產生正確無誤的檔案庫複製. 這表示不管線上檔案庫發生多糟糕的事, 只要一個簡單的遞迴目錄複製指令, 就能從備份回復回來. 不過很不幸地, 如果你維護多個檔案庫的備份, 這些完整備份會佔用跟你線上檔案庫一樣多的磁碟空間.

在 Subversion 前後版本的資料庫綱要變動的時候, 使用檔案庫傾印格式的漸進式備份在手邊是很方便的. 由於將檔案庫升級到新版的資料庫綱要需要進行完整的檔案庫傾印與載入, 如果已經有一半的步驟 (傾印的部份) 已經完成的話, 事情就方便多了. 不過很不幸地, 漸進式備份的建立 — 以及回復 — 要花較長的時間, 因為實際上每一個送交都是重播至傾印檔或是檔案庫之中.

不管是哪一種備份方式, 檔案庫管理員必須知道未納入版本控制的性質更動如何影響它們的備份. 由於這些更動不會產生新的修訂版, 它們不會觸發 post-commit 掛勾, 甚至也不會觸發 pre-revprop-change 與 post-revprop-change 掛勾. ^[14] 由於你能夠不依時間順序更動修訂版性質 — 你可以在任何時間修改任何修訂版的性質 — 最新幾個修訂版的漸進式備份也許不會知道原先備份的性質更動.

通常最好的修訂版備份是包含多種方式的. 你可以妥善運用完整備份與漸進備分的組合, 再加上電子郵件的送交檔案. 舉個例子, Subversion 的發展人員在每一次新的修訂版建立後, 就會備份 Subversion 的源碼, 並且保留所有的送交與性質的電子郵件通知. 你的方案可能很類似, 但是應該配合你的需要, 在便利與偏執之間取得平衡. 雖然這些都無法從暗黑命運的魔拳 ^[15] 中解救你的硬體, 它應該能在她肆機而動的時候解救你.

Subversion 的主要網路伺服器為 Apache HTTP 伺服器 (httpd), 可以 WebDAV/deltaV 通訊協定溝通. 這個通訊協定 (它是 HTTP 1.1 的擴充; 請參照 http://www.webdav.org/) 採用廣為使用的 HTTP 通訊協定, 這是全球資訊網的核心, 再加上寫入 — 更具體地說, 有版本控制的寫入 — 的能力. 其結果就是一個標準的, 強固的系統, 包裝成一個 Apache 2.0 軟體的一部份, 常用作業系統與協力廠商都支援, 又不需要網路管理員開啟另一個自訂的連接埠. ^[16]

以下的討論中, 提到許多 Apache 設定的指令. 雖然有些範例中提供了指令的用法, 但是完整的描述並不在本書的範圍中. Apache 團隊維護一份很不錯的文件, 可在他們的網站 http://httpd.apache.org 取得. 例如, 一般性的設定指令位於 http://httpd.apache.org/docs-2.0/mod/directives.html.

另外, 在你修改 Apache 的設定時, 很有可能會在過程中引入其它的錯誤. 就算你不熟悉 Apache 的紀錄子系統, 你也應該要知道有它的存在. 在你的 httpd.conf 檔中, 有著指定 Apache 產生的存取紀錄檔與錯誤紀錄檔應放置的位置 (各為 CustomLog 與 ErrorLog 指令). Subversion 的 mod_dav_svn 亦使用 Apache 的錯誤紀錄界面. 你都可以瀏灠這些檔案的內容, 它們可能會顯示出其它方法無法發生的錯誤來源.

LoadModule dav_svn_module     modules/mod_dav_svn.so
        

<Location /repos>
  DAV svn
  SVNPath /absolute/path/to/repository
</Location>

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
</Location>

$ ### 第一次: 以 -c 建立檔案
$ htpasswd -c /etc/svn-auth-file harry
New password: ***** 
Re-type new password: *****
Adding password for user harry
$ htpasswd /etc/svn-auth-file sally
New password: *******
Re-type new password: *******
Adding password for user sally
$
        

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
  AuthType Basic
  AuthName "Subversion repository"
  AuthUserFile /path/to/users/file
</Location>

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
  AuthType Basic
  AuthName "Subversion repository"
  AuthUserFile /path/to/users/file
  <LimitExcept GET PROPFIND OPTIONS REPORT>
    Require valid-user
  </LimitExcept>
</Location>

ServerName svn.red-bean.com
        

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
  SVNIndexXSLT "/svnindex.xsl"
  …
</Location>

除了 Apache 之外, Subversion 還提供另一個單獨的伺服器程式, 也就是 svnserve. 這個程式要比 Apache 更輕便, 而且更容易設定. 它會與 Subversion 用戶端透過 TCP/IP 連線以自訂的通訊協定溝通.

svnserve 有兩種基本的使用方法:

請注意, 這些 svnserve 的使用方法並不互相衝突; 你可以很簡單地同時在你的伺服器上, 使用這兩種技巧.

$ svnserve
( success ( 1 1 ( ANONYMOUS ) ( ) ) ) 

$ svnserve -d
$ # svnserve 仍在執行, 但是使用者已經回到提示字元

$ svnserve -d -r /usr/local
…

$ svn checkout svn://example.com/repos/project
…

$ svn checkout svn+ssh://example.com/usr/local/repos/project
Password:
…

$ export SVN_SSH="ssh -l username"

[tunnels]
ssh = ssh -l username
        

當你在 Apache HTTP 伺服器與自訂的 svnserve 程式之間作抉擇時, 其實並沒有一個標準的答案. 依你自己的要求, 某一個可用的方案可能看起來會比較適合. 事實上, 這些伺服器都可以一起使用, 每個都以它們自己的方式存取檔案庫, 不會互相干擾. 作為前兩章的總結, 以下是兩個 Subversion 可用的伺服器的簡單比較表 — 請選擇最適合你與使用者之用的:

雖然 Subversion 可以讓你隨意移動受版本控管的目錄與檔案, 而又不會遺失資訊, 不過這麼作還是會打亂經常存取檔案庫, 習慣什麼東西會在什麼地方的使用者的工作流程. 請試著稍微考慮一下未來; 在把資料納入版本控制之前, 先作好計劃. 藉由一開始就對檔案庫的內容先作好 “規劃”, 你可以免去未來的頭痛事件.

在設定 Subversion 檔案庫時, 有幾件事得考慮. 假設你是檔案庫管理員, 你得負責用於數個專案的版本控制系統的支援. 第一個決定, 你要對多個專案使用一個檔案庫, 還是每個專案都有它自己的檔案庫, 還是這兩者的折衷方案.

對多個專案使用一個檔案庫有一些好處, 最明顯的是不需作重複的維護動作. 一個檔案庫表示它有一組掛勾命令稿, 一個例行的備份, 如果 Subversion 發行一個不相容的新版本, 也只要進行一個傾印與載入, 諸如此類的. 再者, 你也可以在各個不同的專案之間搬移檔案, 不會漏失掉任何版本資訊的歷程紀錄.

使用單一檔案庫的缺點, 就是不同的專案可能會有不同的送交郵遞論壇, 或是不同的認證與授權的要求. 另外, 請記得 Subversion 使用的檔案庫範圍的修訂版號. 有人對於別的專案中正如火如荼在進行修改, 但是自己的專案卻因為全域修訂版的關係, 其最年輕的修訂版號一直努力攀升會相當地反感.

不過還是有中間路線可供取捨. 舉個例子, 不同的專案可以根據他們的相依程度歸類在一起. 你可以在每個檔案庫中, 放上幾個專案. 這樣子, 很有可能會分享資料的專案可以很容易達到目的, 當檔案庫增加修訂版號時, 發展人員至少可以知道, 這些更動對同一個檔案庫上的人員都是有一些影響的.

在決定你的專案如何與檔案庫組織起來後, 你大概就要思考檔案庫的目錄架構. 由於 Subversion 利用一般的目錄複本來作分支與標記 (請參考 Chapter 4, 分支與合併), Subversion 社群建議使用兩個方法之一. 這兩種方法都使用以下的目錄, 分別名為 trunk, 表示主要專案發展的目錄位置, 以及 branches, 於其中建立主要發展線不同具名分支.

第一種方法是把每個專案放在根檔案系統目錄之下的子目錄, 每個專案計劃目錄其下接著為 trunk 與 branches 目錄, 如圖 5-1 所示.

Figure 5.1. 一種建議的檔案庫配置.

第二種則是反過來 — 在檔案系統最頂層之下的是 trunk 與 branches 目錄, 其下則為所有檔案庫中的專案目錄, 如圖 5-2 所示:

Figure 5.2. 另一種建議的檔案庫配置.

請以你認為最適合的配置來規畫檔案庫. Subversion 並不會期望或強制你要用哪一種配置 — 在它的眼中, 是目錄的目錄就只是目錄. 歸根究底, 你應該選擇一種最適合你, 以及專案的檔案庫配置.

決定檔案庫要如何安排專案之後, 你應該就開始要以選擇的配置來建立檔案庫, 並放置資料進去. Subversion 有幾種方式可以達到這樣的目的. 你可以使用 svn mkdir 命令 (請參考 Chapter 8, 完整 Subversion 參考手冊) 命令, 依檔案庫配置的骨架, 一個一個將目錄建立起來. 比較快達到相同目的的方法, 就是使用 svn import 命令 (請參考 the section called “svn import”). 在磁碟的暫時位置先建立好檔案庫配置後, 你可以利用單一送交, 將整個配置樹匯入至檔案庫中:

$ mkdir tmpdir
$ cd tmpdir
$ mkdir projectA
$ mkdir projectA/trunk
$ mkdir projectA/branches
$ mkdir projectB
$ mkdir projectB/trunk
$ mkdir projectB/branches
…
$ svn import projectA file:///path/to/repos --message 'Initial repository layout'
Adding         projectA
Adding         projectA/trunk
Adding         projectA/branches
Adding         projectB
Adding         projectB/trunk
Adding         projectB/branches

Committed revision 1.
$ cd ..
$ rm -rf tmpdir
$

當你的配置骨架就定位後, 如果資料還沒進去的話, 你就可以開始將真正的資料匯入你的檔案庫. 再聲明一下, 要達到這個目的有很多方法. 你可以使用 svn import 命令. 你可以從新的檔案庫取出工作複本, 將資料移到工作複本中放好, 然後使用 svn add 與 svn commit. 不過當我們開始講到這樣的事情之後, 我們就不是在討論檔案庫管理. 如果你還不熟悉 svn 用戶端程式的話, 請參考 Chapter 3, 導覽.

svn 命令列用戶端在第一次執行的時候, 它會建立一個使用者設定區域. 在類 Unix 系統上, 它是使用者家目錄裡的 .subversion 目錄. 在 Win32 系統上, Subversion 會建立一個名為 Subversion 的檔案夾, 一般是在使用者 profile 目錄的 Application Data 區域中. 但是在這個平台上, 實際的位置會依各個系統不同而不同, 而且都是由 Windows 登錄檔指定的. ^[20] 我們會以 Unix 上的名稱 .subversion 來表示使用者設定區域.

除了使用者設定區域之外, Subversion 還會注意到系統設定區域的存在. 這讓系統管理員能夠在特定的機器上, 為所有使用者設定預設環境. 請注意, 系統設定區域並不具有強制性 — 使用者設定區域裡的設定會蓋過系統設定區域, 而在 svn 程式的命令列選項是最後決定行為的部份. 在類 Unix 平台上, 系統設定區域是在 /etc/subversion 目錄; 在 Windows 平台上, 它還是會在公用的 Application Data 區域 (同樣地, 還是要依 Windows 登錄檔裡的設定而定) 裡的 Subversion 目錄. 不像使用者設定區域一樣, svn 程式不會試著去建立系統設定區域.

目前 .subversion 目錄包含三個檔案 — 兩個設定檔 (config 與 servers), 以及一個 README.txt 檔案, 用來描述 INI 格式. 在建立它們的時候, 這些檔案包含 Subversion 支援選項的預設值, 大多數都被設定為註解, 並且包括這些設定值如何影響 Subversion 行為的描述文字. 要改變某一種行為, 你只需要以文字編輯器開啟適當的檔案, 然後修改對應選項的值. 如果任何時候你想要回復一個或多個檔案的預設值, 你只要刪除這些檔案, 然後執行某些無害的 svn 命令, 像是 svn --version, 那些消失的檔案就會以它們的預設狀態重新建立起來.

使用者設定區域也會包含認證資料的快取. auth 目錄擁有一群子目錄, 裡面包含數種 Subversion 支援的認證方式所需要的快取資料. 這個目錄建立時, 其權限設定為只讓使用者可以讀取其內容.

除了一般使用 INI 程式的設定區域, 執行於 Windows 上的 Subversion 用戶端也會利用 Windows 登錄檔來紀錄設定資料. 選項名稱與值都與 INI 檔案內的相同, 而 “檔案/區塊” 的架構也是一樣的, 但是說明時會有點不同 — 在該種方式下, 檔案與區塊只是登錄的不同階層而已.

Subversion 會在 HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion 鍵裡找系統設定值. 舉個例子, global-ignore 是一個在 config 檔的 miscellany 區塊中的選項, 可以在 HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Config\Miscellany\global-ignores 中找到. 使用者設定值則應該存於 HKEY_CURRENT_USER\Software\Tigris.org\Subversion 中.

登錄檔設定選項會在其對應的設定檔案 之前 被處理, 所以會被設定檔案中的數值給覆蓋過去. 換句話說, Windows 系統上的設定優先次序一定是以下列順序處理的:

另外, Windows 的登錄檔並不支援 “註解” 的語法. 不過 Subversion 會忽略任何以井字號 (#) 作為開頭的選項鍵. 這讓你能夠把一個 Subversion 選項變成註解, 而不必將其自登錄檔中刪去, 顯而易見地, 讓回復該選項的動作簡單多了.

svn 命令列用戶程式永遠不會寫入 Windows 登錄檔, 也不會在那裡建立預設的設定區域. 你可以利用 REGEDIT 來建立你需要的鍵. 另外, 你也可以建立一個 .REG 檔, 然後在檔案總管中雙擊該檔, 這樣會讓裡面的資料併入你的登錄檔中.

REGEDIT4

[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\groups]

[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\global]
"#http-proxy-host"=""
"#http-proxy-port"=""
"#http-proxy-username"=""
"#http-proxy-password"=""
"#http-proxy-exceptions"=""
"#http-timeout"="0"
"#http-compression"="yes"
"#neon-debug-mask"=""
"#ssl-authority-files"=""
"#ssl-trust-default-ca"=""
"#ssl-client-cert-file"=""
"#ssl-client-cert-password"=""

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auth]
"#store-password"="no"

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\helpers]
"#editor-cmd"="notepad"
"#diff-cmd"=""
"#diff3-cmd"=""
"#diff3-has-program-arg"=""

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\miscellany]
"#global-ignores"="*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#*"
"#log-encoding"=""
"#use-commit-times"=""
"#template-root"=""
"#enable-auto-props"=""

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\tunnels]

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]

前述的範例是 .REG 檔案的內容, 其中包含了幾個常用的設定選項, 以及它們的預設值. 請注意裡面同時包含了系統 (網路代理伺服器相關的選項) 與使用者設定 (編輯器程式與儲存密碼的地方, 以及有的沒有的). 你只需要自選項名稱之前移去井字號 (#), 然後設定你想要的值.

在本節中, 我們會討論目前 Subversion 支援的執行時期設定選項.

[groups]
beanie-babies = *.red-bean.com
collabnet = svn.collab.net

[beanie-babies]
…

d[collabnet]
…

對你的工作複本來說, 性質可說是相當有用的附加價值. 事實上, Subversion 自己就利用性質來放置特殊的資訊, 而且當作一種表示還需要進行某些處理的方法. 同樣地, 你可以依自己所需來使用性質. 當然囉, 任何你可以透過性質達到的, 你也可以透過一般納入版本控制的檔案作到, 不過先看看以下的 Subversion 性質使用例子.

假設你想要設計一個放置了許多數位照片的網站, 並以標題與日期戳記來顯示它們. 現在, 你的相片一直在變動, 所以你希望像大部份的站台一樣, 都儘量能夠自動化. 這些相片可能相當地大, 就像這類站台的共通特性一樣, 你希望能夠為站台訪客提供縮小的圖片. 你可以利用傳統的檔案來達到這樣的目的, 像是同時擺放 image123.jpg 與 image123-thumbnail.jpg. 或者如果你想要讓檔案名稱保持相同, 你可能會把縮小圖片放在不同的目錄, 像是 thumbnails/image123.jpg. 你也可以利用類似的方法, 儲存標題與日期戳記, 一樣還是存放在與原始影像不同的檔案. 很快地, 你的檔案樹就會一團糟, 每當有新的相片放上去, 就會增加好幾個檔案.

現在考慮以 Subversion 的檔案性質, 來進行相同的設定. 想像有一個影像檔 image123.jpg, 然後將該檔的性質設定為 caption, datestampe 以及 thumbnail. 現在你的工作複本目錄看起來更容易管理了 — 事實上, 裡面除了影像檔以外, 就沒別的了. 但是你的自動命令檔了解的更多. 它們知道可以利用 svn (更好的, 則是利用 Subversion 的語言繫結 — 請參考 the section called “Using Languages Other than C and C++”), 挖出網站所需的額外資訊, 而不必再去讀取索引檔, 或是玩著操弄路徑的遊戲.

你該如何 (或者該說是否) 使用 Subversion 的性質, 都由你自己決定. 如前所述, Subversion 對性質有自己的用法, 我們在本章稍候會討論到. 但是首先, 讓我們討論如何以 svn 程式來使用性質.

svn 命令提供了幾種新增或修改目錄與檔案性質的方法. 對於有著簡短而可讀的性質內容, 要新增性質最簡單的方法, 就是利用命令列的 propset 來指定子命令的性質名稱與數值.

$ svn propset copyright '(c) 2003 Red-Bean Software' calc/button.c
property `copyright' set on 'calc/button.c'
$

但是我們已強調, Subversion 為性質的數值提供了強大的彈性. 如果你的性質內容想要有多行文字, 更甚是二進制內容的話, 你大概不會想要在命令列指定其內容, 所以 propset 子命令提供了一個 --file (-F) 選項, 用以指定一個檔案名稱, 將該檔的內容作為性質的內容.

$ svn propset license -F /path/to/LICENSE calc/button.c
property `license' set on 'calc/button.c'
$

除了 propset 命令以外, svn 程式還提供了 propset 命令. 這個命令會使用設定的文字編輯程式 (參見 the section called “Config”) 以新增或修改性質. 當你執行這個命令時, svn 會讓文字編輯器修改一個暫存檔, 裡面包含了目前指定性質的內容 (或者什麼都沒有, 如果你要新增一個性質的話). 接著你只要在文字編輯器中修改這個內容, 直到它成為你想要的新內容, 然後存檔並跳離程式. 如果 Subversion 發現你真的修改了該性質的現有內容, 那麼它會接受, 並視為新的性質內容. 如果你未作任何修改就跳離文字編輯器的話, 那麼性質並不會有任何變動.

$ svn propedit copyright calc/button.c  ### exit the editor without changes
No changes to property `copyright' on `calc/button.c'
$

就像其它的 svn 子命令, 我們應該注意到性質也可以一次作用在多個路徑上. 這讓你能夠利用一個命令, 一次修改一組檔案的性質. 舉個例子, 我們可以這樣作:

$ svn propset copyright '(c) 2002 Red-Bean Software' calc/*
property `copyright' set on 'calc/Makefile'
property `copyright' set on 'calc/button.c'
property `copyright' set on 'calc/integer.c'
…
$

如果你不能很容易地取得儲存的性質內容的話, 這些新增與編輯性質的功能就沒有多大的用處. 因此 svn 程式提供了兩個子命令, 用以顯示儲存在目錄與檔案的性質名稱與內容. svn proplist 命令會列出所有儲存於某一路徑的所有性質名稱. 當你知道該節點的性質名稱之後, 你就可以利用 svn propget 來取得個別的內容. 只要指定一個路徑 (或一組路徑) 以及一個性質名稱, 這個命令會在標準輸出串流上顯示性質內容.

$ svn proplist calc/button.c
Properties on 'calc/button.c':
  copyright
  license
$ svn propget copyright calc/button.c
(c) 2003 Red-Bean Software

proplist 命令甚至還有變形, 可以列出所有性質的名稱與其內容. 只要指定 --verbose (-v) 選項即可.

$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2003 Red-Bean Software
  license : ================================================================
Copyright (c) 2003 Red-Bean Software.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions 
are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions, and the recipe for Fitz's famous
red-beans-and-rice.
…

最後一個與性質有關的子命令, 是 propdel. 由於 Subversion 允許你儲存空值的性質, 你無法利用 propedit 或 propset 來移除性質. 舉個例子, 以下的命令 不會 產生你想要的效果:

$ svn propset license '' calc/button.c
property `license' set on 'calc/button.c'
$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2003 Red-Bean Software
  license : 
$

你需要使用 propdel 命令來刪除性質. 它的語法很接近其它性質命令:

$ svn propdel license calc/button.c
property `foo' deleted from ''.
$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2003 Red-Bean Software
$

現在你已經熟悉了所有關於性質的 svn 子命令, 讓我們看看性質修改如何影響一般的 Subversion 工作流程. 如我們早先提過的, 目錄與檔案的性質都被納入版本管理, 就像你的檔案內容一樣. 這樣的結果, 就是 Subversion 也提供合併 — 無誤地合併, 或是產生衝突 — 別人更動的機會.

$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop
property `svn:log' set on repository revision '11'
$

就像檔案內容一樣, 性質的更動算是本地修改, 只有在你透過 svn commit 送進檔案庫後, 它才會永久生效. 你所作的性質更動也可以很容易地回復 — svn revert 命令會把你的目錄與檔案回復至它們尚未編輯的狀態、內容、性質、所有的東西. 還有, 透過 svn status 與 svn diff, 你也可以得到關於目錄與檔案的一些有趣資訊.

$ svn status calc/button.c
 M     calc/button.c
$ svn diff calc/button.c
Property changes on: calc/button.c
___________________________________________________________________
Name: copyright
   + (c) 2003 Red-Bean Software

$

請注意 status 子命令是如何在第二欄, 而非第一欄中顯示 M. 那是因為我們修改了 calc/button.c 的性質, 但是還沒有修改它的文字內容. 要是我們兩位都變更了, 我們也會在第一欄看到 M (請參見 the section called “svn status”).

% svn update calc
M  calc/Makefile.in
 C calc/button.c
Updated to revision 143.
$ 

$ svn status calc
 C     calc/button.c
?      calc/button.c.prej
$ cat calc/button.c.prej 
prop `linecount': user set to '1256', but update set to '1301'.
$

你也許也注意到, Subversion 使用非標準的方式來顯示性質差異. 你還是可以執行 svn diff, 然後將結果重導向, 以產生出適合的修補檔. patch 程式會忽略掉性質的部份 — 一般來說, 它會忽略任何它看不懂的東西. 很不幸地, 如果你想要完全套用 svn diff 的修補檔的話, 所有性質修改的地方, 都必須手動為之.

如你所見, 性質修改的存在, 對於一般的 Subversion 工作流程並沒有很大的影響. 更新工作複本, 檢查目錄與檔案的狀態, 回報你所作的更動, 以及送交更動回檔案庫的工作型態, 與性質的存在與否是毫不相干的. svn 程式是多了幾個可以用來修改性質的子命令, 不過也就只有這個明顯可見的差異而已.

Subversion 對性質沒有什麼特別的規定 — 你可以為任何理由而使用它們. Subversion 只要求使用者不要使用以 svn: 作為開頭的性質. 這個命名空間已經保留下來, 有它自己的用途. 事實上, Subversion 定義了幾個特殊的性質, 它對關聯到的目錄與檔案有神奇的效用. 在本節中, 我們會解開這層神祕的面紗, 說明這些特殊的性質是如何讓你的生命稍微好過一點.

$ svn propset svn:ignore -F .cvsignore .
property `svn:ignore' set on '.'
$

$ svn status calc
 M     calc/button.c
?      calc/calculator
?      calc/data.c
?      calc/debug_log
?      calc/debug_log.1
?      calc/debug_log.2.gz
?      calc/debug_log.3.gz

calculator
debug_log*

$ svn status
 M     calc
 M     calc/button.c
?      calc/data.c

$ svn status --no-ignore
 M     calc/button.c
I      calc/calculator
?      calc/data.c
I      calc/debug_log
I      calc/debug_log.1
I      calc/debug_log.2.gz
I      calc/debug_log.3.gz

Here is the latest report from the front lines.
$LastChangedDate$
$Rev$
Cumulus clouds are appearing more frequently as summer approaches.

$ svn propset svn:keywords "LastChangedDate Author" weather.txt
property `svn:keywords' set on 'weather.txt'
$

Here is the latest report from the front lines.
$LastChangedDate: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $
$Rev$
Cumulus clouds are appearing more frequently as summer approaches.

管理供應商分支的方法, 一般是以這種方式處理. 你建立一個最上層的目錄 (像是 /vendor) 來存放供應商分支. 然後將第三方源碼匯入到這個最上層目錄的一個子目錄中. 然後, 你將這個子目錄複製到你的主要發展分支 (舉個例子, /trunk) 至適當的位置. 你的更動, 一定都是在主要發展分支裡. 每次你追蹤的程式碼有了新的發行版本時, 就把它放進供應商分支, 將更動合併回 /trunk, 並且解決本地更動與上游更動之間的衝突.

也許來個例子, 就更能了解這個方法. 我們使用一個案例, 你的發展團隊正在製作一個計算機程式, 它需要連結到一個第三方的複數運算程式庫, 叫作 libcomplex. 我們一開始先建立一個供應商分支, 然後匯入第一個供應商 drop.

…
$ svn import /path/to/libcomplex-1.0 \
             http://svn.example.com/repos/calc/vendor/libcomplex/current \
             -m 'importing initial 1.0 vendor drop'
…

我們現在在 /vendor/libcomplex/current 中, 放置了現行版本的 libcomplex 源碼. 現在我們建立這個版本的標記 (請參見 the section called “標記”), 然後將把它複製到主發展分支, 這樣我們才能對它建立自訂修改.

$ svn copy http://svn.example.com/repos/calc/vendor/libcomplex/current  \
           http://svn.example.com/repos/calc/vendor/libcomplex/1.0      \
           -m 'tagging libcomplex-1.0'
…
$ svn copy http://svn.example.com/repos/vendor/libcomplex/1.0  \
           http://svn.example.com/repos/calc/libcomplex        \
           -m 'bringing libcomplex-1.0 into the main branch'
…

我們取出專案的主要分支 — 現在它包含了最初的供應商 drop 複本 — 然後開始建立 libcomplex 的自訂源碼. 在我們注意到之前, 我們修改過的 libcomplex 已經完全整合到我們的計算機程式. ^[27]

幾個星期後, libcomplex 的發展人員釋出了新版的程式庫 — 1.1 版 — 它包含了幾個非常想要的特色與功能. 但是我希望升級到這個新版本, 但是又仍保有我們對現存版本的自訂修正. 就如你所猜想的, 我們實際要作的, 就是以 libcomplex 1.1 的複本取代我們現存的基準版本 libcomplex 1.0, 然後再將我們對該程式庫所作的自訂修改套用到新的版本去.

要進行這樣的升級, 我們先取得一份供應商分支的複本, 然後以新的 libcomplex 1.1 源碼取得 current 版本. 在送交這個更動之後, 現在我們的 current 分支就包含了新的供應商 drop. 我們標記新的版本, 然後再將前一個版本的標記與新的現行版本之間的差異, 合併至我們的主要發展分支.

$ cd working-copies/calc
$ svn merge http://svn.example.com/repos/vendor/libcomplex/1.0      \
            http://svn.example.com/repos/vendor/libcomplex/current  \
            libcomplex
… # resolve all the conflicts between their changes and our changes
… # 解決所有他們與我們的更動之間的衝突
$ svn commit -m 'merging libcomplex-1.1 into the main branch'
…

在普通的使用情況下, 從目錄與檔案的觀點來說, 第三方工具的新版本看起來與前一個版本沒什麼差別. 換句話說, 沒有任何一個 libcomplex 源碼檔案被刪除, 更名, 或是移到新的位置 — 簡單地請, 在完美的世界中, 我們的更動可以無誤地套用在新版的程式庫, 一點也不複雜, 也不會有衝突發生.

但是事情並不總是那麼簡單, 而且事實上, 源碼在不同發行版本之間常常會移動. 確認我們的更動仍能適用在新版本的源碼變得複雜, 很快地, 我們會陷入必須手動對新版本重新作出我們的自訂更動. 不過只要 Subversion 知道某個指定源碼檔的歷史 — 包括它先前的位置 — 合併新版本程式庫的過程就很簡單了. 但是我們必須告訴 Subversion 在供應商 drop 版本之間的檔案配置更動.

如果供應商 drop 包含好幾個刪除, 新增, 以及移動的檔案的話, 更新第三方資料的連續版本就變得複雜. 所以 Subversion 提供了 svn_load_dirs.pl 腳本檔, 幫助你進行這樣的作業. 這個腳本檔會自動執行我們在通用供應商分支管理程序一節中所講的匯入方法, 以將錯誤降到最低. 不過你還是要自已執行合併命令, 以將新版本的第三方資料合併至你的主發展分支, 但是 svn_load_dirs.pl 可以幫助更快更輕鬆地達到那個階段.

簡單地說, svn_load_dirs.pl 是 svn import 的加強, 它有以下幾個重要特性:

svn_load_dirs.pl 需要三個主要的引數. 第一個引數是用來工作的基礎 Subversion 目錄的 URL. 接著這個引數的是 URL — 相對於第一個引數 — 目前的供應商 drop 會匯入至該目錄下. 最後, 第三個引數是要匯入的本地目錄. 以我們前面的例子來說, svn_load_dirs.pl 執行起來就像這樣;

$ svn_load_dirs.pl http://svn.example.com/repos/calc/vendor/libcomplex \
                   current                                             \
                   /path/to/libcomplex-1.1
…

藉由傳遞 -t 命令列選項, 並且指定一個標籤名稱, 你可以讓 svn_load_dirs.pl 來標記新的供應商 drop. 這個標記是另一個相對於第一個程式引數的 URL.

$ svn_load_dirs.pl -t libcomplex-1.1                                   \
                   http://svn.example.com/repos/calc/vendor/libcomplex \
                   current                                             \
                   /path/to/libcomplex-1.1
…

當你執行 svn_load_dirs.pl 時, 它會檢查你 “現有” 供應商 drop 的內容, 然後將它與新的供應商 drop 作比較. 在最簡單的情況中, 不會有一個檔案出現在一個版本, 而在另一個版本不見的情況, 命令稿會毫無問題地進行新的匯入. 不過要是版本之間有不同檔案配置, svn_load_dirs.pl 會問你要如何解決這些差異. 舉個例子, 你有機會告訴命令稿 libcomplex 1.0 版的 math.c 已經更名為 libcomplex 1.1 的 arithmetic.c. 任何沒有以移動來解釋的差異, 將會當作普通的新增與刪除.

這個命令稿也接受一個獨立的設定檔, 設定符合正規表示式、 新增 到檔案庫的目錄與檔案的性質. 可以透過 -p 命令列, 向 svn_load_dirs.pl 指定設定檔. 設定檔的每一列, 包含以空白分隔的兩個或四個值: 一個類似 Perl 風格的正規表示式, 用以比對新增的路徑, 一個控制關鍵字 (可為 break 或 cont), 然後可以接一個性質的名稱與其內容.

\.png$              break   svn:mime-type   image/png
\.jpe?g$            break   svn:mime-type   image/jpeg
\.m3u$              cont    svn:mime-type   audio/x-mpegurl
\.m3u$              break   svn:eol-style   LF
.*                  break   svn:eol-style   native

對每個新增的路徑, 當依序比對的路徑正規表示式比對成功時, 與其對應的性質會變更, 除非控制指定為 break (這表示該路徑已經沒有性質要變動的). 如果控制指定為 cont — 這是 continue 的縮寫 — 那麼比對會繼續往控制檔案的下一列進行.

任何在正規表示式、性質名稱、或是性質內容裡的空白字元, 都必須以單引號或雙引號字元包起來. 你可以將不是用來包起空白字元的引號字元, 於其前加上倒斜線 (\) 將其逸出 (escape). 在剖析設定檔時, 倒斜線只會用來逸出引號, 所以對正規表示式, 不必對不必要的字元保護過頭.

When referring to Subversion's Repository Layer, we're generally talking about two libraries—the repository library, and the filesystem library. These libraries provide the storage and reporting mechanisms for the various revisions of your version-controlled data. This layer is connected to the Client Layer via the Repository Access Layer, and is, from the perspective of the Subversion user, the stuff at the "other end of the line."

The Subversion Filesystem is accessed via the libsvn_fs API, and is not a kernel-level filesystem that one would install in an operating system (like the Linux ext2 or NTFS), but a virtual filesystem. Rather than storing "files" and "directories" as real files and directories (as in, the kind you can navigate through using your favorite shell program), it uses a database system for its back-end storage mechanism. Currently, the database system in use is Berkeley DB. ^[28] However, there has been considerable interest by the development community in giving future releases of Subversion the ability to use other back-end database systems, perhaps through a mechanism such as Open Database Connectivity (ODBC).

The filesystem API exported by libsvn_fs contains the kinds of functionality you would expect from any other filesystem API: you can create and remove files and directories, copy and move them around, modify file contents, and so on. It also has features that are not quite as common, such as the ability to add, modify, and remove metadata ("properties") on each file or directory. Furthermore, the Subversion Filesystem is a versioning filesystem, which means that as you make changes to your directory tree, Subversion remembers what your tree looked like before those changes. And before the previous changes. And the previous ones. And so on, all the way back through versioning time to (and just beyond) the moment you first started adding things to the filesystem.

All the modifications you make to your tree are done within the context of a Subversion transaction. The following is a simplified general routine for modifying your filesystem:

Once you have committed your transaction, your filesystem modifications are permanently stored as historical artifacts. Each of these cycles generates a single new revision of your tree, and each revision is forever accessible as an immutable snapshot of "the way things were."

Most of the functionality provided by the filesystem interface comes as an action that occurs on a filesystem path. That is, from outside of the filesystem, the primary mechanism for describing and accessing the individual revisions of files and directories comes through the use of path strings like /foo/bar, just as if you were addressing files and directories through your favorite shell program. You add new files and directories by passing their paths-to-be to the right API functions. You query for information about them by the same mechanism.

Unlike most filesystems, though, a path alone is not enough information to identify a file or directory in Subversion. Think of a directory tree as a two-dimensional system, where a node's siblings represent a sort of left-and-right motion, and descending into subdirectories a downward motion. Figure 7-2 shows a typical representation of a tree as exactly that.

Figure 7.2. Files and Directories in Two Dimensions

Of course, the Subversion filesystem has a nifty third dimension that most filesystems do not have—Time! ^[29] In the filesystem interface, nearly every function that has a path argument also expects a root argument. This svn_fs_root_t argument describes either a revision or a Subversion transaction (which is usually just a revision-to-be), and provides that third-dimensional context needed to understand the difference between /foo/bar in revision 32, and the same path as it exists in revision 98. Figure 7-3 shows revision history as an added dimension to the Subversion filesystem universe.

Figure 7.3. Revisioning Time—the Third Dimension!

As we mentioned earlier, the libsvn_fs API looks and feels like any other filesystem, except that it has this wonderful versioning capability. It was designed to be usable by any program interested in a versioning filesystem. Not coincidentally, Subversion itself is interested in that functionality. But while the filesystem API should be sufficient for basic file and directory versioning support, Subversion wants more—and that is where libsvn_repos comes in.

The Subversion repository library (libsvn_repos) is basically a wrapper library around the filesystem functionality. This library is responsible for creating the repository layout, making sure that the underlying filesystem is initialized, and so on. Libsvn_repos also implements a set of hooks—scripts that are executed by the repository code when certain actions take place. These scripts are useful for notification, authorization, or whatever purposes the repository administrator desires. This type of functionality, and other utility provided by the repository library, is not strictly related to implementing a versioning filesystem, which is why it was placed into its own library.

Developers who wish to use the libsvn_repos API will find that it is not a complete wrapper around the filesystem interface. That is, only certain major events in the general cycle of filesystem activity are wrapped by the repository interface. Some of these include the creation and commit of Subversion transactions, and the modification of revision properties. These particular events are wrapped by the repository layer because they have hooks associated with them. In the future, other events may be wrapped by the repository API. All of the remaining filesystem interaction will continue to occur directly with libsvn_fs API, though.

For example, here is a code segment that illustrates the use of both the repository and filesystem interfaces to create a new revision of the filesystem in which a directory is added. Note that in this example (and all others throughout this book), the SVN_ERR macro simply checks for a non-successful error return from the function it wraps, and returns that error if it exists.

/* Create a new directory at the path NEW_DIRECTORY in the Subversion
   repository located at REPOS_PATH.  Perform all memory allocation in
   POOL.  This function will create a new revision for the addition of
   NEW_DIRECTORY.  */
static svn_error_t *
make_new_directory (const char *repos_path,
                    const char *new_directory,
                    apr_pool_t *pool)
{
  svn_error_t *err;
  svn_repos_t *repos;
  svn_fs_t *fs;
  svn_revnum_t youngest_rev;
  svn_fs_txn_t *txn;
  svn_fs_root_t *txn_root;
  const char *conflict_str;

  /* Open the repository located at REPOS_PATH.  */
  SVN_ERR (svn_repos_open (&repos, repos_path, pool));

  /* Get a pointer to the filesystem object that is stored in
     REPOS.  */
  fs = svn_repos_fs (repos);

  /* Ask the filesystem to tell us the youngest revision that
     currently exists.  */
  SVN_ERR (svn_fs_youngest_rev (&youngest_rev, fs, pool));

  /* Begin a new transaction that is based on YOUNGEST_REV.  We are
     less likely to have our later commit rejected as conflicting if we
     always try to make our changes against a copy of the latest snapshot
     of the filesystem tree.  */
  SVN_ERR (svn_fs_begin_txn (&txn, fs, youngest_rev, pool));

  /* Now that we have started a new Subversion transaction, get a root
     object that represents that transaction.  */
  SVN_ERR (svn_fs_txn_root (&txn_root, txn, pool));
  
  /* Create our new directory under the transaction root, at the path
     NEW_DIRECTORY.  */
  SVN_ERR (svn_fs_make_dir (txn_root, new_directory, pool));

  /* Commit the transaction, creating a new revision of the filesystem
     which includes our added directory path.  */
  err = svn_repos_fs_commit_txn (&conflict_str, repos, 
                                 &youngest_rev, txn);
  if (! err)
    {
      /* No error?  Excellent!  Print a brief report of our success.  */
      printf ("Directory '%s' was successfully added as new revision "
              "'%" SVN_REVNUM_T_FMT "'.\n", new_directory, youngest_rev);
    }
  else if (err->apr_err == SVN_ERR_FS_CONFLICT))
    {
      /* Uh-oh.  Our commit failed as the result of a conflict
         (someone else seems to have made changes to the same area 
         of the filesystem that we tried to modify).  Print an error
         message.  */
      printf ("A conflict occurred at path '%s' while attempting "
              "to add directory '%s' to the repository at '%s'.\n", 
              conflict_str, new_directory, repos_path);
    }
  else
    {
      /* Some other error has occurred.  Print an error message.  */
      printf ("An error occurred while attempting to add directory '%s' "
              "to the repository at '%s'.\n", 
              new_directory, repos_path);
    }

  /* Return the result of the attempted commit to our caller.  */
  return err;
} 

In the previous code segment, calls were made to both the repository and filesystem interfaces. We could just as easily have committed the transaction using svn_fs_commit_txn. But the filesystem API knows nothing about the repository library's hook mechanism. If you want your Subversion repository to automatically perform some set of non-Subversion tasks every time you commit a transaction (like, for example, sending an email that describes all the changes made in that transaction to your developer mailing list), you need to use the libsvn_repos-wrapped version of that function—svn_repos_fs_commit_txn. This function will actually first run the "pre-commit" hook script if one exists, then commit the transaction, and finally will run a "post-commit" hook script. The hooks provide a special kind of reporting mechanism that does not really belong in the core filesystem library itself. (For more information regarding Subversion's repository hooks, see the section called “Hook scripts”.)

The hook mechanism requirement is but one of the reasons for the abstraction of a separate repository library from the rest of the filesystem code. The libsvn_repos API provides several other important utilities to Subversion. These include the abilities to:

As Subversion continues to evolve, the repository library will grow with the filesystem library to offer increased functionality and configurable option support.

If the Subversion Repository Layer is at "the other end of the line", the Repository Access Layer is the line itself. Charged with marshalling data between the client libraries and the repository, this layer includes the libsvn_ra module loader library, the RA modules themselves (which currently includes libsvn_ra_dav, libsvn_ra_local, and libsvn_ra_svn), and any additional libraries needed by one or more of those RA modules, such as the mod_dav_svn Apache module with which libsvn_ra_dav communicates or libsvn_ra_svn's server, svnserve.

Since Subversion uses URLs to identify its repository resources, the protocol portion of the URL schema (usually file:, http:, https:, or svn:) is used to determine which RA module will handle the communications. Each module registers a list of the protocols it knows how to "speak" so that the RA loader can, at runtime, determine which module to use for the task at hand. You can determine which RA modules are available to the Subversion command-line client, and what protocols they claim to support, by running svn --version:

$ svn --version
svn, version 0.25.0 (dev build)
   compiled Jul 18 2003, 16:25:59
 
Copyright (C) 2000-2003 CollabNet.
Subversion is open source software, see http://subversion.tigris.org/
 
The following repository access (RA) modules are available:
 
* ra_dav : Module for accessing a repository via WebDAV (DeltaV) protocol.
  - handles 'http' schema
* ra_local : Module for accessing a repository on local disk.
  - handles 'file' schema
* ra_svn : Module for accessing a repository using the svn network protocol.
  - handles 'svn' schema

On the client side, the Subversion working copy is where all the action takes place. The bulk of functionality implemented by the client-side libraries exists for the sole purpose of managing working copies—directories full of files and other subdirectories which serve as a sort of local, editable "reflection" of one or more repository locations—and propagating changes to and from the Repository Access layer.

Subversion's working copy library, libsvn_wc, is directly responsible for managing the data in the working copies. To accomplish this, the library stores administrative information about each working copy directory within a special subdirectory. This subdirectory, named .svn is present in each working copy directory and contains various other files and directories which record state and provide a private workspace for administrative action. For those familiar with CVS, this .svn subdirectory is similar in purpose to the CVS administrative directories found in CVS working copies. For more information about the .svn administrative area, see the section called “Inside the Working Copy Administration Area”in this chapter.

The Subversion client library, libsvn_client, has the broadest responsibility; its job is to mingle the functionality of the working copy library with that of the Repository Access Layer, and then to provide the highest-level API to any application that wishes to perform general revision control actions. For example, the function svn_client_checkout takes a URL as an argument. It passes this URL to the RA layer and opens an authenticated session with a particular repository. It then asks the repository for a certain tree, and sends this tree into the working copy library, which then writes a full working copy to disk (.svn directories and all).

The client library is designed to be used by any application. While the Subversion source code includes a standard command-line client, it should be very easy to write any number of GUI clients on top of the client library. New GUIs (or any new client, really) for Subversion need not be clunky wrappers around the included command-line client—they have full access via the libsvn_client API to same functionality, data, and callback mechanisms that the command-line client uses.

Along with Subversion's own datatype, you will see many references to datatypes that begin with "apr_"—symbols from the Apache Portable Runtime (APR) library. APR is Apache's portability library, originally carved out of its server code as an attempt to separate the OS-specific bits from the OS-independent portions of the code. The result was a library that provides a generic API for performing operations that differ mildly—or wildly—from OS to OS. While Apache HTTP Server was obviously the first user of the APR library, the Subversion developers immediately recognized the value of using APR as well. This means that there are practically no OS-specific code portions in Subversion itself. Also, it means that the Subversion client compiles and runs anywhere that the server does. Currently this list includes all flavors of Unix, Win32, BeOS, OS/2, and Mac OS X.

In addition to providing consistent implementations of system calls that differ across operating systems, ^[30] APR gives Subversion immediate access to many custom datatypes, such as dynamic arrays and hash tables. Subversion uses these types extensively throughout the codebase. But perhaps the most pervasive APR datatype, found in nearly every Subversion API prototype, is the apr_pool_t—the APR memory pool. Subversion uses pools internally for all its memory allocation needs (unless an external library requires a different memory management schema for data passed through its API), ^[31] and while a person coding against the Subversion APIs is not required to do the same, they are required to provide pools to the API functions that need them. This means that users of the Subversion API must also link against APR, must call apr_initialize() to initialize the APR subsystem, and then must acquire a pool for use with Subversion API calls. See the section called “Programming with Memory Pools” for more information.

With remote version control operation as the whole point of Subversion's existence, it makes sense that some attention has been paid to internationalization (i18n) support. After all, while "remote" might mean "across the office", it could just as well mean "across the globe." To facilitate this, all of Subversion's public interfaces that accept path arguments expect those paths to be canonicalized, and encoded in UTF-8. This means, for example, that any new client binary that drives the libsvn_client interface needs to first convert paths from the locale-specific encoding to UTF-8 before passing those paths to the Subversion libraries, and then re-convert any resultant output paths from Subversion back into the locale's encoding before using those paths for non-Subversion purposes. Fortunately, Subversion provides a suite of functions (see subversion/include/svn_utf.h) that can be used by any program to do these conversions.

Also, Subversion APIs require all URL parameters to be properly URI-encoded. So, instead of passing file:///home/username/My File.txt as the URL of a file named My File.txt, you need to pass file:///home/username/My%20File.txt. Again, Subversion supplies helper functions that your application can use—svn_path_uri_encode and svn_path_uri_decode, for URI encoding and decoding, respectively.

If you are interested in using the Subversion libraries in conjunction with something other than a C program—say a Python script or Java application—Subversion has some initial support for this via the Simplified Wrapper and Interface Generator (SWIG). The SWIG bindings for Subversion are located in subversion/bindings/swig and are slowly maturing into a usable state. These bindings allow you to call Subversion API functions indirectly, using wrappers that translate the datatypes native to your scripting language into the datatypes needed by Subversion's C libraries.

There is an obvious benefit to accessing the Subversion APIs via a language binding—simplicity. Generally speaking, languages such as Python and Perl are much more flexible and easy to use than C or C++. The sort of high-level datatypes and context-driven type checking provided by these languages are often better at handling information that comes from users. As you know, only a human can botch up the input to a program as well as they do, and the scripting-type language simply handle that misinformation more gracefully. Of course, often that flexibility comes at the cost of performance. That is why using a tightly-optimized, C-based interface and library suite, combined with a powerful, flexible binding language is so appealing.

Let's look at an example that uses Subversion's Python SWIG bindings. Our example will do the same thing as our last example. Note the difference in size and complexity of the function this time!

from svn import fs
import os.path

def crawl_filesystem_dir (root, directory, pool):
  """Recursively crawl DIRECTORY under ROOT in the filesystem, and return
  a list of all the paths at or below DIRECTORY.  Use POOL for all 
  allocations."""

  # Get the directory entries for DIRECTORY.
  entries = fs.dir_entries(root, directory, pool)

  # Initialize our returned list with the directory path itself.
  paths = [directory]

  # Loop over the entries
  names = entries.keys()
  for name in names:
    # Calculate the entry's full path.
    full_path = os.path.join(basepath, name)

    # If the entry is a directory, recurse.  The recursion will return
    # a list with the entry and all its children, which we will add to
    # our running list of paths.
    if fs.is_dir(fsroot, full_path, pool):
      subpaths = crawl_filesystem_dir(root, full_path, pool)
      paths.extend(subpaths)

    # Else, it is a file, so add the entry's full path to the FILES list.
    else:
      paths.append(full_path)

  return paths

An implementation in C of the previous example would stretch on quite a bit longer. The same routine in C would need to pay close attention to memory usage, and need to use custom datatypes for representing the hash of entries and the list of paths. Python has hashes and lists (called "dictionaries" and "sequences", respectively) as built-in datatypes, and provides a wonderful selection of methods for operating on those types. And since Python uses reference counting and garbage collection, users of the language don't have to bother themselves with allocating and freeing memory.

In the previous section of this chapter, we mentioned the libsvn_client interface, and how it exists for the sole purpose of simplifying the process of writing a Subversion client. The following is a brief example of how that library can be accessed via the SWIG bindings. In just a few lines of Python, you can check out a fully functional Subversion working copy!

#!/usr/bin/env python
import sys
from svn import util, _util, _client

def usage():
  print "Usage: " + sys.argv[0] + " URL PATH\n"
  sys.exit(0)

def run(url, path):
  # Initialize APR and get a POOL.
  _util.apr_initialize()
  pool = util.svn_pool_create(None)

  # Checkout the HEAD of URL into PATH (silently)
  _client.svn_client_checkout(None, None, url, path, -1, 1, None, pool)

  # Cleanup our POOL, and shut down APR.
  util.svn_pool_destroy(pool)
  _util.apr_terminate()

if __name__ == '__main__':
  if len(sys.argv) != 3:
    usage()
  run(sys.argv[1], sys.argv[2])

Currently, it is Subversion's Python bindings that are the most complete. Some attention is also being given to the Java bindings. Once you have the SWIG interface files properly configured, generation of the specific wrappers for all the supported SWIG languages (which currently includes versions of C#, Guile, Java, Mzscheme, OCaml, Perl, PHP, Python, Ruby, and Tcl) should theoretically be trivial. Still, some extra programming is required to compensate for complex APIs that SWIG needs some help generalizing. For more information on SWIG itself, see the project's website at http://www.swig.org.

Perhaps the single most important file in the .svn directory is the entries file. The entries file is an XML document which contains the bulk of the administrative information about a versioned resource in a working copy directory. It is this one file which tracks the repository URLs, pristine revision, file checksums, pristine text and property timestamps, scheduling and conflict state information, last-known commit information (author, revision, timestamp), local copy history—practically everything that a Subversion client is interested in knowing about a versioned (or to-be-versioned) resource!

The following is an example of an actual entries file:

<?xml version="1.0" encoding="utf-8"?>
<wc-entries
   xmlns="svn:">
<entry
   committed-rev="1"
   name="svn:this_dir"
   committed-date="2002-09-24T17:12:44.064475Z"
   url="http://svn.red-bean.com/tests/.greek-repo/A/D"
   kind="dir"
   revision="1"/>
<entry
   committed-rev="1"
   name="gamma"
   text-time="2002-09-26T21:09:02.000000Z"
   committed-date="2002-09-24T17:12:44.064475Z"
   checksum="QSE4vWd9ZM0cMvr7/+YkXQ=="
   kind="file"
   prop-time="2002-09-26T21:09:02.000000Z"/>
<entry
   name="zeta"
   kind="file"
   schedule="add"
   revision="0"/>
<entry
   url="http://svn.red-bean.com/tests/.greek-repo/A/B/delta"
   name="delta"
   kind="file"
   schedule="add"
   revision="0"/>
<entry
   name="G"
   kind="dir"/>
<entry
   name="H"
   kind="dir"
   schedule="delete"/>
</wc-entries>

As you can see, the entries file is essentially a list of entries. Each entry tag represents one of three things: the working copy directory itself (noted by having its name attribute set to "svn:this-dir"), a file in that working copy directory (noted by having its kind attribute set to "file"), or a subdirectory in that working copy (kind here is set to "dir"). The files and subdirectories whose entries are stored in this file are either already under version control, or (as in the case of the file named zeta above) are scheduled to be added to version control when the user next commits this working copy directory's changes. Each entry has a unique name, and each entry has a node kind.

Developers should be aware of some special rules that Subversion uses when reading and writing its entries files. While each entry has a revision and URL associated with it, note that not every entry tag in the sample file has explicit revision or url attributes attached to it. Subversion allows entries to not explicitly store those two attributes when their values are the same as (in the revision case) or trivially calculable from ^[32] (in the url case) the data stored in the "svn:this-dir" entry. Note also that for subdirectory entries, Subversion stores only the crucial attributes—name, kind, url, revision, and schedule. In an effort to reduce duplicated information, Subversion dictates that the method for determining the full set of information about a subdirectory is to traverse down into that subdirectory, and read the "svn:this-dir" entry from its own .svn/entries file. However, a reference to the subdirectory is kept in its parent's entries file, with enough information to permit basic versioning operations in the event that the subdirectory itself is actually missing from disk.

As mentioned before, the .svn directory also holds the pristine "text-base" versions of files. Those can be found in .svn/text-base. The benefits of these pristine copies are multiple—network-free checks for local modifications and "diff" reporting, network-free reversion of modified or missing files, smaller transmission of changes to the server—but comes at the cost of having each versioned file stored at least twice on disk. These days, this seems to be a negligible penalty for most files. However, the situation gets uglier as the size of your versioned files grows. Some attention is being given to making the presence of the "text-base" an option. Ironically though, it is as your versioned files' sizes get larger that the existence of the "text-base" becomes more crucial—who wants to transmit a huge file across a network just because they want to commit a tiny change to it?

Similar in purpose to the "text-base" files are the property files and their pristine "prop-base" copies, located in .svn/props and .svn/prop-base respectively. Since directories can have properties, too, there are also .svn/dir-props and .svn/dir-prop-base files. Each of these property files ("working" and "base" versions) uses a simple "hash-on-disk" file format for storing the property names and values.

The first step in community participation is to find a way to stay on top of the latest happenings. To do this most effectively, you will want to subscribe to the main developer discussion list (<dev@subversion.tigris.org>) and commit mail list (<svn@subversion.tigris.org>). By following these lists even loosely, you will have access to important design discussions, be able to see actual changes to Subversion source code as they occur, and be able to witness peer reviews of those changes and proposed changes. These email based discussion lists are the primary communication media for Subversion development. See the Mailing Lists section of the website for other Subversion-related lists you might be interested in.

But how do you know what needs to be done? It is quite common for a programmer to have the greatest intentions of helping out with the development, yet be unable to find a good starting point. After all, not many folks come to the community having already decided on a particular itch they would like to scratch. But by watching the developer discussion lists, you might see mentions of existing bugs or feature requests fly by that particularly interest you. Also, a great place to look for outstanding, unclaimed tasks is the Issue Tracking database on the Subversion website. There you will find the current list of known bugs and feature requests. If you want to start with something small, look for issues marked as "bite-sized".

To edit the code, you need to have the code. This means you need to check out a working copy from the public Subversion source repository. As straightforward as that might sound, the task can be slightly tricky. Because Subversion's source code is versioned using Subversion itself, you actually need to "bootstrap" by getting a working Subversion client via some other method. The most common methods include downloading the latest binary distribution (if such is available for your platform), or downloading the latest source tarball and building your own Subversion client. If you build from source, make sure to read the INSTALL file in the top level of the source tree for instructions.

After you have a working Subversion client, you are now poised to checkout a working copy of the Subversion source repository from http://svn.collab.net/repos/svn/trunk: ^[34]

$ svn checkout http://svn.collab.net/repos/svn/trunk subversion
A  HACKING
A  INSTALL
A  README
A  autogen.sh
A  build.conf
...

The above command will checkout the bleeding-edge, latest version of the Subversion source code into a subdirectory named subversion in your current working directory. Obviously, you can adjust that last argument as you see fit. Regardless of what you call the new working copy directory, though, after this operation completes, you will now have the Subversion source code. Of course, you will still need to fetch a few helper libraries (apr, apr-util, etc.)—see the INSTALL file in the top level of the working copy for details.

Now that you have a working copy containing the latest Subversion source code, you will most certainly want to take a cruise through the HACKING file in that working copy's top-level directory. The HACKING file contains general instructions for contributing to Subversion, including how to properly format your source code for consistency with the rest of the codebase, how to describe your proposed changes with an effective change log message, how to test your changes, and so on. Commit privileges on the Subversion source repository are earned—a government by meritocracy. ^[35] The HACKING file is an invaluable resource when it comes to making sure that your proposed changes earn the praises they deserve without being rejected on technicalities.

With the code and community policy understanding in hand, you are ready to make your changes. It is best to try to make smaller but related sets of changes, even tackling larger tasks in stages, instead of making huge, sweeping modifications. Your proposed changes will be easier to understand (and therefore easier to review) if you disturb the fewest lines of code possible to accomplish your task properly. After making each set of proposed changes, your Subversion tree should be in a state in which the software compiles with no warnings.

Subversion has a fairly thorough ^[36] regression test suite, and your proposed changes are expected to not cause any of those tests to fail. By running make check (in Unix) from the top of the source tree, you can sanity-check your changes. The fastest way to get your code contributions rejected (other than failing to supply a good log message) is to submit changes that cause failure in the test suite.

In the best-case scenario, you will have actually added appropriate tests to that test suite which verify that your proposed changes actually work as expected. In fact, sometimes the best contribution a person can make is solely the addition of new tests. You can write regression tests for functionality that currently works in Subversion as a way to protect against future changes that might trigger failure in those areas. Also, you can write new tests that demonstrate known failures. For this purpose, the Subversion test suite allows you to specify that a given test is expected to fail (called an XFAIL), and so long as Subversion fails in the way that was expected, a test result of XFAIL itself is considered a success. Ultimately, the better the test suite, the less time wasted on diagnosing potentially obscure regression bugs.

After making your modifications to the source code, compose a clear and concise log message to describe those changes and the reasons for them. Then, send an email to the developers list containing your log message and the output of svn diff (from the top of your Subversion working copy). If the community members consider your changes acceptable, someone who has commit privileges (permission to make new revisions in the Subversion source repository) will add your changes to the public source code tree. Recall that permission to directly commit changes to the repository is granted on merit—if you demonstrate comprehension of Subversion, programming competency, and a "team spirit", you will likely be awarded that permission.

雖然 Subversion 的子命令有許多不同的選項, 但是所有的選項都是全面通用的 — 也就是不管使用的子命令為何, 每個選項都保證表示同樣的東西. 像是 --verbose (-v) 一定是 “詳細輸出”, 不管你與哪個子命令使用.