パッチログとプロジェクトツリーの履歴

前章では、ブランチとマージについて習いはじめました. そこで、missing、update、replayの ようなコマンドが, プロジェクトの複数のブランチを追跡し, そこでの変更を適用 するのにどのように使えるかを知りました.

この章では、 パッチログ (patch logs) についてちょっと説明します。 これはプロジェクトツリーの履歴を追跡するのためのものです. また, 賢いマージのためのものでもあります.

まず、以前の章でパッチログに出会ったことを思い出しましょう (例えば、新規ソースツリーの開始で、最初にプロジェクトツリーを初期化したときです). この章では、パッチログをもう少し詳しく説明します.

プロジェクトツリーはパッチログを持っています

アーカイブにおける, すべての初期のインポート、タグリビジョン, およびチェンジセットリビジョンは関連するログメッセージを持つことを思い出してください。 そのメッセージの構成は、あなたが import や commit のようなコマンドで与えるヘッダおよび本体と, それに加えて, arch が自動的に生成するものからのものです.

プロジェクトツリーがアーカイブへ最初にインポートされる場合、新しいリビジョンのパッチログエントリーがツリーに加えられます。 commit があるとき、コミットする過程の一部として、新しいリビジョンのログエントリーがツリーに加えられます。 tag コマンドで作られたリビジョンを get すると, それがタグリビジョンへのパッチログエントリーを含むことに気づくでしょう。

パッチログエントリーは蓄積していきます。 したがって、例えば, 各コミットは、新しいログエントリーを追加し, 以前のログエントリー全ては保存されます. 各タグリビジョンは、タグへのエントリーだけでなく, タグ付されたリビジョンから継承されたすべてのログエントリーも含みます.

以前の例に戻って、アリスとボブの patch-2 リビジョンを見てみましょう:

        % cd ~/wd

        [... 以前の例でのディレクトリを消去する ...]

        % tla get -A lord@emf.net--2003-example \
                    hello-world--mainline--0.1--patch-2 \
                    hw-AnB-2

        [...]

        % cd ~/hw-AnB-2

まず、パッチログは arch のバージョン名で整列されてることを 注意しておきます. このツリーは、だた1つのバージョンからのログを持っています:

        % tla log-versions
        lord@emf.net--2003-example/hello-world--mainline--0.1

そのバージョン内に、初期のインポート, および, 二つのチェンジセットについてのログがあります:

        % tla logs -A lord@emf.net--2003-example \
                       --summary \
                       hello-world--mainline--0.1
        base-0
            initial import
        patch-1
            Fix bugs in the "hello world" string
        patch-2
            commented return from main

