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
…