***************************
TortoiseHg クイックスタート
***************************

.. module:: tour
	:synopsis: Windows で TortoiseHg を使うためのチュートリアル

TortoiseHg と Mercurial にようこそ！
TortoiseHg は Mercurial 分散バージョン管理システム (DVCS) に Windows
エクスプローラのシェル拡張と使い勝手の良い GUI
フロントエンドを提供するアプリケーションです。すべての TortoiseHg
の機能はエクスプローラの右クリックメニューからだけでなく、付属の
:command:`hgtk` コマンドラインツールからも起動することができます。
Mercurial のコマンドも通常の :command:`hg` コマンドで利用できます。

TortoiseHg の設定
=================

まず最初にやることは TortoiseHg にあなた自身について教えることです。
TortoiseHg のユーザ設定ダイアログから設定できます。
プロジェクトディレクトリを右クリックして
:menuselection:`TortoiseHg --> ユーザ設定` を選択します。

.. figure:: figures/cmenu-global-settings.png
	:alt: デスクトップの右クリックメニュー

	デスクトップからユーザ設定ダイアログを開く

このメニューは TortoiseHg 設定ダイアログを開いて、ホームディレクトリにある
あなたのユーザ設定を編集します。コマンドラインから使用しているのであれば
:command:`hgtk userconfig` でユーザ設定ダイアログを開くことができます。

.. figure:: figures/settings.png
	:alt: 設定ダイアログ

	TortoiseHg 設定ダイアログ

そして :guilabel:`コミット` ページに切り替えて、 :guilabel:`ユーザ名` の
テキストボックスに名前を入力してください。

.. note::
	ユーザ名の設定をし忘れた場合、TortoiseHg は必要に応じてコミット時にユーザ名の
	入力を促します。

.. note::
	ユーザ名として設定する名前の形式に厳密なルールがあるわけではありませんが、
	多くの人が次のような形式を採用しています：

		氏名 <電子メールアドレス>

	例えば：

		Taro Yamada <taroyamada@example.net>

	電子メールアドレスはチェンジログビューアで履歴を表示する際には削除され、
	Mercurial 内蔵のウェブサーバを利用した場合はスパム対策のためメールアドレス
	の一部のみ表示されます。

次に :guilabel:`TortoiseHg` ページに切り替え、 :guilabel:`3-way マージツール`
の設定項目を選択します。このドロップダウンリストにはシステム内で検出された
すべての利用可能なマージツール (kdiff3 は Windows 向けの TortoiseHg
インストーラ同梱) と Mercurial 組み込みのマージ処理が含まれています。
好みのマージツールを選んでください。

選択したマージツールを GUI 差分表示ツールとしても利用したい場合は
:guilabel:`GUI 差分表示ツール` の設定項目を :guilabel:`未設定`
のままにしておいてください。マージツールとは異なる他の差分ツールを
利用したい場合はドロップダウンリストから好きなツールを選択してください。

ドロップダウンリストに選択肢がない場合は mergetools.rc がサポートしている
差分/マージツールをインストールするか、未サポートのツールであれば
:file:`Mercurial.ini` ファイル、または :file:`.hgrc`
ファイルに設定を記述する必要があります。

.. note::
	TortoiseHg をソースコードからインストールしている場合、
	contrib/mergetools.rc ファイルを HGRC パスに含める必要があります。
	例えば %include を使うことで ~/.hgrc ファイルから読み込みます。

他のユーザ設定も自由に設定してください。必要であればユーザ設定における
設定値はリポジトリごとの設定で上書きすることができます。

:guilabel:`OK` ボタンを押して変更を保存して完了です。

.. note::
	ほとんどの TortoiseHg ダイアログは設定を反映するために
	再起動する必要があります (システムの再起動ではない)。


リポジトリの初期化
==================

右クリックメニューの :guilabel:`ここにリポジトリを作成` を選択するか、
コマンドラインから :command:`hgtk init` を実行して最初のリポジトリを
ローカルディスク上に作成してみましょう。
この作業はプロジェクトディレクトリのルートで一度だけ行ってください。

.. figure:: figures/init.png
	:alt: 初期化ダイアログ

	リポジトリ初期化ダイアログ

特に理由がなければ
:guilabel:`特殊ファイルを追加する (.hgignoreなど)` にチェックを入れ、
:guilabel:`Mercurial 1.0 互換のリポジトリを作成` のチェックは外した状態で
リポジトリを作成すると良いでしょう。

