コードライン、ブランチング、およびストリーム

この章では、ディポ内のファイルの集合を保守するために必要なタスクについて説明します。次のような問題に対応します。

  • ディポディレクトリ構造およびリポジトリの最適な編成方法

  • コードラインおよびプロジェクトディレクトリにおける、ファイルとファイル変更の移動

  • ラベルまたはチェンジリストを使用したファイルセットの特定

コードライン管理をより簡単に行うために、多数のベストプラクティスと自動制御が一体化されたPerforceの機能、ストリームを使用することができます。本章には、Perforceコマンドラインクライアントを使用してストリームを管理する方法を説明するセクションがあります。基本情報については、『PERFORCE入門http://www.perforce.com/perforce/r15.1/manuals/intro/index.html』を参照してください。ストリームの詳細については、『P4Vユーザーズガイド』の『ストリームを使用する』を参照してください。

この章ではソフトウェアのコードベースの保守に焦点を当てていますが、タスクの多くは、ウェブサイトなど他のファイル集合の管理にも関連します。ベストプラクティスについては、Perforceウェブサイトにある白書をご覧ください。

基本用語

以降のセクションを理解しやすくするため、Perforceにおける関連用語の定義を次に示します。

用語

定義

ブランチ

(名詞)新規追加ではなくコピーにより作成された、関連するファイルの集合。関連するファイルの集合は、多くの場合、コードラインと呼ばれます。

(動詞)ブランチを作成すること。

統合

ファイルの祖先を保存して既存のファイルから新しいファイルを作成すること(ブランチング)、または1つファイルセットから別のファイルセットに変更を反映すること(マージ)。

マージ

通常P4Mergeなどのマージツールを使用して、2つの衝突しているファイルリビジョンの内容を単一のファイルに結合するプロセス。

衝突解決

2つのファイルリビジョン間の差分を調整するために使用するプロセス。衝突解決の方法として、サブミット対象のファイルを選択するか、衝突しているファイルの内容をマージするか選択できます。

ディポを編成する

ディポは、最上位のディレクトリと考えることができます。ディポの編成方法を決定する際は、次の要素を考慮してください。

  • 内容のタイプ: 自分のプロジェクトおよびそれらの関係の性質に基づいて、ディポまたはメインラインディレクトリを作成します(例えば、別々のスケジュールで開発された複数のコンポーネントを含むアプリケーション)。

  • リリース要件: 1つのプロジェクト内で、それぞれのリリースにブランチを作成して、ブランチ間の変更を反映させて、機能およびバグ修正の導入を制御します。

  • ビルドの管理: ラベルとチェンジリストを使用して、ビルドされたファイルリビジョンを制御します。クライアント仕様とビューを使用してビルド範囲が明確にします。

基本的かつ論理的にディポを編成するには、プロジェクトごとにサブディレクトリ(コードライン)を作成します。例えば、自分の会社がJamプロジェクトにかかわっている場合、1つのコードラインを現在開発中のリリース専用にし、もう1つのコードラインを既にリリース済みのソフトウェア専用にし、もう1つを会社のウェブサイト専用にすることが考えられます。開発者は各自のクライアントビューを変更して、ファイルを各自のプロジェクトにマッピングでき、関係のない他のプロジェクトを除外できます。例えば、アールがウェブサイトの保守を担当している場合、アールのクライアントビューは次のようになります。

//depot/www/dev/...     //earl-web-catalpa/www/development/...
//depot/www/review/...  //earl-web-catalpa/www/review/...
//depot/www/live/...    //earl-web-catalpa/www/live/...

同じくJamプロジェクトにかかわっているゲイルは、自分のクライアントビューを次のように設定します。

//depot/dev/main/jam/... //gale-jam-oak/jam/...

ディポはプロジェクトまたはコードラインの用途にしたがって編成することができます。例えば、プロジェクトにしたがってディポを編成するには、次のような構造を使用することができます。

//depot/project1/main/
//depot/project1/release 1.0/
//depot/project1/release 1.1/

一方、各コードラインの用途にしたがってディポを編成するには、次のような構造を使用することができます。

//depot/main/project1/
//depot/main/project2/
//depot/release1.0/project1/
//depot/release1.0/project2/
//depot/release2.0/project1/
//depot/release2.0/project2/

各プロジェクトに対して1つずつディポを作成する方法もあります。ブランチングおよび統合をできるだけ単純化できる構造を選択し、操作の履歴を理解しやすいようにしてください。

コードラインにデータを読み込む

履歴を含まないコードラインを作成している場合、p4 addコマンドを使用してファイルを追加した後、p4 copyを使用してブランチを作成します。例えば、前の節で示したメインライン構造を作成するには、以下の手順で操作します。

  1. ワークスペースにメインラインファイル用のローカルフォルダを作成します。例:

    mkdir c:\p4clients\myworkspace\depot\main\
    
  2. 新たに作成されたフォルダにProject1とProject2のファイルをコピーします。

  3. ファイルをディポに追加します。

    p4 add //depot/main/project1/...
    p4 add //depot/main/project2/...
    p4 submit
    
  4. リリース・ブランチを作成します。

    p4 copy //depot/main/project1/... //depot/release1.0/project1/...
    p4 copy //depot/main/project2/... //depot/release1.0/project2/...
    p4 submit
    

