☆ CVSシステムの使い方 for MetalGearSolid 2
	1999/07/06 K.Uehara
	$Id: cvs4mgs.txt,v 1.1.1.3 2002/11/19 11:41:42 Yoshizawa1 Exp $

PSメタルのときの反省をふまえ、バージョン管理システムとしてCVSを導入します。
いくつか、約束ごとが増えますので注意してください。

とりあえず、何がうれしいかというと、

・誰が何を変更したかのログが残る。
・上書きによるバージョンダウンが起こりにくい。
・ソースのアップデートがコマンド一発でできる。ミスも起こりにくい。
・いつでもすべてのソースを過去のある時点のソースに戻すことができる。
・RCSにくらべ、チェックイン／アウトが煩雑ではない。

で、何がめんどくさいかというと、

・ソースをアップデートするたびに変更点のコメントを求めてくる。
	->書かないことも可能だが、できれば書こう。
・コマンドラインコマンドを覚える必要あり。
	->ま、でも、思ったより少ない。
・メッセージが全部英語。
	->しゃーない。
・履歴ファイルが膨大になりそう。
	->久米村さんに泣いてもらうということで。

ということで、使います。

----------------------------------------------------------
■ 日本語マニュアル
----------------------------------------------------------

CVSの日本語マニュアルHTML版が、
http://cali.konami/
の、
CVS日本語マニュアル(1.10.5)
から見れるようになっています。

----------------------------------------------------------
■ 注意事項
----------------------------------------------------------

● 環境設定

ホームディレクトリの.cshrc に、以下の行を追加してください。
---ここから
setenv CVSROOT /u/develop/mj001b/cvsroot
setenv CVSEDITOR mule -nw
---ここまで

CVSROOTは、実際にマスターのソース（と履歴）が格納されるパスです。
メタルプロジェクトは、すべてここにソースを集めます。
CVSEDITORは、CVSのコメントを編集するエディタの設定です。
好きなひとはviでもいいです。もし、設定されていない場合は、viになります。
エディタを使うのがじゃまくさい人は、-m "message" をつければ
それが登録されます。

● ソースコメントの統一

各プログラムソースの先頭に以下のコメント行を必ずつけるようにしてください。
＄Id＄(本当は半角) は、CVSを使うと、「最後に触った日付とユーザー」を自動的に
埋め込んでくれます。
(ただし、最後に触った時間はグリニッジ標準時で表示されます)

---ここから
/*
	gamed.c                     [ <- ファイル名 ]
	    ゲーム進行デーモン      [ <- そのファイルの簡単な説明 ]

	1999/07/06 K.Uehara         [ <- 最初のバージョンを作成した時間とユーザー ]
	＄Id＄                      [ <- CVSによって置換される(ほんとは半角) ]

	(ここから下は任意)
*/
---ここまで

● 管理されるファイル

通常のソースファイルはすべて管理します。ただし、stage/の各ステージ用の.cファイルは、
gclconvにて自動生成しますので、管理の対象とはしません。
バイナリファイルは特別なオプションを使って管理できますが、差分履歴が大きくなるので、
なるべく含めない方がいいと思います。

そのディレクトリで管理の対象としないファイルは、.cvsignoreで指定することができます。

● ディレクトリ名

標準のディレクトリ構成は、

mgs2---source		プログラム
     |-module       IOP側のプログラムや共用ライブラリ
     |-list			ステージ毎のデータダウンロードスクリプト
     |-scn			シナリオ
     |-cdrom.img	データディレクトリ

となります。

ソースをダウンロードするときにディレクトリ名を指定してください。

プロジェクト名は mgs2とします。

----------------------------------------------------------
■ 使い方
----------------------------------------------------------

プログラムは、cvs １個です。その後にコマンドを書いて実行します。
めんどくさい場合は、aliasを適当に作った方がいいでしょう。
ここでは、すべてaliasを使わずに表記します。

絶対に覚えるのは、

cvs update
cvs commit

cvs add
cvs remove

cvs checkout

(使用頻度順)です。

--------------------- 最初の1回

● ソースのダウンロード

いままでは、
cp -r /u/develop/mj003/prog/mgs/source .
などで、すべてのファイルを取ってきていましたが、
これが、

cvs checkout mgs2

一発でできるようになります。
カレントに mgs2のディレクトリが作られて、その下にプロジェクトmgs2の
すべてのファイルがコピーされます。
cdrom.imgは作成されませんので、注意してください。
cdrom.imgは mgs2/list の下で、make all を行なうことによりダウンロード
することができます。

mgs2の名前を変えたい場合は

cvs checkout -d ディレクトリ名 mgs2

オプションの場所に注意してください。

すべてのサブディレクトリに CVS/というディレクトリができますが、
これは、管理情報保存用です。気にしなくてOK。逆に、消してはいけません。

--------------------- 基本操作

● ソースを最新の状態に更新する