:guilabel:`作成` ボタンを押すと Mercurial はプロジェクトディレクトリに
:file:`.hg` という名前のディレクトリを作成します。
ここには Mercurial のすべてのバージョン情報が保管され、一般に *リポジトリ*
と呼ばれています。一方、実際のソースファイルなどが含まれているディレクトリを
*作業ディレクトリ* と呼びます。コマンドを実行するときこの :file:`.hg`
ディレクトリを指定する必要はなく、作業ディレクトリのルートを指定するだけで
大丈夫です。これは Mercurial がどのように動いているのかを理解するために
覚えておくと良いかもしれません。

.. warning::
	:file:`.hg` を直接編集することはリポジトリの破損を引き起こすため危険です。
	ただし :file:`.hg/hgrc` のみ例外的に編集が認められています。


ファイルの追加
==============

いよいよ Mercurial にどのファイルを管理下に置き、どのファイルを無視すべき
なのかを指定します。これにはいくつものやり方があります：

1.	エクスプローラで追加したいファイルを右クリックしてメニューを開いて
	:menuselection:`TortoiseHg --> 追加...` を選択します。
	するとファイル追加を確認するダイアログが表示されるので、
	それでよければ :guilabel:`追加` ボタンを押してください。

2.	もしくは、ステータスツール (:menuselection:`TortoiseHg --> 変更点の確認`
	またはコマンドラインから :command:`hgtk status`) を開いて追加したいファイルの
	チェックボックスにチェックを入れ、 :guilabel:`追加` ボタンを押します。
	ステータスツールでは、不明なファイルの右クリックメニュー (:guilabel:`無視`)
	から無視フィルタツールを開くこともできます。

3.	または、ファイルの追加を独立した作業として行わず、コミットツールで済ます
	ことも可能です。コミットツールはステータスツールと非常に似ており、
	ステータスツールで可能な操作はすべてコミットツールでも行えます。
	このツールではファイルにチェックを入れて :guilabel:`コミット` ボタンを押す
	ことで、まだ Mercurial 管理下に置かれていないファイルの追加およびコミット
	することができます。

4.	無視ファイルを指定するために無視フィルタダイアログを開きます：
	右クリックメニューから :menuselection:`TortoiseHg --> 無視フィルタの編集`
	を選択するか、コマンドラインから :command:`hgtk hgignore` を実行します。
	一覧からファイルを選択するか直接 *Glob* または *正規表現* を入力して
	:guilabel:`追加` ボタンを押してください。ここでの変更は即座に反映されます。

.. note::
	:file:`.hgignore` ファイルは作業ディレクトリのルートに含まれており、
	通常は Mercurial のバージョン管理下に置かれています。

.. note::
	作業ディレクトリにたくさんの *不明* ファイルを放置したままにしないというのは、
	バージョン管理下に置くべきファイルの追加し忘れを未然に防ぐという意味で
	よい習慣と言えます。そのため :file:`.hgignore` ファイルを極力最新の状態に
	保つよう努めてください。


コミット
========

プロジェクトディレクトリを右クリックして :guilabel:`Hg コミット ...` を
選択するか、コマンドラインから :command:`hgtk commit` を実行して変更点を
ローカルリポジトリにコミットします。コミットメッセージを記述し、
コミットしたいファイルにチェックを入れてから :guilabel:`コミット` ボタンを
押します。コミット後にコミットメッセージの内容やコミットしたファイルの間違いに
気付いた場合は :guilabel:`取り消し` ボタンで直前のコミットを取り消すことが
できます。入力したコミットメッセージはメッセージ履歴のドロップダウンリストに
残るため、同じメッセージを再度入力し直す必要はありません。

.. note::
	コミットツールを閉じてしまうと直前のコミットを :guilabel:`取り消し` ボタンで
	取り消すことは出来なくなります。

.. figure:: figures/commit.png
	:alt: コミットダイアログ

	コミットツール


リポジトリの共有
================

これであなたの成果を共有するための準備が整いました。あとはこのリポジトリを
他のメンバからも参照できる共用スペースにコピーするだけでOKです。
Mercurial ではこのコピー操作を *リポジトリのクローン (cloning your repository)*
と呼んでいます。リポジトリを共有ドライブにするには右クリックメニューから
:menuselection:`TortoiseHg --> リポジトリのクローン` を選択するか、
コマンドラインから :command:`hgtk clone` を実行します。

