スタックブランチを利用する
==========================

.. _motivation:

ユースケース
--------------

あるプロジェクトで作業しようとしていて、公開されているリポジトリに対して
読み込みアクセスはできるものの書き込みができないとしましょう。
公開されているリポジトリと同じホストで自分のブランチを公開したりバックアップ
したりする場合、スタックブランチを使うことができるかもしれません。

スタックブランチの他のユースケースとしては、実験的なブランチと、コード
ホスティングサイトが挙げられます。これらのシナリオではスタックブランチの
特性がぴったりあいます。


スタックブランチとは？
-------------------------

スタックブランチ(stacked branch)は別の(スタック先)ブランチのリビジョンを
見つける方法を知っています。
スタックブランチはスタック先ブランチには存在しないユニークなリビジョンのみを
保存することで、ブランチの作成を高速にしたり、ディスク利用効率を向上します。
これらの観点から、スタックブランチは共用リポジトリと似ています。
しかしながら、スタックブランチは追加の利点があります:

* 新しいブランチはスタックされたブランチとは完全に異なる位置に設置できます。

* スタックブランチを削除すれば(共用リポジトリだと残ってしまう)
  リビジョンの情報も削除されます

* セキュリティは共用リポジトリよりも向上しています。
  スタック先のリポジトリはスタックブランチにコミットする開発者に対して
  物理的にリードオンリーだからです。


スタックブランチを作成する
--------------------------

スタックブランチを作成するには、branchコマンドの ``stacked`` オプションを使用します。
例です::

  bzr branch --stacked source-url my-dir

このコマンドによって ``my-dir`` がローカルリビジョンなしのスタックブランチ\
として作成されます。
定義されると、 ``source-url`` に関連づけされた公開ブランチは
*スタックドオン(stacked on)* の位置として使われます。
さもなければ、 ``source-url`` は *スタックドオン* の位置になります。


スタックチェックアウトを作成する
-----------------------------------

スタックチェックアウトを直接作成する機能はまもなくサポートされる予定です。
それまでの間、2段階の処理が必要です:

1. 上記で示されたようにスタックブランチを作成する。

2. ``reconfigure`` もしくは ``bind`` コマンドのどちらかを利用して
   ブランチをチェックアウトに変換する。


スタックブランチをプッシュする
---------------------------------

多くのプロジェクトの大部分の変更は
*開発トランク* or *現在の安定* ブランチといった既存のブランチを基礎としています。
これらの1つにスタックされた新しいブランチの作成は ``push`` コマンドを利用して
次のように簡単にできます::

  bzr push --stacked-on reference-url my-url

このコマンドでは、 ``reference-url`` にスタックした新しいブランチを ``my-url``
に作成し、 ``reference-url`` には無いリビジョンだけをそこに格納します。
``my-url`` は ``reference-url`` と同じホストでも構いません。

.. The following text is hidden because bug 375013 breaks the example.
   When bug 375013 is fixed, we should unhide this text.
      - Andrew Bennetts, 10 March 2010

ローカルブランチがスタックブランチとして作成された場合、
``push`` するには ``--stacked`` オプションを使うことが可能で
スタック先の位置を省略できます。::

  bzr branch --stacked source-url my-dir
  cd my-dir
  (hack, hack, hack)
  bzr commit -m "fix bug"
  bzr push --stacked

この使い方は、上述したユースケースにマッチしています。


スタックブランチの制限
----------------------

スタックブランチに関して覚えておくべき大事なことは、ほとんど全ての\
オペレーションでスタック先ブランチが必要になることです。
これは両方のブランチがローカルもしくは同じサーバーにあるときは\
問題にはなりません。

また、ほとんどの履歴がスタック先リポジトリに格納されているので、スタック先
リポジトリへのアクセスがネットワーク経由だった場合に ``bzr log``
のようなコマンドが遅くなるかもしれません。
 
スタックするブランチを変更する
-------------------------------

``bzr reconfigure`` コマンドを使ってスタックドオンブランチを変更したり\
スタックするのをやめたりすることができます。
``bzr reconfigure --unstacked`` を実行した場合、bzrは全ての参照されているデータを\
スタックドオンブランチからスタックされていたブランチにコピーしてくることに\
注意してください。
大きなレポジトリにおいては、これは時間がかかったりリポジトリサイズを増大\
させたりします。