ほかの人が編集したプログラムを自分のディレクトリに反映させるには、
source の下で、

cvs update

を行うだけです。
その下のディレクトリが再帰的に更新されます。
シナリオの更新を行うときは scnの下で cvs update をしてください。

もし、誰かが新規ディレクトリを作成した場合は、勝手にはダウンロード
されないので、

cvs update -d 

を行う必要があります。~/.cvsrcに書いておくと、便利です。
	(ref.->その他tips .cvsrc)

実行するとファイルが一覧で表示されます。ファイルの前についている
フラグの意味はだいたい以下の通りです。

U : ファイルが更新されました。
M : ファイルはローカルで修正されてます。
	または、ほかの人の修正も同じファイルに入ってましたが、何とかなりました。

C : ほかの人の修正とかぶってます。なんとかしてください。
	( -> 「修正がかぶった場合」参照 )

? : 知らないファイルがあります。必要なら追加してください。
	( -> 「ファイルを追加する場合」参照 )

● 自分が変更したソースの更新

変更したモジュールをアップロードするときは、

cvs commit

を実行してください。
勝手に変更したファイルを探し出して、アップロードしてくれます。

これは、各サブディレクトリの下で行うと、それ以下のディレクトリが
対象になります。
(たとえば、korekado の下だけとかが可能）

cvs commit ファイル名

で、そのファイルだけの更新が可能です。

変更したファイルに対して、EDITORで指定されたエディタが起動して、
変更履歴を入れるように求めてきます。
そのまま、一番上の行に簡単なコメントを入れてください。
２つ以上のファイルを同時にアップデートすると、コメントは
すべてのファイルで共通になります。(ただし同一ディレクトリ内のみ)

コメントを入れずにエディタを終了すると、中止するか、継続するか
聞かれます。継続すればコメントなしで登録できます。

コメントを入れる必要がないときは

cvs commit -m "" [ファイル名]

で、コメントなし、エディタ起動なしで登録できます。

アップデート時に、修正がかぶっていると怒られる場合があります。
	( ->「修正がかぶった場合」参照 )

また、管理者が設定した条件に適合しないと格納できないように
することもできます。

--------------------- かぶった場合

● 修正がかぶった場合

cvs commit や、cvs update で怒られた場合は、慌てず、

cvs update ファイル名

を実行してください。

その後、そのファイルを開けると、変更がかぶっている個所が、

<<<<<<< fileA.c
>>>>>>> 

などで囲まれて表示されるので、それを編集して、ちゃんとコンパイルが
通るようにしてください。

その後、

cvs commit ファイル名

をすれば、そのファイルが登録されるはずです。

＃変にいじりすぎるとまた怒られるかも知れないので、
＃大きな変更がある場合はとりあえず最小限の変更をして
＃commitしてから変更したほうがいいかも。

--------------------- ファイル操作

● ファイルを追加する場合

ソースを追加したときは、

cvs add ファイル名

で、明示的にCVSに追加する必要があります。
これを忘れないで下さい。

これは、ローカルに対する宣言だけなので、追加した後は必ず、

cvs commit

を実行して、アップロードしてください。

● ファイルを削除する場合

ソースを削除するときは、ファイルを削除してから、

cvs remove ファイル名

です。cvs commit も必要です。

ディレクトリを削除することは、CVSでは基本的にできません。
updateの時に、空のディレクトリを削除するオプション、
cvs update -P
をつけることで、削除のかわりとなります。

● リネームする場合

古い名前で削除して、新しい名前で追加してください。
ただし、履歴は新しい名前に関して１から始まります。

--------------------- バージョン操作

● アップロードされているファイルとdiffをとりたい場合

cvs diff file.c

● 最新のファイルに戻したい場合

file.c を戻すとすると、

cvs update -p file.c > file.c

が一番確実らしい。
必要に応じて、バックアップを取っておくといいかも。

また、もっと簡単な方法として、

rm file.c
cvs update

ってのもある。

● 昔のファイルを見たい場合

バージョン番号、または日付を指定して、昔のファイルをとりだすことが
できます。

file.c を取出すとすると、まず、今のバックアップを取ってから、
mv file.c file.c.bak

・バージョン1.3の場合
cvs update -p -r 1.3 file.c > file.c
・2日前のソースの場合
cvs update -p -D "2 days ago" file.c > file.c
・1999/07/08のソースの場合
cvs update -p -D "07/08/99" file.c > file.c

● 変更履歴を見たい場合

cvs log ファイル名

結構長くなるかも知れないので、lessを使いましょう。

--------------------- その他 tips

● どのファイルが変更されているか見たい場合

cvs -n update

でローカルを変更せずに、変更されているファイルだけの一覧を
見ることができます。

● ヘルプ

cvs --help
cvs [コマンド名] -H

● 誰がいつどのファイルを変更したかを知りたい場合

cat /u/develop/mj001b/cvsroot/logs/mgs2.log
にmgs2の下でのcommit, add, removeのログがあります。

● .cvsrc

cvs update -d など、常にそのオプションをつけておきたいときは、
自分のホームディレクトリの.cvsrcというファイルに
----
update -d
----
などと書いておけば、そのコマンドの使用時に、勝手にそのオプションを
つけてくれます。
また、そのファイルに
----
cvs -q
----
を書いておくと、アップデート時などにサブディレクトリの表示を行わない
ようになるので、見やすいかもしれません。

私のお勧めは
----
cvs -q
update -dP
----
です。

● ディレクトリを消した場合

普通、update -dを実行すると、空のディレクトリが残ってしまいます。
消したい場合は、

cvs update -P

で、updateをかけることで、消すことができます。
ただし、消した後 -Pなしでupdate -d すると復活します。
どうしても消したい場合は、.cvsrcに
update -P ( または -dP )
と書いておいてください。

● 枝について

たとえば、2人で同じ作業をしていて、CVSを使ってファイルをやり取りしたいけど、
実験中なので、そのほかの人達のupdateには反映させたくないというとき、
「枝」という概念を使用します。
現在普通に格納されている場所を「幹」とたとえます。

判りやすくするために、ここでは是角君と園山君がソースを共有したいとします。

まず、是角君が「枝」を作ります。
「枝」の名前は、2度と同じ名前にできないので、日付情報を入れてください。
ここでは、TEST_991023 という名前にします。

１）是角君は、mgs2/source で以下のコマンドを打ち込みます。

cvs tag -b TEST_991023

ファイルがすべて、T という状態で表示されます。
-b はその名前の枝を作るというオプションです。
これで、「この時点でCVSにアップされている最新のソース」から、
TEST_991023 という名前の「枝」を作成しました。
さらに、

cvs update -r TEST_991023

をおこなって、ソース全体をTEST_991023 という「枝」であると宣言します。

以降、cvs commit を行うと、ソース全体に対する修正は、
みんなと同じところではなく、TEST_991023から分岐したところに保管されます。
逆に言うと、それ以降の「幹」に対する、たとえば高部君の修正は、
この場所でのcvs updateでは反映されません。

２）園山君は、是角君の「枝」に参加することにします。

是角君から「枝」の名前を聞いてきて、以下のコマンドを実行します。

cvs update -r TEST_991023

これで、是角君と同じ「枝」に参加しました。
以降、cvs update, cvs commit は、是角君とのみ共有します。
ほかの人も、同じコマンドで参加することができます。

３）作業が終了し、全体と合流します。

まず、現在のソースを cvs commit で格納してください。(必須)

次に、「枝」の名前を思い出します。(この場合 TEST_991023)
もし、忘れてしまった場合は、適当なファイル ( たとえば enemy.c )
をつかって、

cvs status enemy.c

を実行します。

すると、

===================================================================
File: enemy.c       	Status: Locally Modified

   Working revision:	1.5	Thu Oct  7 11:20:30 1999
   Repository revision:	1.5	/u/develop/mj001b/cvsroot/tools/gclconv/enemy.c,v
   Sticky Tag:		TEST_991023 (branch: 1.5.4)
   Sticky Date:		(none)
   Sticky Options:	(none)

なんかこんなのが表示されます。
このなかの、Sticky Tagというのが、現在作業中のタグ名です。
これを使って、以下の３つのコマンドを実行します。

cvs update -d -A
cvs update -d -j TEST_991023
cvs commit

最初の、-A で、とりあえずみんなの「幹」に合流します。
「幹」の最新バージョンがダウンロードされます。この時点では、
「枝」の作業は消えてしまいます。もし、「枝」の作業がうまく行かず、
破棄したいときは、このままほっておけばいいわけです。

次の -j で、「枝」で作業してきた変更点を「幹」にマージします。
もし、コンフリクトが起きた場合は修正してください。

最後の cvs commit で、「幹」に格納します。

園山君も同様の手順で「幹」に復帰します。この作業をしない限り、
ずっと、「枝」での作業が続きます。

「枝」にいる状態では、「幹」の変更は全く反映されないことを
絶対に忘れないでください。
間違っても、合流するのを忘れないように。

なお、これらの作業は、ディレクトリやファイル単位でも行うことが
できます。「枝」はsonoyamaとkorekadoの下のみということも可能です。
（その場合は、その外のディレクトリはちゃんと「幹」のupdateが反映される）
ただし、この時は、是角君も園山君もディレクトリ毎に同じタグ名で
cvs update -r TAG
を実行する必要があります。
ただし、誰もcvs tab -b TAG でタグ名をつけていないディレクトリやファイルで
その操作を行った場合、ローカルからファイルが消えてしまいますので、注意してください。
（普通に cvs updateすれば復活します)

タグに関しては消すこともできますが、誰かがそのタグを使った「枝」で作業していた場合は
取り返しのつかないことになりかねませんので、一応、管理者のみがその権限を持つこととします。