.. figure:: figures/share.png
	:alt: クローンダイアログ

	クローンダイアログ

チームでコードを共有するための *中央リポジトリ* に、あなたが持っている
ローカルのリポジトリのような作業ディレクトリは必要ありません。
つまり、純粋にリポジトリだけあれば十分と言えます。このような場合、
:guilabel:`クローン後に作業ディレクトリを HEAD に更新しない`
にチェックを入れることで Mercurial は中央リポジトリのクローンから
作業コピーをチェックアウトしません。その結果、プロジェクトのリビジョン履歴の
すべてが格納されている :file:`.hg` のみとなります。

他のチームメンバはこの中央リポジトリからクローンすることで作業できます。


共有リポジトリからの取得
========================

今あなたがあるチームと共同作業を始めたいとします。彼らは
*X からリポジトリを取得してくれ* と言っていますが、どういう意味なのでしょうか？
これは、X という場所に置かれているリポジトリをローカルにクローンしてくれ、
という意味になります。Mercurial ではこれをクローン (cloning) と呼び、
TortoiseHg には専用のダイアログが用意されています。
クローンを作成したいディレクトリで右クリックメニューを開いて
:menuselection:`TortoiseHg --> リポジトリのクローン` を選択するか
コマンドラインから :command:`hgtk clone` を実行してください。

.. figure:: figures/clone.png
	:alt: クローンダイアログ

	クローンダイアログ

今回はこれからクローンするリポジトリの作業ディレクトリでプロジェクトの作業を
するため、 :guilabel:`クローン後に作業ディレクトリを HEAD に更新しない`
のチェックは外してください。これで Mercurial は作業ディレクトリを
*tip* リビジョンに更新します。


リポジトリを使ったワークフロー
==============================

作業ディレクトリでいくつかの変更を加えたとします。エクスプローラでいくつかの
変更が保留中であることをアイコンオーバーレイの変化から簡単に確認できます。
より詳細な変更点の確認やそれらのコミットはエクスプローラから行うことができます。
手っ取り早い方法はコミットツールを使うことです：

.. figure:: figures/overlayicons.png
	:alt: アイコンオーバーレイ

	Windows Vista でのアイコンオーバーレイ表示

コミットツールは変更の差分を表示してくれます。もしくは普段使用している GUI の
差分表示ツール (kdiff など) を使用することもできます。 Mercurial のリポジトリは
分散型になっているため、変更点を共有リポジトリと同期 (変更点の共有) するかどうか
決める前にローカルリポジトリにコミットできます。

変更を共有リポジトリに公開する準備が整ったら、

1.	ローカルのリポジトリに変更点をコミットします (前述)。
2.	共有リポジトリから変更をローカルリポジトリにプル (pull) します：
	右クリックメニューから :menuselection:`TortoiseHg --> ログの表示` または
	コマンドラインから :command:`hgtk log` を実行し、共有リポジトリの場所を
	同期バーで選択して、ツールバーの :guilabel:`プル` ボタンを押します。
3.	いくつかのチェンジセットがプルされた場合、それらの変更とローカルでの変更を
	マージして、マージ結果をローカルリポジトリにコミットしてください。
	チェンジログビューアから (:menuselection:`TortoiseHg --> ログの表示`
	または :command:`hgtk log`) マージしたいリビジョンの右クリックメニューを
	開いて :guilabel:`マージ` を選択します。マージダイアログが表示されるので、
	:guilabel:`マージ` ボタンを押してマージを実行し、 :guilabel:`コミット`
	してください。
4.	マージが正しく行われたかどうかテストなどで検証してください。
5.	変更を共有リポジトリにプッシュ (push) するために、
	:menuselection:`TortoiseHg --> ログの表示` または :command:`hgtk log`
	で同期ダイアログを開き、共有リポジトリの場所を選択してから
	:guilabel:`プッシュ` ボタンを押します。

文章にすると複雑に見えますが、実際にはコミットしてチェンジログビューアのボタンを
押すだけです。

.. note::
	マージ作業に失敗したとしても安全に最初からマージ作業を始めることが可能です。

Mercurial は共同作業を簡単に、素早く、効率的にします。
詳しくは Mercurial の `wiki <https://www.mercurial-scm.org/wiki/>`_
をご覧ください。

.. vim: noet ts=4