これで、p4 copyp4 mergep4 integrateの各コマンドを使用して、メインブランチとリリースブランチの間で変更を伝播できるようになりました。(また、履歴上の関連が反映元と反映先との間にあり、それを維持する必要がある場合は、p4 integrateコマンドを使用してコードラインに別のコードラインからデータを読み込むこともできます。)

簡易的な方法: p4 populate

反映先コードラインが完全に空である(削除済みのファイルも含め、いかなるファイルも存在しない)場合、Perforceではファイルを既存の反映元コードラインからコピーし、関連するチェンジリストをサブミットする処理を自動化したコマンドが提供されています。

例えば、以下の2つのコマンドを使用してrelease1.0ブランチにデータを読み込む代わりに、

p4 copy //depot/main/project1/... //depot/release1.0/project1/...
p4 submit

p4 populateコマンドを使用してブランチにデータを読み込むことができます。

p4 populate //depot/main/project1/... //depot/release1.0/project1/...

コードラインをブランチする

ブランチングは、関連するファイル間の関係を保守する方法です。ブランチは、それ自身の祖先や子孫から独立して発展させることができ、必要に応じて1つのブランチから別のブランチに変更を伝達(反映)することができます。PerforceのインターファイルブランチングTM により、リソースの消費を最小限に留めながら、ファイルとその祖先との関係を保持します。

ブランチを作成するには、p4 integrateコマンドを使用します。p4 integrateコマンドは、既存のファイルセット間での変更の伝達にも使用されます。変更の反映に関して詳しくは、変更を反映させるを参照してください。

ブランチを作成するタイミング

2つのファイルセットでサブミットの方針が異なる場合、または別々に発展させる必要がある場合には、ブランチを作成します。例:

  • 問題 :開発グループは、コードのコンパイルの有無に関係なく、コードが変更されるたびにそのコードをディポにサブミットしたいと考えているが、リリースエンジニアは、デバッグ、検証、承認が完了するまでコードをサブミットしたくないと考えている。

    解決策: 開発コードラインをブランチして、リリースブランチを作成します。開発コードラインが準備できると、リリースコードラインに統合します。パッチやバグ修正はリリースコードで行われ、開発コードに再度反映されます。

  • 問題: ある会社では、新しいマルチプラットフォームプリンタのドライバを書いています。UNIXデバイスのドライバを書き終え、OS Xのドライバを書く作業に取り掛かろうとしています。

    解決策: 既存のUNIXコードからOS Xブランチを作成します。これらのコードラインは別々に展開することができます。一方のコードラインでバグが見つかった場合、バグ修正をもう一方のコードラインに反映することができます。

基本戦略の1つは、//depot/main/でコードを開発する一方で、リリース用のブランチを作成することです(例えば、//depot/rel1.1/)。リリース固有のバグ修正をリリースブランチで行い、必要に応じて、バグ修正内容を//depot/main/コードラインに反映します。

ブランチを作成する

ブランチを作成するには、p4 integrateコマンドを使用します。ブランチを作成すると、Perforceはブランチされたファイルとそれらの祖先との間の関係を記録します。

ファイル仕様またはブランチ仕様を使用してブランチを作成することができます。単純なブランチの場合は、ファイル仕様を使用します。複雑なファイルセットに基づくブランチの場合、またはブランチの定義方法を確実に記録しておきたい場合は、ブランチ仕様を使用します。ブランチ仕様は、その後の統合にも使用することができます。またブランチ仕様は、コードラインの方針の記録としても役立てることができます。

ブランチ仕様を使用する

ファイルセットを反映元から反映先にマッピングするには、ブランチマッピングを作成し、p4 integrateコマンドを発行する際に引数として使用することができます。ブランチマッピングを作成するには、p4 branch branchnameコマンドを発行し、対象とするマッピングView:フィールドで指定します。このとき、反映元ファイルを左側、反映先ファイルを右側に示します。反映先ファイルとディレクトリがクライアントビューにあることを確認してください。ブランチマッピングを作成または変更しても、ディポ内またはクライアントワークスペース内のファイルには一切影響しません。ブランチマッピングは反映元ファイルを反映先ファイルにマッピングするだけです。

ブランチマッピングを使用してブランチを作成するには、p4 integrate -b branchnameコマンドを発行します。その後、p4 submitを使用して反映先のファイルをディポにサブミットします。

クライアントビューと同様、ブランチ仕様には、複数のマッピングと除外マッピングを含めることができます。例えば、次のブランチマッピングは、テストスクリプトを除いて、メインのコードラインからJam 1.0ソースコードをブランチします。

Branch:   jamgraph-1.0-dev2release

View:
    //depot/dev/main/jamgraph/...       //depot/release/jamgraph/1.0/...
    -//depot/dev/main/jamgraph/test/... //depot/release/jamgraph/1.0/test/...
    //depot/dev/main/bin/glut32.dll     //depot/release/jamgraph/1.0/bin/glut32.dll

上記のブランチマッピングを使用してブランチを作成するには、次のコマンドを発行し、

p4 integrate -b jamgraph-1.0-dev2release