それらのログエントリーのうちの 1つを特に調べると:

        % tla cat-log -A lord@emf.net--2003-example \
                        hello-world--mainline--0.1--patch-2
        Revision: hello-world--mainline--0.1--patch-2
        Archive: lord@emf.net--2003-example
        Creator: Tom (testing) Lord <lord@emf.net>
        Date: Wed Jan 29 12:46:50 PST 2003
        Standard-date: 2003-01-29 20:46:50 GMT
        Summary: commented return from main
        Keywords: 
        New-files: \
          {arch}/[...]/hello-world--mainline--0.1/[...]/patch-log/patch-2
        Modified-files: main.c
        New-patches: \
          lord@emf.net--2003-example/hello-world--mainline--0.1--patch-2

        Added a comment explaining how the return from `main'
        relates to the exit status of the program.

例えば、patch-2 changeset がファイル main.c を修正し、新しいファイルであるログエントリー自体(名前は上記の出力のように短縮されます)を加えたことがわかります.

他の例で考慮に値するのは、キャンディスのツリーに由来するものです。 彼女が tagを使って, アリスとボブのツリーの patch-1 リビジョンからフォークしたことを思い出してください. そのため, 以下のようになります:

        % cd ~/wd

        % tla get -A candice@candice.net--2003-candice \
                    hello-world--candice--0.1--patch-2 \
                    hw-C-0

        [...]

        % cd ~/hw-C-0

        % tla log-versions
        candice@candice.net--2003-candice/hello-world--candice--0.1
        lord@emf.net--2003-example/hello-world--mainline--0.1

        % tla logs  -A lord@emf.net--2003-example \
                        --summary \
                        hello-world--mainline--0.1
        base-0
            initial import
        patch-1
            Fix bugs in the "hello world" string


        % tla logs  -A candice@candice.net--2003-candice \
                        --summary \
                        hello-world--candice--0.1
        base-0
            tag of \
              lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1

どのように動作するか -- missing

以前の章では、 missing コマンドで, アーカイブにコミットされてるけども, 特定のプロジェクトツリーに反映されていない変更点を知る方法を習いました (なぜアリスがコミットできないかについて検討するおよび新ブランチの探索を参照).

いまやそれらのコマンドがどのように動作するかを理解するのは簡単なはずです. arch で、特定のバージョンでのリビジョン全てを一覧するのに revisions コマンドを使います:

        % tla revisions -A lord@emf.net--2003-example \
                          hello-world--mainline--0.1
        base-0
        patch-1
        patch-2
        patch-3

これらはアーカイブのログです。 arch は、プロジェクトツリーがログエントリーを持っている リビジョンを一覧するのに logs を使います:

        % tla logs -A lord@emf.net--2003-example \
                       hello-world--mainline--0.1
        base-0
        patch-1
        patch-2

それら 2つのリスト間の差分は missingの出力です:

        % tla missing -A lord@emf.net--2003-example \
                      hello-world--mainline--0.1
        patch-3

変更履歴とツリーの系統の概念

パッチログは、ツリーの履歴に対する重要な洞察を与えます。 取り上げるべき二つの観点があります: 変更履歴 (change history) の観点、および ツリーの系統 (tree ancestry) の観点からです。

変更履歴

ツリーに, とあるチェンジセットの commit に対応するログがあるとき, これが意味することは, その commit からの変更がツリーに適用されたことです: そのチェンジセットの commit はツリーの "変更履歴"の一部分です. 例えば, もしチェンジセットがバグフィックスなら、これはバグフィックスがツリーの中にあることの目安です。

注意: 与えられたチェンジセットがツリーの変更履歴の一部であるという単なる事実は、そのチェンジセットによって行なわれた変更がツリーの中にあるという絶対的な証明ではありません。 例えば、それらの変更は後の変更によって"元に戻された"可能性もあります. しかし、変更履歴はツリーの状態を調査し理解するための有用な道具です.

ツリーの系統 (Tree Ancestry)

アーカイブされたリビジョンが, 自身までに至るアーカイブリビジョンの バージョンにおける全てのリビジョンのパッチログエントリーを持つ場合, そのアーカイブされたリビジョンは, いわば, プロジェクトツリーの ツリーの祖先 (tree ancestor) といえます.

したがって、例えば、キャンディスのタグリビジョンは, アリスとボブの patch-1 リビジョンを祖先として持ちます. というのも, それはアリスとボブのリビジョンのログを持つからです:

        base-0
        patch-1

また、キャンディスの patch-2 リビジョンは、アリスとボブの patch-2 と patch-3 からの変更をマージしていますが、 これらの追加的なリビジョン両方を祖先として持ちます (ブランチ元のバージョンからの更新を参照).

チェンジログの自動生成

tla changelog コマンドは、パッチログから GNUスタイルのチェンジログファイルを生成します:

        
  % cd ~/wd

  % tla get -A candice@candice.net--2003-candice \
              hello-world--candice--0.1 \
              hw-C-latest
  [....]

  % cd ~/wd/hw-C-latest

  % tla changelog
  # do not edit -- automatically generated by arch changelog
  # arch-tag: automatic-ChangeLog-- [...]
  #

  2003-01-30 GMT  Tom (testing) Lord <lord@emf.net>       patch-2

      Summary:
        merge from mainline sources
      Revision:
        hello-world--candice--0.1--patch-2
  
      Patches applied:
      
        * lord@emf.net--2003-example/hello-world--mainline--0.1--patch-3
           added copywrong statements
      
        * lord@emf.net--2003-example/hello-world--mainline--0.1--patch-2
           commented return from main
      
  
      new files:
       {arch}/ [...] /hello-world--mainline--0.1 [...] /patch-2
       {arch}/ [...] /hello-world--mainline--0.1 [...] /patch-3
  
      modified files:
       hw.c main.c
  
      new patches:
       lord@emf.net--2003-example/hello-world--mainline--0.1--patch-2
       lord@emf.net--2003-example/hello-world--mainline--0.1--patch-3
  
  
  2003-01-30 GMT  Tom (testing) Lord <lord@emf.net>       patch-1
  
      Summary:
        Punctuated the output correctly
      Revision:
        hello-world--candice--0.1--patch-1
  
      
      This program should say "hello, world" not "hello world".
      
  
      modified files:
       hw.c
  
  
  2003-01-30 GMT  Tom (testing) Lord <lord@emf.net>       base-0
  
      Summary:
        tag of lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1
      Revision:
        hello-world--candice--0.1--base-0
  
      (automatically generated log message)
      
  
      new patches:
       lord@emf.net--2003-example/hello-world--mainline--0.1--base-0
       lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1
  

生成された チェンジログが タグライン (tagline)を含むことに注意してください。 プロジェクトツリーに changelogコマンドの出力を保存するなら、 タグラインの id を使うか, tagline の idと一致する 明示的な id を与えることで, commit のようなコマンドは その ChangeLog を自動的に最新のものに追随させるでしょう.