p4 submitを使用して変更をサブミットします。

ブランチマッピングを削除するには、p4 branch -d branchnameコマンドを発行します。ブランチマッピングを削除しても、既存のファイルやブランチには一切影響しません。

ワークスペースビューと同様、ブランチビューにあるファイル名またはパスに空白が含まれる場合、必ずパスを引用符で囲んでください。

//depot/dev/main/jamgraph/... "//depot/release/Jamgraph 1.0/..."

ファイル仕様を使用する

ファイル仕様を使用してブランチするには、反映元ファイルと反映先ファイルを指定してp4 integrateコマンドを発行します。反映先ファイルはクライアントビューになければなりません。反映元ファイルがクライアントビューにない場合、ディポシンタックスを使用して指定します。

ファイル仕様を使用してブランチを作成するには、以下の手順を実行します。

  1. ブランチされるファイルをディポ内およびクライアントワークスペース内のどこに配置するか決定します。対応するマッピング仕様を自分のクライアントビューに追加します。

  2. p4 integrate source_files target_filesコマンドを発行します。

  3. ブランチされたファイルを含むチェンジリストをサブミットします。反映先ファイルを含むブランチがディポ内に作成されます。

Example 30. ファイル仕様を使用してブランチを作成する

Jamのバージョン2.2がリリースされたばかりで、バージョン3.0での作業が始まろうとしています。保守作業のため、Version 2.2を//depot/release/jam/2.2/...にブランチする必要があります。

ブルーノはp4 clientを使用して、自分のクライアントビューに次のマッピングを追加します。

//depot/release/jam/2.2/... //bruno_ws/release/jam/2.2/...

ブルーノは次のコマンドを発行してブランチを作成します。

p4 integrate //depot/dev/main/jam/... //bruno_ws/release/jam/2.2/...

最後に、ブルーノはp4 submitコマンドを発行します。これで、新しくブランチされたファイルがディポに追加されます。

変更を反映させる

ブランチを作成後、ブランチ間に変更を伝達する必要があるかもしれません。例えば、リリースブランチでバグを修正すると、修正内容をメインのコードラインに組み込みたいと考えるでしょう。選択した変更をブランチされたファイル間で伝達するには、p4 integratep4 merge、またはp4 copyコマンドを次のように使用します。

  1. p4 integrateコマンドを発行してファイルの衝突解決をスケジュールします。(多くの場合、p4 mergeまたはp4 copyも使用することができます。)

  2. p4 resolveコマンドを発行し、反映元ファイルから反映先ファイルに変更を伝達します。

    個々の変更を伝達するには、マージファイルを編集するか、マージプログラムを使用します。変更がクライアントワークスペースにある反映先ファイルに加えられます。

  3. 解決済みファイルを含むチェンジリストをサブミットします。

Example 31. ブランチされたファイル間で変更を伝達する

ブルーノは、Jamプロジェクトのリリース2.2ブランチにおけるバグを修正したので、修正内容をメインのコードラインに反映させる必要があります。自分のホームディレクトリから、ブルーノは次のように入力します。

p4 integrate //depot/release/jam/2.2/src/Jambase //depot/dev/main/jam/Jambase

すると、次のメッセージが表示されます。

//depot/dev/main/jam/Jambase#134 - integrate from //depot/release/jam/2.2/src/Jambase#9

これで、ファイルの衝突解決がスケジュールされました。ブルーノがp4 resolveと入力すると、標準マージダイアログが画面に表示されます。

//depot/dev/main/jam/Jambase - merging depot/release/jam/2.2/src/Jambase#9
Diff chunks: 0 yours + 1 theirs + 0 both + 0 conflicting
Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [at]:

ブルーノはファイルの衝突を解決します。完了すると、ブルーノのワークスペースのファイルが結果ファイルによって上書きされます。結果ファイルを含むチェンジリストをディポにサブミットする必要があります。

p4 integratep4 merge、またはp4 copyコマンドを実行するには、反映先ファイルのPerforce書き込み権限(write)と、反映元ファイルの読み取り権限(read)が必要です。Perforceの権限について詳しくは、『Perforceサーバ管理者ガイド: 基本』を参照してください。

デフォルトでは、p4 integrateコマンドによってクライアントワークスペースで新規作成されたファイルは、サブミットしないと編集できません。新しく反映されたファイルをサブミットする前に編集するには、衝突を解決した後、p4 editコマンドを発行します。

反映されるリビジョンの範囲に削除済みのリビジョンが含まれる場合(例えば、ファイルがディポから削除された後に再度追加された場合)、削除済みリビジョンの反映方法を-Diオプションを使用して指定することができます。詳細については、『P4コマンドリファレンス』を参照してください。

ブランチ仕様を使用して反映させる

1つのファイルセットおよびディレクトリから変更を反映させるには、p4 integrateコマンドを発行するときにブランチマッピングを使用することができます。ブランチマッピング使用時のintegrateコマンドの基本構文は以下のとおりです。

p4 integrate -b branchname [tofiles]

反映先ファイルはブランチビューとクライアントビューの両方でマッピングされている必要があります。反映元ファイルは、クライアントビューにある必要はありません。tofiles引数を省略すると、ブランチ内のすべてのファイルが影響を受けます。

ブランチマッピングを使用して逆方向の反映操作を行うには、-rオプションを指定します。このオプションにより、それぞれの方向に対してブランチマッピングを作成せずに、2つのブランチ間で双方向の反映操作を行うことができます。

Example 32. ブランチ内にある単一のファイルに変更を反映させる

メインのJamコードラインに機能が1つ追加されました。ブルーノはこの機能をリリース1.0に伝達したいと考え、次のように入力します。

p4 integrate -b jamgraph-1.0-dev2release *.c

すると、次のように表示されます。

//depot/release/jam/1.0/src/command.c#10 - integrate from //depot/dev/main/jam/command.c#97

これで、ファイルの衝突解決がスケジュールされました。ブルーノがp4 resolveと入力すると、標準マージダイアログが画面に表示されます。

//depot/release/jam/1.0/src/command.c - merging //depot/dev/main/jam/command.c#97
Diff chunks: 0 yours + 1 theirs + 0 both + 0 conflicting
Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [at]:

ブルーノはファイルの衝突を解決します。完了すると、ブランチされたクライアントワークスペース内のファイルが結果ファイルによって上書きされます。その後、この結果ファイルをディポにサブミットする必要があります。

関連性のないファイル間で反映させる

反映先ファイルがソースファイルからブランチされていない場合、base(共通の祖先)リビジョンが存在しません。Perforceは反映元ファイルの最初の(最も新しく追加された)リビジョンをベースリビジョンとして使用します。この操作はベースのないマージと呼ばれます。

特定のファイルリビジョンを反映させる

デフォルトでは、integrateコマンドは、最後に反映されたソースリビジョン以降のすべてのリビジョンを、反映先ファイルに反映させます。反映対象のリビジョン範囲を指定することで、編集中にマージファイルから不要なリビジョンを手動で削除する必要がなくなります。p4 integrateを使用している場合、baseファイルは最も近い共通の祖先となります。p4 mergeを使用している場合、baseファイルは共通の編集が最も多いリビジョンとなります。

Example 33. 特定のファイルリビジョンを反映させる

ブルーノはメインのコードラインで//depot/dev/main/jam/scan.cに対して2つのバグを修正しました。アールはこの変更をリリース1.0ブランチに反映させたいと考えています。修正がサブミットされて以降、scan.cは何度もリビジョンを経ましたが、アールは自分が必要としているバグ修正がscan.cの30番目のリビジョンに適用されたことを知っています。次のように入力します。

p4 integrate -b jamgraph-1.0-dev2release //depot/release/jam/1.0/scan.c#30,30

反映先ファイル(//depot/release/jam/1.0/scan.c)は引数として与えられていますが、ファイルリビジョンは反映元ファイルに適用されます。アールがp4 resolveを実行すると、ブルーノのファイルの30番目のリビジョンだけが衝突解決のためにスケジュールされます。すなわち、アールはブルーノがリビジョン30でscan.cに加えた変更のみを見ます。

ファイルを再反映させ、衝突を再解決する

反映元ファイルのリビジョンが反映先ファイルに反映されると、そのリビジョンは、同じ反映先ファイルへの今後の反映時にはスキップされます。既に反映済みのファイルを強制的に反映させるには、p4 integrateコマンドの発行時に-fオプションを指定します。

衝突は解決されたが、サブミットされていない反映先ファイルの場合は、p4 resolveコマンドに-fを指定することで衝突を再解決することができます。ファイルの衝突を再解決すると、yoursが新しいクライアントファイル、すなわち、前の解決結果となります。

レポートを反映させる

次のレポートコマンドにより、ブランチおよび反映の対象となるファイルのステータスに関して有用な情報が得られます。プレビューオプション(-n)は、レポート目的で使用することができます。

表示させたい内容

使用するコマンド

反映の結果のプレビュー

p4 integrate -n [filepatterns]

衝突解決がスケジュールされたファイル

p4 resolve -n [filepatterns]

衝突は解決されたが、まだサブミットされていないファイル

p4 resolved

ブランチ仕様のリスト

p4 branches

指定されたファイルの反映履歴

p4 integrated filepatterns

指定されたファイルのリビジョン履歴(指定されたファイルのブランチ元のファイルの反映履歴を含む)

p4 filelog -i [filepatterns]

ストリーム

Perforceストリームは「属性を持つブランチ」であり、ブランチ戦略を反映した階層を構成するコンテナです。ストリームは、変動的なブランチの変更をマージして親ブランチの最新状態との同期を保ち、昇格させるのに十分な程度まで安定したときに作業内容を親にコピーするという、メインライン・ブランチ・モデルを実装するうえで理想的です。ストリームを利用するとPerforceが関連ワークスペースのビューを生成できるため、ユーザが手動でビューを更新して変更をブランチ構造に反映させる必要がなくなります。

ストリームの詳細については、『P4Vユーザーズガイド』の『ストリームを使用する』を参照してください。

ストリームで作業するには、以下の操作を実行します。

  1. ストリームディポを作成する

  2. メインラインストリームを作成し、データを取り込む

  3. 開発ストリームとリリースストリームをブランチする

  4. 変更をマージしてコピーする

ストリームを管理するには、(主に)以下のコマンドを使用します。

  • p4 stream

  • p4 streams

  • p4 merge

  • p4 copy

  • p4 resolve

  • p4 cstat

  • p4 istat

ストリーム引数を受け入れるその他のコマンドを以下に示します。

  • p4 branch

  • p4 client

  • p4 clients

  • p4 diff2

  • p4 dirs

  • p4 integrate

  • p4 interchanges

コマンド構文とオプションに関して詳しくは、『P4コマンドリファレンス』を参照するか、p4 help commandnameコマンドを実行してください。概要を見るには、p4 help streamintroを実行してください。以下のセクションでは、ストリーム関連のタスクについてさらに詳しく説明します。

ストリームのタイプ

ストリームの想定される用法、安定性、および変更フローに従って、ストリーム・タイプを割り当てます。ストリームのタイプを以下に示します

ストリームのタイプ

安定性

想定される変更フロー

   

マージ

コピー

mainline

方針に従えば安定(例: すべてのコードをビルドする)

子(リリースから、または開発へ)から

子(リリースへ、または開発から)へ

virtual

適用外、ストリームの絞り込みに使用

適用外

適用外

development

不安定

親から

親へ

task

不安定

親から

親へ

release

安定性が高い

親へ

親から

マージ」とは、別のストリームの変更を自分のストリームに組み込むことを意味し、衝突を解決する必要がある場合があります。「コピー」は反映元ストリームのコピーを反映先へと伝播することです。下図は基本的なストリーム階層を示します。変更は(より安定性の低いコードラインに)マージダウンされ、(より安定性の高いコードラインに)コピーアップされます。

ストリームのタイプはマージとコピーのデフォルトの動作を定義しますが、ストリーム仕様でtoparent/notoparentオプションおよびfromparent/nofromparentオプションを編集することによって、デフォルト設定を無効にすることができます。

ストリーム・パス

ストリーム・パスは、ストリームを構成するファイルとパスを制御し、それらのファイルの伝播方法を定義します。メインラインを除き、各ストリームは親ストリームの構造を引き継ぎます。子ストリームの構造を変更するには、以下のとおりパスを指定します。

タイプ

同期を実行?

サブミットを実行?

親への/親からの反映を実行?

注意

share

Y

Y

Y

(デフォルト)編集され、親と子のストリーム間で伝播されるファイルに使用。共有パスにあるすべてのファイルはブランチされ、一般に、共有パスの制限は最も寛容です。

isolate

Y

Y

N

バイナリのビルド結果など、ストリームの外への伝播は許容されないが、その中での編集が可能であるファイルに使用。

import

Y

N

N

ストリームに物理的に存在していなければならないが、変更されることのないコンポーネントに使用。例: サードパーティ製ライブラリ。

インポートパスは、特定のチェンジリストを参照してインポートされたコンポーネントをその変更のリビジョンまたはそれ以下のリビジョンに制限することができます。次のように@changelist#構文を使用します。

//depot/lib3.0/...@455678

import+

Y

Y

N

インポートパスと同じように機能します。明示的に定義されたディポパスを参照できますが、標準のインポートパスと異なり、import+パス内のファイルには変更をサブミットできます

exclude

N

N

N

子ストリームに組み込むことが決して許容されない、親ストリーム内のファイルに使用。

次の例では、srcパス内のファイルはサブミット不可(親ストリームのビューからインポートされている)、libパス内のファイルはサブミット不可(ディポ内の明示的な指定場所からインポートされている)、dbパス内のファイルはストリーム内での編集とサブミットが可能ですが、親にコピーすることはできません。

Paths:
    share ...
    import src/...
    import lib/...  //depot/lib3.0/...
    isolate db/...

これらのパスを使用して、ストリームに関連付けられたワークスペースのマッピングが生成されます。ストリーム構造が変化すると、関連するワークスペースのクライアント・ビューが自動的に更新され、事実上手動では変更できません。ストリームがlockedの状態である場合、ストリーム所有者のみ(あるいは、ストリームのOwner:フィールドがグループである場合はそのグループに所属しているユーザ)ストリーム仕様の編集が可能です。

ストリーム仕様により、(指定されたディポの場所にあるファイルがワークスペース内の別の場所に同期されるように)ファイルの場所をマッピングし直して、ファイルタイプに従ってファイルを選抜することも可能です。例えば、オブジェクト・ファイルおよび実行可能モジュールがストリームに含まれないようにするには、以下のエントリをストリーム仕様に追加します。

Ignored:
    .o
    .exe

ストリーム・ディポの作成

ストリームは(「ローカル」ディポではなく)「ストリーム」ディポにあります。ディポを作成するには、super権限がなければなりません。ストリーム・ディポを作成する手順は以下のとおりです。

  1. Perforceスーパーユーザがp4 depot depotnameコマンドを発行します。ディポ仕様フォームが表示されます。(例: p4 depot projectX)

  2. Type:フィールドをstreamに設定します。

  3. その他の設定を適宜調整して、仕様を保存します。

ディポの作成後は、ディポのタイプを変更できないことに注意してください。

ストリームの作成

すべてのストリームは、それらを含むディポの1つ下の(パス)レベルに格納されます。例えばProject Xの場合は、以下のようなディポ・パスをもつ一組のストリームがあると想定されます。

  • //projectX/main

  • //projectX/dev-bruno

  • //projectX/release1.0

  • //projectX/release2.0

など。

まず最初に、ストリーム階層の中央に位置するメインストリームを作成します。多くの場合、メインラインはかなり安定性の高い受信側の幹線であり、子ストリームから開発作業を受け入れ、結果をリリース・ストリームへと伝播することで、進行中の開発を妨害することなく、リリースに向けた安定化とビルドを行うことができます。

メインラインを作成する手順は以下のとおりです。

  1. p4 streamコマンドを、ディポの後にストリーム名を指定して実行します。(例: p4 stream -t mainline //projectX/main)。ストリーム仕様フォームが表示されます。

  2. 必要に応じてオプションを変更して、仕様を保存します。

  3. メインラインストリームが作成されたことを確認するために、p4 streamsコマンドを実行します。(例: p4 streams //projectX/...)。

次に、メインラインにファイルを取り込みます。

メインラインにデータを取り込む

メインラインにデータを取り込むには、以下の2つの方法があります。

  • ローカルのファイルシステムからファイルを追加する

  • 別のディポからファイルをブランチする

ファイルの履歴を保持する必要がある場合は、反映元のファイルをメインライン・ストリームにブランチします。ファイル履歴を保持する必要がない場合は、単にファイルを追加します。以下のセクションで、それぞれの方法について説明します。

最初に、ワークスペースを作成する

ストリームで作業するには、ストリームに関連付けられたワークスペースを作成しなければなりません。ワークスペースをストリームに関連付けると、Perforceはストリームの構造に基づいてワークスペースビューを生成します。ユーザがワークスペース・ビューを編集する必要はありません(実際、手動で変更することはできません)。ストリームの構造が変化すると、PERFORCEは必要に応じて、ストリームに関連付けられたワークスペースのビューを更新します。

(推奨事項: ストリームに関連付けられたワークスペースに名前を割り当てる場合には、user_depot_streamname名などの命名規則を採用してください。例えば、bruno_projectXなどとします。また、異なるタイプのストリームに関連付けられたクライアントワークスペースへの切り替えをたびたび行うユーザは、ストリームタイプをワークスペース名に追加し、bruno_projectX_mainbruno_projectX_devなどとすると有用であるかもしれません)。

ストリーム用のワークスペースを作成する手順は以下のとおりです。

  1. p4 clientコマンドを、-Sオプションを使用して関連ストリームの名前を指定して実行します。(例: p4 client -S //projectX/main bruno_projectX)。

  2. ワークスペース仕様フォームが表示されます。(ストリームに関連付けられたワークスペースにのみ用いられるStream:フィールドに注意してください。)

  3. ワークスペース・ルート・ディレクトリおよび必要なその他の設定を構成して、仕様を保存します。View:フィールドはPerforceによって管理されるため、変更する必要はありません。

  4. ワークスペースが作成されたことを確認するために、p4 clientsコマンドを実行します。(例: p4 clients -S //projectX/main)。

これで、メインラインにファイルを取り込む準備ができました。

ファイルを追加する

反映元ファイルと新しいメインライン・ストリーム内のファイルとの間で履歴の関係を維持する必要がない場合は、単にファイルを追加します。ファイルをメインライン・ストリームに追加する手順は以下のとおりです。

  1. ワークスペース・ルート・ディレクトリが存在しない場合はそれを作成します。例:

    cd C:\Users\bruno\p4clients\
    mkdir bruno_projectX_main
    
  2. ファイルとフォルダをワークスペース・ルート・ディレクトリにコピーします。

  3. クライアントワークスペースのルートディレクトリに移動し、p4 reconcileコマンドを使用してPerforceの制御下にないファイルを検出し、それらを追加目的の作業状態にします。

    p4 reconcile -a

ファイルが正しく追加されるように設定されていることを確認するには、p4 openedコマンドを実行します。ストリームにデータを取り込むには、ファイルが作業状態にされているチェンジリストをサブミットします。

他のディポからブランチする

他のストリーム・ディポ、従来のディポ、またはリモート・ディポからファイルをブランチすることが可能です。ブランチ操作によってメインラインにデータを取り込むと、Perforceは反映元ファイルと反映先ファイルのリビジョン履歴の関係を維持します。ワークスペースには、反映先ストリームに関連付けられたものを設定しなければなりません(例: p4 set P4CLIENT=bruno_projectX_main)。

ブランチ操作によってメインラインにデータを取り込むには、反映元と反映先を指定してp4 copyコマンドを実行します。例:

p4 copy -v //mysourcedepot/mainline/... //ProjectX/main/...

(この例では-vオプションを指定して、ワークスペースにファイルをコピーせずにサーバを更新することによってパフォーマンスを向上させています。)Perforceは一連の「...からインポートします」というメッセージを表示して反映元と反映先のファイルを列挙し、作業中チェンジリストでファイルを作業状態にします。ファイルを作業状態にせずに操作結果をプレビューするには、-nオプションを指定します。誤ったコピー操作を元に戻すには、p4 revert コマンドを実行します。(例: p4 revert //ProjectX/main/...)

ファイルが正しく追加されるように設定されていることを確認するには、p4 openedコマンドを実行します。ストリームにデータを取り込むには、ファイルが作業状態にされているチェンジリストをp4 submit(サブミット)します。

空のストリームにデータを読み込む場合は、p4 populateを使用することでこの処理を簡略化できます。例:

p4 populate //mysourcedepot/mainline/... //ProjectX/main/...

は、p4 copy -vの後にp4 submitを実行した場合と同様に動作します。p4 populateの実行結果を事前に知りたい場合は、p4 populate -nを使用して、コマンドの結果をプレビューします。

子ストリームにデータを取り込む

メインラインにデータを取り込んだ後、開発ストリームとリリース・ストリームにファイルをブランチすることができます。開発ストリームを使用すればメインラインの安定性を損なうことなく試験を行うことができ、リリース・ストリームを使用すれば、メインラインで新機能に取り組んでいる間に既存の機能を完成させることが可能です。例えば、親メインラインのクローンである開発ストリームを作成するには、以下のコマンドを実行します。

p4 stream -t development -P //projectX/main //projectX/dev

タイプがdevelopmentに設定されたストリーム仕様がPerforceに表示されます。この仕様を保存してください。ファイルをメインラインからストリームに取り込むには、次のコマンドを実行します。

p4 client -s -S //projectX/dev bruno_projectX_dev
p4 merge -S //projectX/dev -r
p4 submit -d "Branching from mainline"

または、単にp4 populateを次のように使用します。

p4 populate -d "From main" -S //projectX/dev -P //projectX/main -r //projectX/dev

変更を伝播する

ストリームの使用により、安定したコードを処理中の作業から隔離して、妨害を受けずに様々なプロジェクトに同時に取り組むことが可能になります。安定性のより低いストリームを、安定性のより高いストリームから(マージにより)定期的に更新した後、変更を(コピーにより)安定性の高いストリームに昇格させることが最善の方法です。マージとコピーは効率化された反映形式です。一般には、以下のとおり変更を伝播します。

  • コピーとブランチを行うには、p4 copyを使用します。

  • マージを行うには、p4 mergeを使用します。

  • p4 mergeまたはp4 copyによって対処できなかったその他の場合には、p4 integrateを使用します。

上述したガイドラインは、ストリームと従来のディポの両方に適用されます。

安定性の高いストリームから変更をマージする

安定性のより高いストリームからの変更によってストリームを更新するには、p4 merge -S source-streamコマンドを実行し、必要に応じて衝突解決を行った後、得られたチェンジリストをサブミットします。デフォルトでは、意図した反映先から入って来るあらゆる変更をマージするまで、安定性の高いストリームに変更をコピーすることはできません。これによって、安定性の高いストリームの内容を誤って上書きしてしまうことが避けられます。

開発ストリームで作業を始めた後に、変更がメインラインにチェックインされたと仮定すると(また、ワークスペースが開発ストリームに設定されていると仮定)、以下のコマンドを実行することにより、開発ストリームに変更を組み込むことができます。

p4 merge -S //projectX/dev -r
p4 resolve
p4 submit -d "Merged latest changes"

安定性の高いストリームに変更をコピーする

マージ実行後、ストリームにはより安定した親または子の最新状態が反映されています。開発ストリームに加えたい変更を完成させたと仮定すると、反映先ストリームでの作業を上書きしてしまう危険を伴わずに新しい内容に昇格できます。「コピー」操作では反映元の複製が単に反映先に伝播され、衝突解決は必要とされません。例えば、(ワークスペースが親のメインライン・ストリームに設定されていると仮定して)開発ストリームから親のメインラインに変更を昇格させるには、以下のコマンドを実行します。

p4 copy -S //projectX/dev
p4 submit -d "Check my new feature in"

変更を別のストリーム階層に伝播する

同格の開発ストリームから作成中の機能やバグ修正を取得したい場合など、生来の親子関係を持たない2つのストリーム間で特定の変更を伝播する必要があるかもしれません。そのようなストリームからのマージまたはそのようなストリームへのコピーを行うには、仕様を編集して、Parentフィールドを目的の反映元または反映先に設定することにより、ストリームの親を変更することができます。これは最適な方法とはみなされませんが、必要な場合があるかもしれません。

スパース(希薄)なブランチにタスクストリームを使用する

タスクストリームは開発ストリームと同様に動作するブランチですが、親ストリーム(逆方向)にブランチされるまでは半プライベートな状態に保たれます。このストリームは軽量なブランチとして設計されており、ブランチ内で予測される作業がブランチ内のファイル数と比較して少数のファイルにのみ影響する場合に最も有効です。

タスクストリームには親ストリームが必要ありません。そのため、ストリームディポで作業していないユーザであっても、タスクストリームの利点を得ることができます。(タスクストリームはストリームディポの中にある必要がありますが、管理者がストリームディポをタスクストリーム専用の保存場所として構成することが可能です。)

タスクストリームは、使用後に削除またはアンロードされることが想定されています。タスクストリームを削除した後であっても、そのストリーム名を再利用することはできません。ほとんどのサイトでは、タスクごとに固有の命名規則(user-date-jobnumber)を採用することになります。

タスクストリーム内での作業は、開発ストリームでの作業と同様です。

  1. タスクストリームを作成します(この例では、開発ストリームとして作成)。

    p4 stream -t task -P //projectX/dev //Tasks/mybug123

  2. ストリームにデータを取り込みます。

    p4 populate -d "Fix bug 123" -S //Tasks/mybug123 -P //projectX/dev -r Tasks/mybug123

  3. ストリーム内のファイルに変更を加えます。

  4. 必要な変更を親ストリームからマージダウンします。必要に応じて衝突解決を行います。

    p4 merge -S //Tasks/mybug123 -r

  5. 変更内容を親ストリームにコピーアップします。

    p4 copy -S //Tasks/mybug123 -P //projectX/dev

  6. タスクストリームを削除またはアンロードします。

    p4 stream -d //Tasks/mybug123

    (または、p4 unload -s //Tasks/mybug123を使用してアンロードします。)

タスクストリーム使用時、タスクストリームに関連付けられたワークスペースにおいてのみ、ストリーム内のすべてのファイルを表示することができます。ストリームは、他のワークスペースへのスパースブランチとして表示されます。これらのワークスペースには、タスクストリーム内で変更したファイルとリビジョンのみが表示されます。タスクストリームの他のほとんどのメタデータはプライベートの状態に保持されます。

タスクストリームは削除またはアンロードされるまでディポ内に急速に蓄積されます。プロジェクトのディポがタスクストリームでいっぱいにならないように、Perforce管理者またはプロジェクトリードがタスクストリーム専用の保存領域として特定のストリームディポを構築するとよいでしょう。この場合、プロジェクトディポ内にある親の子ストリームとして、ストリームをタスクストリームのディポ内に作成してください。

ストリームのワークスペースを管理する

このセクションでは、ストリームのワークスペースを管理するための各種方法について説明します。

複数のストリームに単一のワークスペースを使用する

通常は、作業を行うストリームごとにワークスペースを定義します。しかしこの方法では、ストリームに非常に多くのファイルが含まれている場合(例えば数万件から数十万件)、前回作業を行ってから大幅に変更されたストリームに切り替える際に、長時間の同期処理が必要となる可能性があります。ストリームの構造に一貫性があり、ほとんどのファイルが同内容である場合、両方のストリームに異なるワークスペースを使用する代わりにワークスペースを切り替え後のストリームに関連付け直すことによって、この問題を回避することができます。ワークスペースとストリームの関連付けを変更したら、同期を実行し、違いのあるファイルをすべて取得します。

ワークスペースに関連付けられたストリームを変更するには、次のコマンドを実行します。

p4 client -s -S //streamdepot/ streamname

仮想ストリームによりワークスペースの範囲を狭くする

大規模なプロジェクトでは、ストリームを整然と編成してもワークスペースビューを十分に制限できないことがあります。大規模な組織では、プロジェクトのファイルのほんの一部にしか関心のないグループが多数存在することがよくあります。旧バージョンのPerforceでは、こういったユーザは必要な部分のみを含めるように手動でクライアントワークスペースのビューを制限していました。ストリームを利用する別の方法として、virtualストリームをフィルタとして使用することができます。

例えば、次のように進行中の開発作業が//Ace/devストリームで行われているとします。

Stream:  //Ace/dev
Parent: //Ace/main
Type:   development
Paths:
    share ...

(プロジェクトに関するすべての資産ではなく)製品のドキュメントに関する作業にのみ従事しているユーザであれば、以下のように//Ace/dev/docs/...下にあるファイルのみを含む仮想ストリームを作成できます。

Stream:  //Ace/devdocs
Parent: //Ace/dev
Type:   virtual
Paths:
    share docs/...

すると、ユーザは次のコマンドを使用して自分のクライアントワークスペースをdevdocs仮想ストリームに切り替えることができます。

p4 client -s -S //Ace/devdocs

devdocsワークスペースを使用すると、ユーザのクライアントワークスペースのビューが//Ace/dev/docs/...にある要素のみを含むように自動的に更新されます。そして、そのユーザが//Ace/devdocsに加えた変更は自動的に元の//Ace/devコードラインに伝播され、p4 copyまたはp4 integrateを手動で実行する必要はありません。

特定のチェンジリストからストリームを表示する

ワークスペース仕様にあるStreamAtChangeオプションを使用すると、ストリームのビューを特定のチェンジリストから使用して、ストリームワークスペースを設定してストリームを同期できます。これにより、自分のストリームの"振り返り"のビューを表示できるようになります。特にストリーム定義が頻繁に変更される場合、ある特定の時点におけるストリームビューが何であったかを確認する際に役に立ちます。StreamAtChangeオプションを使用する場合は、ストリーム内のファイルに変更をサブミットできません。ワークスペースファイルが最新リビジョンではないためです。

特定のチェンジリストからストリームワークスペースを同期するように設定するには、以下の手順を実行します。

  1. ストリームのワークスペース仕様フォームを編集するために開きます。

    p4 client -S //projectX/main bruno_projectX
    
  2. p4 clientフォームのStreamAtChangeフィールドにチェンジリスト番号を入力します。

詳細については、『P4コマンドリファレンス』p4 clientを参照してください。