=encoding utf8 =for comment Consistent formatting of this file is achieved with: perl ./Porting/podtidy pod/perlgit.pod =head1 NAME =begin original perlgit - Detailed information about git and the Perl repository =end original perlgit - git と Perl リポジトリに関する詳細情報 =head1 DESCRIPTION =begin original This document provides details on using git to develop Perl. If you are just interested in working on a quick patch, see L first. This document is intended for people who are regular contributors to Perl, including those with write access to the git repository. =end original この文書は、Perl を開発するために git を使う詳細を提供します。 単に簡単なパッチに対して作業することに興味があるなら、 まず L を参照してください。 この文書は、git リポジトリへの書き込みアクセスを持つ人々を含む、 Perl の定期的な貢献者である人々のためを意図しています。 =head1 CLONING THE REPOSITORY (リポジトリをクローンする) =begin original All of Perl's source code is kept centrally in a Git repository at I. =end original Perlのソースコードはすべて、I の Git リポジトリに 集中管理されています。 =begin original You can make a read-only clone of the repository by running: =end original これを実行することでリポジトリの読み込み専用のクローンを作ることができます: % git clone git://perl5.git.perl.org/perl.git perl =begin original This uses the git protocol (port 9418). =end original これは git プロトコル (ポート 9418) を使います。 =begin original If you cannot use the git protocol for firewall reasons, you can also clone via http, though this is much slower: =end original ファイアウォールの関係で git プロトコルが使えない場合、 http 経由でもクローンできますが、はるかに遅いです: % git clone http://perl5.git.perl.org/perl.git perl =head1 WORKING WITH THE REPOSITORY (リポジトリでの作業) =begin original Once you have changed into the repository directory, you can inspect it. After a clone the repository will contain a single local branch, which will be the current branch as well, as indicated by the asterisk. =end original リポジトリディレクトリに変更を加えたら、そのディレクトリを検査できます。 クローン作成後、リポジトリには単一のローカルブランチが含まれます。 このローカルブランチは、アスタリスクで示されているように、 現在のブランチにもなります。 % git branch * blead =begin original Using the -a switch to C will also show the remote tracking branches in the repository: =end original C に -a スイッチを使用すると、リポジトリ内の リモート追跡ブランチも表示されます: % git branch -a * blead origin/HEAD origin/blead ... =begin original The branches that begin with "origin" correspond to the "git remote" that you cloned from (which is named "origin"). Each branch on the remote will be exactly tracked by these branches. You should NEVER do work on these remote tracking branches. You only ever do work in a local branch. Local branches can be configured to automerge (on pull) from a designated remote tracking branch. This is the case with the default branch C which will be configured to merge from the remote tracking branch C. =end original "origin" で始まるブランチは、クローン元の "git remote" ("origin" という名前) に対応します。 リモートの各ブランチは、これらのブランチによって正確に追跡されます。 これらのリモート追跡ブランチでは絶対に作業しないでください。 ローカルブランチでのみ作業します。 ローカルブランチは、指定されたリモート追跡ブランチから (プル時に)自動マージするように構成できます。 これは、リモート追跡ブランチ C からマージするように 構成されているデフォルトブランチ C の場合です。 =begin original You can see recent commits: =end original 最近のコミットを見られます: % git log =begin original And pull new changes from the repository, and update your local repository (must be clean first) =end original リポジトリから新しい変更をプルし、ローカルリポジトリを更新します (最初にクリーンにする必要があります)。 % git pull =begin original Assuming we are on the branch C immediately after a pull, this command would be more or less equivalent to: =end original プルの直後にブランチ C にいると仮定すると、このコマンドは 以下とほぼ等価になります: % git fetch % git merge origin/blead =begin original In fact if you want to update your local repository without touching your working directory you do: =end original 実際、作業ディレクトリにアクセスせずにローカルリポジトリを更新したい場合は、 次のようにします: % git fetch =begin original And if you want to update your remote-tracking branches for all defined remotes simultaneously you can do =end original また、定義されたすべてのリモートに対してリモート追跡ブランチを 同時に更新したい場合は、以下のように行うことができます: % git remote update =begin original Neither of these last two commands will update your working directory, however both will update the remote-tracking branches in your repository. =end original 最後の二つのコマンドはどちらも作業ディレクトリを更新しませんが、どちらも リポジトリ内のリモート追跡ブランチを更新します。 =begin original To make a local branch of a remote branch: =end original リモートブランチのローカルブランチを作るには: % git checkout -b maint-5.10 origin/maint-5.10 =begin original To switch back to blead: =end original blead に戻るには: % git checkout blead =head2 Finding out your status (現在の状態を確認する) =begin original The most common git command you will use will probably be =end original おそらくもっともよく使う git コマンドは: % git status =begin original This command will produce as output a description of the current state of the repository, including modified files and unignored untracked files, and in addition it will show things like what files have been staged for the next commit, and usually some useful information about how to change things. For instance the following: =end original このコマンドは、変更されたファイルや無視されていない 追跡されていないファイルなど、リポジトリの現在の状態の説明を 出力として生成します。 さらに、次のコミットのためにステージングされたファイルや、 通常は変更方法に関する有用な情報を表示します。 たとえば、次のようになります: $ git status # On branch blead # Your branch is ahead of 'origin/blead' by 1 commit. # # Changes to be committed: # (use "git reset HEAD ..." to unstage) # # modified: pod/perlgit.pod # # Changed but not updated: # (use "git add ..." to update what will be committed) # # modified: pod/perlgit.pod # # Untracked files: # (use "git add ..." to include in what will be committed) # # deliberate.untracked =begin original This shows that there were changes to this document staged for commit, and that there were further changes in the working directory not yet staged. It also shows that there was an untracked file in the working directory, and as you can see shows how to change all of this. It also shows that there is one commit on the working branch C which has not been pushed to the C remote yet. B: that this output is also what you see as a template if you do not provide a message to C. =end original これは、コミットのためにステージングされたこの文書に変更があったことと、 まだステージングされていないワーキングディレクトリに さらに変更があったことを示しています。 また、ワーキングディレクトリに追跡されていないファイルが あったことも示しています; また、これらすべてを変更する方法を示しています。 また、C リモートにまだプッシュされていないワーキングブランチ C に一つのコミットがあることも示しています。 B<注>: この出力は、C にメッセージを提供しない場合に テンプレートとして表示されるものでもあります。 =head2 Patch workflow (パッチのワークフロー) =begin original First, please read L for details on hacking the Perl core. That document covers many details on how to create a good patch. =end original まず、Perl コアをハックするための詳細については L を読んでください。 この文書はよいパッチの作り方に関する多くの詳細に対応しています。 =begin original If you already have a Perl repository, you should ensure that you're on the I branch, and your repository is up to date: =end original すでに Perl リポジトリを持っている場合は、 I ブランチにいて、リポジトリが最新であることを確認する必要があります: % git checkout blead % git pull =begin original It's preferable to patch against the latest blead version, since this is where new development occurs for all changes other than critical bug fixes. Critical bug fix patches should be made against the relevant maint branches, or should be submitted with a note indicating all the branches where the fix should be applied. =end original 最新の blead バージョンに対してパッチを適用することをお勧めします。 これは、重大なバグ修正以外のすべての変更に対して新たな開発が行われる 場所であるためです。 重大なバグ修正パッチは、関連するメインブランチに対して作成するか、 修正が適用されるすべてのブランチを示すメモとともに提出する必要があります。 =begin original Now that we have everything up to date, we need to create a temporary new branch for these changes and switch into it: =end original すべてが最新の状態になったので、これらの変更に対して一時的な 新しいブランチを作成し、そのブランチに切り替える必要があります: % git checkout -b orange =begin original which is the short form of =end original これは以下のものの短縮形です % git branch orange % git checkout orange =begin original Creating a topic branch makes it easier for the maintainers to rebase or merge back into the master blead for a more linear history. If you don't work on a topic branch the maintainer has to manually cherry pick your changes onto blead before they can be applied. =end original トピックブランチを作成することで、メンテナはよりリニアな履歴のために master blead にリベースまたはマージバックすることが簡単になります。 トピックブランチで作業しない場合、 メンテナは変更を適用する前に手動で blead にチェリーピックする 必要があります。 =begin original That'll get you scolded on perl5-porters, so don't do that. Be Awesome. =end original perl5-porters で叱られることになるので、そんなことはしないでください。 うまくやりましょう。 =begin original Then make your changes. For example, if Leon Brocard changes his name to Orange Brocard, we should change his name in the AUTHORS file: =end original 次に、変更を加えます。 たとえば、Leon Brocard が名前を Orange Brocard に変更した場合、 AUTHORS ファイル内の名前を変更する必要があります: % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS =begin original You can see what files are changed: =end original どのファイルを変更したかを見られます: % git status # On branch orange # Changes to be committed: # (use "git reset HEAD ..." to unstage) # # modified: AUTHORS # =begin original And you can see the changes: =end original そして変更が見られます: % git diff diff --git a/AUTHORS b/AUTHORS index 293dd70..722c93e 100644 --- a/AUTHORS +++ b/AUTHORS @@ -541,7 +541,7 @@ Lars Hecking Laszlo Molnar Leif Huhn Len Johnson -Leon Brocard +Orange Brocard Les Peters Lesley Binks Lincoln D. Stein =begin original Now commit your change locally: =end original ここで変更をローカルにコミットします: % git commit -a -m 'Rename Leon Brocard to Orange Brocard' Created commit 6196c1d: Rename Leon Brocard to Orange Brocard 1 files changed, 1 insertions(+), 1 deletions(-) =begin original The C<-a> option is used to include all files that git tracks that you have changed. If at this time, you only want to commit some of the files you have worked on, you can omit the C<-a> and use the command C>> before doing the commit. C> allows you to even just commit portions of files instead of all the changes in them. =end original C<-a> オプションは、git が追跡しているファイルの中であなたが変更した 全てのファイルを含むために使われます。 もしこの時点で、作業したファイルの一部だけをコミットしたい場合は、 C<-a> を省略して、コミットを行う前にコマンド C>> を使ってください。 C> は、ファイル中の全ての変更ではなく、 ファイルの一部をコミットできるようにします。 =begin original The C<-m> option is used to specify the commit message. If you omit it, git will open a text editor for you to compose the message interactively. This is useful when the changes are more complex than the sample given here, and, depending on the editor, to know that the first line of the commit message doesn't exceed the 50 character legal maximum. =end original C<-m> オプションはコミットメッセージを指定するために使われます。 これを省略すると、git はメッセージを対話的に作成するために テキストエディタを開きます。 これは、変更がここで指定するサンプルよりも複雑な場合、そして エディタによっては、コミットメッセージの先頭行が上限の 50 文字を超えないことを知るために有用です。 =begin original Once you've finished writing your commit message and exited your editor, git will write your change to disk and tell you something like this: =end original コミットメッセージを書き終えてエディタを終了すると、 git は変更をディスクに書き込み、以下のようなメッセージを出力します: Created commit daf8e63: explain git status and stuff about remotes 1 files changed, 83 insertions(+), 3 deletions(-) =begin original If you re-run C, you should see something like this: =end original C を再実行すると、次のようなものが表示されます: % git status # On branch blead # Your branch is ahead of 'origin/blead' by 2 commits. # # Untracked files: # (use "git add ..." to include in what will be committed) # # deliberate.untracked nothing added to commit but untracked files present (use "git add" to track) =begin original When in doubt, before you do anything else, check your status and read it carefully, many questions are answered directly by the git status output. =end original 疑わしいときには、他のことをする前に、ステータスをチェックして 注意深く読んでください; 多くの疑問は git status の出力で直接応えられています。 =begin original You can examine your last commit with: =end original 最後のコミットを以下のようにして検査できます: % git show HEAD =begin original and if you are not happy with either the description or the patch itself you can fix it up by editing the files once more and then issue: =end original 説明またはパッチ自体に満足できない場合は、ファイルをもう一度編集してから 次のコマンドを発行することで修正できます: % git commit -a --amend =begin original Now you should create a patch file for all your local changes: =end original ここで全てのローカルな変更のためのパッチファイルを作るべきです: % git format-patch -M origin.. 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch =begin original Or for a lot of changes, e.g. from a topic branch: =end original あるいは変更が多い場合、つまりトピックブランチからは: % git format-patch --stdout -M origin.. > topic-branch-changes.patch =begin original You should now send an email to L with a description of your changes, and include this patch file as an attachment. In addition to being tracked by RT, mail to perlbug will automatically be forwarded to perl5-porters (with manual moderation, so please be patient). You should only send patches to L directly if the patch is not ready to be applied, but intended for discussion. =end original L 宛に変更内容を記載した メールを送信し、このパッチファイルを添付ファイルとして送ってください。 RT で追跡することに加えて、 perlbug にメールすると、自動的に perl5-porters に (手動のモデレーションの後、従って気長に待ってください) 転送されます。 パッチは適用する準備ができていない状態だけれども議論したい場合は、 L だけに 直接メールを送るべきです。 =begin original See the next section for how to configure and use git to send these emails for you. =end original これらのメールを送信するために git を設定して使う方法については、 次の節を参照してください。 =begin original If you want to delete your temporary branch, you may do so with: =end original 一時的なブランチを削除したいなら、以下のようにできます: % git checkout blead % git branch -d orange error: The branch 'orange' is not an ancestor of your current HEAD. If you are sure you want to delete it, run 'git branch -D orange'. % git branch -D orange Deleted branch orange. =head2 Committing your changes (変更をコミットする) =begin original Assuming that you'd like to commit all the changes you've made as a single atomic unit, run this command: =end original 今行ったすべての変更を一つのアトミックユニットとしてコミットしたい場合は、 次のコマンドを実行します: % git commit -a =begin original (That C<-a> tells git to add every file you've changed to this commit. New files aren't automatically added to your commit when you use C If you want to add files or to commit some, but not all of your changes, have a look at the documentation for C.) =end original (C<-a> は git に対して、変更したすべてのファイルをこのコミットに 追加するように指示します。 C を使用しても、新しいファイルは自動的にコミットに追加されません。 ファイルを追加したい場合や、一部の変更をコミットしたい場合は、 C の文書を参照してください。 =begin original Git will start up your favorite text editor, so that you can craft a commit message for your change. See L for more information about what makes a good commit message. =end original Git は、あなたが変更内容のコミットメッセージを作成できるように、 お気に入りのテキストエディタを起動します。 適切なコミットメッセージを作成する方法に関するさらなる情報については、 L を参照してください。 =begin original Once you've finished writing your commit message and exited your editor, git will write your change to disk and tell you something like this: =end original コミットメッセージを書き終えてエディタを終了すると、 git は変更をディスクに書き込み、以下のようなメッセージを出力します: Created commit daf8e63: explain git status and stuff about remotes 1 files changed, 83 insertions(+), 3 deletions(-) =begin original If you re-run C, you should see something like this: =end original C を再実行すると、次のようなものが表示されます: % git status # On branch blead # Your branch is ahead of 'origin/blead' by 2 commits. # # Untracked files: # (use "git add ..." to include in what will be committed) # # deliberate.untracked nothing added to commit but untracked files present (use "git add" to track) =begin original When in doubt, before you do anything else, check your status and read it carefully, many questions are answered directly by the git status output. =end original 何か疑問がある場合には、何かをする前に自分のステータスをチェックして 注意深く読んでください; 多くの疑問に対しては、git status 出力が直接答えてくれます。 =head2 Sending patch emails (パッチをメールする) =begin original After you've generated your patch you should sent it to perlbug@perl.org (as discussed L with a normal mail client as an attachment, along with a description of the patch. =end original パッチを作ったら、 (L<前の節|/"Patch workflow"> で議論したように) それを添付ファイルにして、パッチの説明と共に、 通常のメールクライアントで perlbug@perl.org に送ってください。 =begin original You B use git-send-email(1) to send patches generated with git-format-patch(1). The RT ticketing system living behind perlbug@perl.org does not respect the inline contents of E-Mails, sending an inline patch to RT guarantees that your patch will be destroyed. =end original git-format-patch(1) で生成したパッチを送るのに git-send-email(1) を 使っては B<いけません>。 perlbug@perl.org の後ろで動いている RT チケットシステムは、 電子メールのインラインコンテンツを認識しないので、 RT にインラインでパッチを送ると、パッチは破壊されます。 =begin original Someone may download your patch from RT, which will result in the subject (the first line of the commit message) being omitted. See RT #74192 and commit a4583001 for an example. Alternatively someone may apply your patch from RT after it arrived in their mailbox, by which time RT will have modified the inline content of the message. See RT #74532 and commit f9bcfeac for a bad example of this failure mode. =end original 誰かが RT からパッチをダウンロードすると、題名 (コミットメッセージの 最初の行) は削除されます。 例えば RT #74192 とコミット a4583001 を参照してください。 あるいは、誰かがメールボックスに届いた RT からのパッチを 適用するかもしれません; この場合 RT はメッセージのインラインコンテンツを 変更しています。 この失敗に関する悪い例は RT #74532 とコミット f9bcfeac を参照してください。 =head2 A note on derived files (派生ファイルに関する注意) =begin original Be aware that many files in the distribution are derivative--avoid patching them, because git won't see the changes to them, and the build process will overwrite them. Patch the originals instead. Most utilities (like perldoc) are in this category, i.e. patch F rather than F. Similarly, don't create patches for files under $src_root/ext from their copies found in $install_root/lib. If you are unsure about the proper location of a file that may have gotten copied while building the source distribution, consult the C. =end original ディストリビューション内の多くのファイルは 派生的なものであることに注意してください -- それらのファイルにパッチを当てることは避けてください; なぜなら、git はそれらに対する変更を見ることができず、 ビルドプロセスがそれらを上書きするからです。 代わりにオリジナルにパッチを当ててください。 ほとんどのユーティリティ(perldoc など)はこのカテゴリにあります; すなわち、utils/perldoc ではなく F にパッチを当てます。 同様に、$install_root/lib にあるコピーから $src_root/ext 以下のファイルに パッチを作成しないでください。 ソースディストリビューションのビルド中にコピーされた可能性のあるファイルの 適切な場所がわからない場合は、C を調べてください。 =head2 Cleaning a working directory (作業ディレクトリを掃除する) =begin original The command C can with varying arguments be used as a replacement for C. =end original C コマンドはさまざまな引数で C の代わりに 使うことができます。 =begin original To reset your working directory to a pristine condition you can do: =end original 作業ディレクトリを初期状態にリセットするには、次のようにします: % git clean -dxf =begin original However, be aware this will delete ALL untracked content. You can use =end original ただし、これによりすべての追跡されていないコンテンツが削除されます。 次のようにすると: % git clean -Xf =begin original to remove all ignored untracked files, such as build and test byproduct, but leave any manually created files alone. =end original ビルドやテストの副産物など、すべての無視された 追跡されていないファイルを削除します。 ただし、手動で作成したファイルは残します。 =begin original If you only want to cancel some uncommitted edits, you can use C and give it a list of files to be reverted, or C to revert them all. =end original コミットされていない編集だけをキャンセルしたい場合は、 C を使用して元に戻すファイルのリストを与えるか、 C を使用してすべてを元に戻すことができます。 =begin original If you want to cancel one or several commits, you can use C. =end original 1つまたは複数のコミットをキャンセルしたい場合は、C を 使うことができます。 =head2 Bisecting (bisect) =begin original C provides a built-in way to determine which commit should be blamed for introducing a given bug. C performs a binary search of history to locate the first failing commit. It is fast, powerful and flexible, but requires some setup and to automate the process an auxiliary shell script is needed. =end original C は、指定されたバグが導入されたのがどのコミットに責任があるかを 決定する組み込みの手段を提供しています。 C は失敗する最初のコミットを特定するために 履歴の二分検索を行います。 これは高速で強力で柔軟性がありますが、多少の準備が必要で、 処理を自動化するには外部シェルスクリプトが必要です。 =begin original The core provides a wrapper program, F, which attempts to simplify as much as possible, making bisecting as simple as running a Perl one-liner. For example, if you want to know when this became an error: =end original コアはラッパプログラムである F を提供しています; これはできるだけ作業を単純化して、 Perl のワンライナーを実行するだけで bisect ができるようにします。 例えば、次のものがいつエラーになったかを知りたい場合: perl -e 'my $a := 2' =begin original you simply run this: =end original 単純にこれを実行します: .../Porting/bisect.pl -e 'my $a := 2;' =begin original Using C, with one command (and no other files) it's easy to find out =end original C を (他のファイルなしで) 一つのコマンドで使うことで、 次のものを簡単に見つけられます: =over 4 =item * =begin original Which commit caused this example code to break? =end original どのコミットがこの例のコードを壊しているか =item * =begin original Which commit caused this example code to start working? =end original どのコミットからこの例のコードが動作し始めているか =item * =begin original Which commit added the first file to match this regex? =end original どのコミットが最初にこの正規表現にマッチングするファイルを追加したか =item * =begin original Which commit removed the last file to match this regex? =end original どのコミットが最後にこの正規表現にマッチングするファイルを削除したか =back =begin original usually without needing to know which versions of perl to use as start and end revisions, as F automatically searches to find the earliest stable version for which the test case passes. Run C for the full documentation, including how to set the C and build time options. =end original 通常はどのバージョンの perl を使うかの始点と終点のリビジョンを 知っている必要はありません; F は自動的に、テストケースが通過する最初の安定版バージョンを 探します。 C とビルド時オプションを含む完全な文書を見るには C を実行してください。 =begin original If you require more flexibility than F has to offer, you'll need to run C yourself. It's most useful to use C to automate the building and testing of perl revisions. For this you'll need a shell script for C to call to test a particular revision. An example script is F, which you should copy B of the repository, as the bisect process will reset the state to a clean checkout as it runs. The instructions below assume that you copied it as F<~/run> and then edited it as appropriate. =end original F が提供しているものよりもさらに柔軟性が必要な場合、 C を自分自身で実行する必要があります。 perl リビジョンのビルドとテストを自動化するために C を使うのが最も便利です。 このために、特定のリビジョンをテストするために呼び出すための C のためのシェルスクリプトが必要です。 例のスクリプトは F で、 これはリポジトリの B<外側> にコピーするべきです; bisect 処理は、実行されるとクリーンなチェックアウトのために 状態をリセットするからです。 後述の説明は、スクリプトを F<~/run> としてコピーして、それを 適切に編集することを仮定しています。 =begin original You first enter in bisect mode with: =end original まず bisect モードに入ります: % git bisect start =begin original For example, if the bug is present on C but wasn't in 5.10.0, C will learn about this when you enter: =end original 例えば、バグが C にあっても 5.10.0 にはなかった場合、C は 以下のように入力することでこれを学習します: % git bisect bad % git bisect good perl-5.10.0 Bisecting: 853 revisions left to test after this =begin original This results in checking out the median commit between C and C. You can then run the bisecting process with: =end original この結果、C と C の中間のコミットが チェックアウトされます。 次のようにして bisect 処理を実行します: % git bisect run ~/run =begin original When the first bad commit is isolated, C will tell you so: =end original 最初の不正なコミットが分離されると、C は次のように言います: ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 Author: Dave Mitchell Date: Sat Feb 9 14:56:23 2008 +0000 [perl #49472] Attributes + Unknown Error ... bisect run success =begin original You can peek into the bisecting process with C and C. C will get you out of bisect mode. =end original C と C で bisect 処理を 覗き見ることができます。 Cは bisect モードを解除します。 =begin original Please note that the first C state must be an ancestor of the first C state. If you want to search for the commit that I some bug, you have to negate your test case (i.e. exit with C<1> if OK and C<0> if not) and still mark the lower bound as C and the upper as C. The "first bad commit" has then to be understood as the "first commit where the bug is solved". =end original 最初の C 状態は、最初の C 状態の祖先である必要があることに 注意してください。 何らかのバグを I<解決した> コミットを検索したい場合は、テストケースを 反転させ、 (つまり、OK なら C<1> で終了し、そうでないなら C<0> で終了する)、 下限を C、上限を C とマークする必要があります。 「最初の不正なコミット」は、「バグが解決された最初のコミット」と 解釈する必要があります。 =begin original C has much more information on how you can tweak your binary searches. =end original C には、二分探索を微調整する方法に関する情報が豊富に 用意されています。 =head2 Topic branches and rewriting history (トピックブランチと履歴の書き換え) =begin original Individual committers should create topic branches under B/B. Other committers should check with a topic branch's creator before making any change to it. =end original 個々のコミッターは、B/B の下にトピックブランチを作成する必要があります。 他のコミッターは、トピックブランチに変更を加える前に、その作成者に 確認する必要があります。 =begin original The simplest way to create a remote topic branch that works on all versions of git is to push the current head as a new branch on the remote, then check it out locally: =end original すべてのバージョンの git で動作する、リモートトピックブランチを作成する 最も簡単な方法は、現在の head をリモートの新しいブランチとしてプッシュし、 ローカルでチェックアウトすることです。 $ branch="$yourname/$some_descriptive_name" $ git push origin HEAD:$branch $ git checkout -b $branch origin/$branch =begin original Users of git 1.7 or newer can do it in a more obvious manner: =end original git 1.7 以降のユーザは、もっと明らかな方法を使うことが出来ます: $ branch="$yourname/$some_descriptive_name" $ git checkout -b $branch $ git push origin -u $branch =begin original If you are not the creator of B/B, you might sometimes find that the original author has edited the branch's history. There are lots of good reasons for this. Sometimes, an author might simply be rebasing the branch onto a newer source point. Sometimes, an author might have found an error in an early commit which they wanted to fix before merging the branch to blead. =end original B/B の作成者でない場合、元の作成者が ブランチの履歴を編集したことに気付くことがあります。 これには多くの正当な理由があります。 場合によっては、単にブランチを新しいソースポイントに基づいて 作り直すことになることもあります。 場合によっては、ブランチを blead にマージする前に、 初期のコミットで修正したいエラーを見つけたこともあります。 =begin original Currently the master repository is configured to forbid non-fast-forward merges. This means that the branches within can not be rebased and pushed as a single step. =end original 現在、マスターリポジトリは、非 fast-forward のマージを禁止するように 構成されています。 これは、中のブランチはリベースとプッシュを単一ステップとしては できないことを意味します。 =begin original The only way you will ever be allowed to rebase or modify the history of a pushed branch is to delete it and push it as a new branch under the same name. Please think carefully about doing this. It may be better to sequentially rename your branches so that it is easier for others working with you to cherry-pick their local changes onto the new version. (XXX: needs explanation). =end original プッシュされたブランチの履歴を再取得または変更する唯一の方法は、 そのブランチを削除し、同じ名前で新しいブランチとしてプッシュすることです。 これを行うことについては慎重に検討してください。 他のユーザーが新しいバージョンにローカルの変更を簡単に チェリーピックできるように、 ブランチの名前を順番に変更した方がよい場合があります(XXX:説明が必要)。 =begin original If you want to rebase a personal topic branch, you will have to delete your existing topic branch and push as a new version of it. You can do this via the following formula (see the explanation about C's in the git push documentation for details) after you have rebased your branch: =end original 個人的なトピックブランチをリベースしたい場合は、 既存のトピックブランチを削除し、新しいバージョンとして プッシュする必要があります。 これは、ブランチをリベースした後、次の公式 (詳細は git push 文書の C に関する説明を参照)で行うことができます。 # first rebase $ git checkout $user/$topic $ git fetch $ git rebase origin/blead # then "delete-and-push" $ git push origin :$user/$topic $ git push origin $user/$topic =begin original B it is forbidden at the repository level to delete any of the "primary" branches. That is any branch matching C. Any attempt to do so will result in git producing an error like this: =end original B<注意:> リポジトリレベルで"プライマリ"ブランチを削除することは 禁止されています。 これは C にマッチングするブランチです。 削除しようとすると、gitは次のようなエラーを生成します: $ git push origin :blead *** It is forbidden to delete blead/maint branches in this repository error: hooks/update exited with error code 1 error: hook declined to update refs/heads/blead To ssh://perl5.git.perl.org/perl ! [remote rejected] blead (hook declined) error: failed to push some refs to 'ssh://perl5.git.perl.org/perl' =begin original As a matter of policy we do B edit the history of the blead and maint-* branches. If a typo (or worse) sneaks into a commit to blead or maint-*, we'll fix it in another commit. The only types of updates allowed on these branches are "fast-forward's", where all history is preserved. =end original ポリシーとして、blead ブランチと maint-* ブランチの履歴は編集 B<しません>。 タイプミス(またはそれ以上)が blead または maint-* へのコミットに 忍び込んだ場合は、別のコミットで修正します。 これらのブランチで許可されている更新のタイプは "fast-forward" だけで、 すべての履歴が保存されます。 =begin original Annotated tags in the canonical perl.git repository will never be deleted or modified. Think long and hard about whether you want to push a local tag to perl.git before doing so. (Pushing unannotated tags is not allowed.) =end original 標準的な perl.git リポジトリ内の注釈付きタグは、削除や 変更されることはありません。 ローカルタグを perl.git にプッシュする前に、じっくり考えてみてください (注釈なしタグのプッシュは許可されていません)。 =head2 Grafts (接ぎ木) =begin original The perl history contains one mistake which was not caught in the conversion: a merge was recorded in the history between blead and maint-5.10 where no merge actually occurred. Due to the nature of git, this is now impossible to fix in the public repository. You can remove this mis-merge locally by adding the following line to your C<.git/info/grafts> file: =end original Perl履歴には、変換で検出されなかった誤りが一つ含まれています: blead と maint-5.10 の間の履歴にマージが記録されましたが、 実際にはマージは発生しませんでした。 git の性質上、パブリックリポジトリで修正することは現在不可能です。 C<.git/info/graft> ファイルに次の行を追加することで、 この誤ったマージをローカルで削除できます。 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930 =begin original It is particularly important to have this graft line if any bisecting is done in the area of the "merge" in question. =end original 問題の「マージ」領域で bisect が行われる場合、この graft 行を 指定することが特に重要です。 =head1 WRITE ACCESS TO THE GIT REPOSITORY (git リポジトリへの書き込みアクセス) =begin original Once you have write access, you will need to modify the URL for the origin remote to enable pushing. Edit F<.git/config> with the git-config(1) command: =end original 一旦書き込み権限を得たら、 プッシュを有効にするために origin remote のための URL を 変更する必要があります。 git-config(1) コマンドで F<.git/config> を次のように編集します: % git config remote.origin.url ssh://perl5.git.perl.org/perl.git =begin original You can also set up your user name and e-mail address. Most people do this once globally in their F<~/.gitconfig> by doing something like: =end original ユーザー名と電子メールアドレスを設定することもできます。 ほとんどの人は、以下のようにすることで F<~/.gitconfig> でグローバルに 一度これを行います: % git config --global user.name "Ævar Arnfjörð Bjarmason" % git config --global user.email avarab@gmail.com =begin original However, if you'd like to override that just for perl, execute something like the following in F: =end original しかし、perl だけに対してこれを変更したい場合は、 F で次のようなものを実行します: % git config user.email avar@cpan.org =begin original It is also possible to keep C as a git remote, and add a new remote for ssh access: =end original C を git remote として維持し、ssh アクセス用の新しい remote を 追加することも可能です: % git remote add camel perl5.git.perl.org:/perl.git =begin original This allows you to update your local repository by pulling from C, which is faster and doesn't require you to authenticate, and to push your changes back with the C remote: =end original これにより、C からプルしてローカルリポジトリを更新できます; これはより高速で、認証を必要としません; また、C リモートで変更をプッシュバックすることもできます。 % git fetch camel % git push camel =begin original The C command just updates the C refs, as the objects themselves should have been fetched when pulling from C. =end original C コマンドは単に C refs を更新するだけです; なぜなら、オブジェクト自体は C からプルするときに フェッチされるべきだからです。 =head2 Accepting a patch (パッチを受け入れる) =begin original If you have received a patch file generated using the above section, you should try out the patch. =end original 前述の節でを使って生成されたパッチファイルを受け取った場合は、 パッチを試してみてください。 =begin original First we need to create a temporary new branch for these changes and switch into it: =end original まず、これらの変更のための一時的な新しいブランチを作成し、そのブランチに 切り替える必要があります: % git checkout -b experimental =begin original Patches that were formatted by C are applied with C: =end original C でフォーマットされたパッチは、C で適用されます: % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch Applying Rename Leon Brocard to Orange Brocard =begin original If just a raw diff is provided, it is also possible use this two-step process: =end original 生の diff だけが提供されている場合は、次の 2 段階のプロセスを 使用することもできます: % git apply bugfix.diff % git commit -a -m "Some fixing" --author="That Guy " =begin original Now we can inspect the change: =end original ここで変更を検査できます: % git show HEAD commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 Author: Leon Brocard Date: Fri Dec 19 17:02:59 2008 +0000 Rename Leon Brocard to Orange Brocard diff --git a/AUTHORS b/AUTHORS index 293dd70..722c93e 100644 --- a/AUTHORS +++ b/AUTHORS @@ -541,7 +541,7 @@ Lars Hecking Laszlo Molnar Leif Huhn Len Johnson -Leon Brocard +Orange Brocard Les Peters Lesley Binks Lincoln D. Stein =begin original If you are a committer to Perl and you think the patch is good, you can then merge it into blead then push it out to the main repository: =end original もしあなたが Perl のコミッタで、パッチが良いものだと思うなら、 それを blead にマージしてメインのリポジトリにプッシュすることができます: % git checkout blead % git merge experimental % git push origin blead =begin original If you want to delete your temporary branch, you may do so with: =end original 一時的なブランチを削除したいなら、以下のようにできます: % git checkout blead % git branch -d experimental error: The branch 'experimental' is not an ancestor of your current HEAD. If you are sure you want to delete it, run 'git branch -D experimental'. % git branch -D experimental Deleted branch experimental. =head2 Committing to blead (blead にコミットする) =begin original The 'blead' branch will become the next production release of Perl. =end original 'blead' ブランチは、Perl の次の正式版リリースになります。 =begin original Before pushing I local change to blead, it's incredibly important that you do a few things, lest other committers come after you with pitchforks and torches: =end original I<何らかの> ローカルな変更をプッシュする前に、 あなたの後から来る他のコミッタが熊手と松明を持ってこないように、 いくつかのことをするのが極めて重要です: =over =item * =begin original Make sure you have a good commit message. See L for details. =end original よいコミットメッセージを書くようにしてください。 詳しくは L を参照してください。 =item * =begin original Run the test suite. You might not think that one typo fix would break a test file. You'd be wrong. Here's an example of where not running the suite caused problems. A patch was submitted that added a couple of tests to an existing .t. It couldn't possibly affect anything else, so no need to test beyond the single affected .t, right? But, the submitter's email address had changed since the last of their submissions, and this caused other tests to fail. Running the test target given in the next item would have caught this problem. =end original テストスイートを実行します。 一つのタイプミス修正がテストファイルを壊すとは思わないかもしれません。 それは間違いです。 スイートを実行しないと問題が発生する例を次に示します。 既存の .t にいくつかのテストを追加するパッチが提出されました。 他の何にも影響する可能性はないので、 影響を受けた一つ以上をテストする必要はありません。 そうですね? しかし、送信者のメールアドレスが前回の送信時から変更されていて、 このための他のテストが失敗するようになりました。 次の項目のテストターゲットを実行すると、この問題を捕まえられます。 =item * =begin original If you don't run the full test suite, at least C. This will run basic sanity checks. To see which sanity checks, have a look in F. =end original 完全なテストスイートを実行しない場合でも、 最低 C は実行してください。 これは基本的な正気チェックを実行します。 どの正気チェックかを見るには、F を見てください。 =item * =begin original If you make any changes that affect miniperl or core routines that have different code paths for miniperl, be sure to run C. This will catch problems that even the full test suite will not catch because it runs a subset of tests under miniperl rather than perl. =end original miniperl や miniperl のための異なるコードパスを持つコアルーチンに 影響する変更を行う場合、C をするようにしてください。 これは、perl ではなく miniperl でテストの一部を行うために完全な テストスイートでは捕捉できない問題も捕捉します。 =back =head2 On merging and rebasing (マージとリベース時) =begin original Simple, one-off commits pushed to the 'blead' branch should be simple commits that apply cleanly. In other words, you should make sure your work is committed against the current position of blead, so that you can push back to the master repository without merging. =end original 'blead' ブランチにプッシュされた、単純な 1 回限りのコミットは、 クリーンに適用される単純なコミットであるべきです。 言い換えると、作業したものは blead の現在の位置に対して コミットすることで、マージすることなく master に プッシュできるようにするべきです。 =begin original Sometimes, blead will move while you're building or testing your changes. When this happens, your push will be rejected with a message like this: =end original あなたが変更したものをビルドしたりテストしたりしている間に、 時々 blead は動きます。 これが起きると、プッシュは次のようなメッセージで拒否されます: To ssh://perl5.git.perl.org/perl.git ! [rejected] blead -> blead (non-fast-forward) error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git' To prevent you from losing history, non-fast-forward updates were rejected Merge the remote changes (e.g. 'git pull') before pushing again. See the 'Note about fast-forwards' section of 'git push --help' for details. =begin original When this happens, you can just I your work against the new position of blead, like this (assuming your remote for the master repository is "p5p"): =end original これが起きた場合、次のようにして、blead の新しい位置に対してあなたの作業を 単に I<リベース> します (master リポジトリに対するあなたのリモート名を "p5p" と仮定します): $ git fetch p5p $ git rebase p5p/blead =begin original You will see your commits being re-applied, and you will then be able to push safely. More information about rebasing can be found in the documentation for the git-rebase(1) command. =end original コミットが再適用され、安全にプッシュできるようになります。 リベースに関するさらなる情報は、git-rebase(1) コマンドの文書にあります。 =begin original For larger sets of commits that only make sense together, or that would benefit from a summary of the set's purpose, you should use a merge commit. You should perform your work on a L, which you should regularly rebase against blead to ensure that your code is not broken by blead moving. When you have finished your work, please perform a final rebase and test. Linear history is something that gets lost with every commit on blead, but a final rebase makes the history linear again, making it easier for future maintainers to see what has happened. Rebase as follows (assuming your work was on the branch C<< committer/somework >>): =end original 一緒にすることでのみ意味がある、または集合の目的の要約としての 価値があるような、より大きなコミットの集合に対しては、 マージコミットを使うべきです。 作業は L<トピックブランチ|/Topic branches and rewriting history> で行うべきです; そして、blead の移動によってあなたのコードが壊れていないことを 確認するために定期的に blead に対してリベースするべきです。 作業が終わったら、最後にリベースしてテストしてください。 線形の履歴は blead にコミットされる度に失われますが、 最後のリベースは再び履歴を線形にし、 将来の保守者が何が起きたのかを見るのをより容易にします。 次のようにしてリベースします (あなたの作業が C<< committer/somework >> ブランチにあると仮定します): $ git checkout committer/somework $ git rebase blead =begin original Then you can merge it into master like this: =end original それから次のようにして master にマージできます: $ git checkout blead $ git merge --no-ff --no-commit committer/somework $ git commit -a =begin original The switches above deserve explanation. C<--no-ff> indicates that even if all your work can be applied linearly against blead, a merge commit should still be prepared. This ensures that all your work will be shown as a side branch, with all its commits merged into the mainstream blead by the merge commit. =end original 前述のスイッチは説明が必要でしょう。 C<--no-ff> は、たとえあなたの作業が blead に対して線形に適用可能でも、 マージコミットが準備されることを示します。 これによりあなたの作業は側道のブランチとして表示され、 そのコミットはマージコミットによってメインの blead に マージされることになります。 =begin original C<--no-commit> means that the merge commit will be I but not I. The commit is then actually performed when you run the next command, which will bring up your editor to describe the commit. Without C<--no-commit>, the commit would be made with nearly no useful message, which would greatly diminish the value of the merge commit as a placeholder for the work's description. =end original C<--no-commit> は、マージコミットは I<準備> はされますが I<コミット> はされないことを意味します。 コミットは実際には次のコマンドを実行して、 コミットの説明のためにエディタが起動した後に実行されます。 C<--no-commit> なしの場合、 有用なメッセージなしでコミットが行われます; これは作業の説明のためのプレースホルダとしてマージコミットの価値を 大幅に減らしてしまいます。 =begin original When describing the merge commit, explain the purpose of the branch, and keep in mind that this description will probably be used by the eventual release engineer when reviewing the next perldelta document. =end original マージコミットの説明を書くとき、 このブランチの目的を説明してください; そしてこの説明はおそらく次の perldelta 文書をレビューするときに 最終的なリリースエンジニアによって使われるだろうということを 心に留めておいてください。 =head2 Committing to maintenance versions (メンテナンスバージョンにコミットする) =begin original Maintenance versions should only be altered to add critical bug fixes, see L. =end original メンテナンスバージョンは、重要なバグ修正を追加する場合にのみ変更してください; L を参照してください。 =begin original To commit to a maintenance version of perl, you need to create a local tracking branch: =end original perl のメンテナンスバージョンにコミットするには、 ローカル追跡ブランチを作成する必要があります。 % git checkout --track -b maint-5.005 origin/maint-5.005 =begin original This creates a local branch named C, which tracks the remote branch C. Then you can pull, commit, merge and push as before. =end original これにより、リモートブランチ C を追跡する C という名前のローカルブランチが作成されます。 次に、以前と同じようにプル、コミット、マージ、プッシュを行うことができます。 =begin original You can also cherry-pick commits from blead and another branch, by using the C command. It is recommended to use the B<-x> option to C in order to record the SHA1 of the original commit in the new commit message. =end original C コマンドを使用して、blead と別のブランチから コミットをチェリーピックすることもできます。 元のコミットの SHA1 を新しいコミットメッセージに記録するために、 C に B<-x> オプションを使うことを勧めます。 =begin original Before pushing any change to a maint version, make sure you've satisfied the steps in L above. =end original maint 版に何かをプッシュする前に、前述の L のステップを満たしていることを確認してください。 =head2 Merging from a branch via GitHub (GitHub 経由のブランチをマージする) =begin original While we don't encourage the submission of patches via GitHub, that will still happen. Here is a guide to merging patches from a GitHub repository. =end original 私たちはパッチを GitHub 経由で投稿することを勧めていませんが、 実際発生します。 これは GitHub リポジトリからのパッチをマージするためのガイドです。 % git remote add avar git://github.com/avar/perl.git % git fetch avar =begin original Now you can see the differences between the branch and blead: =end original これで、そのブランチと blead の差分を見られるようになりました: % git diff avar/orange =begin original And you can see the commits: =end original そしてコミットを表示できます: % git log avar/orange =begin original If you approve of a specific commit, you can cherry pick it: =end original 特定のコミットを承認する場合は、次のようにして選択できます: % git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae =begin original Or you could just merge the whole branch if you like it all: =end original または、必要に応じてブランチ全体をマージすることもできます: % git merge avar/orange =begin original And then push back to the repository: =end original そして、リポジトリにプッシュバックします: % git push origin blead =head2 Using a smoke-me branch to test changes (変更をテストするために smoke-me ブランチを使う) =begin original Sometimes a change affects code paths which you cannot test on the OSes which are directly available to you and it would be wise to have users on other OSes test the change before you commit it to blead. =end original 時々、ある変更があなたが直接利用できない OS に関するテストできない コードパスに影響することがあるので、 blead にコミットする前に他の OS のユーザーが変更をテストしてもらうのが 賢明です。 =begin original Fortunately, there is a way to get your change smoke-tested on various OSes: push it to a "smoke-me" branch and wait for certain automated smoke-testers to report the results from their OSes. =end original 幸い、様々な OS であなたの変更をスモークテストする方法があります: これを "smoke-me" ブランチとしてプッシュして、いくつかの自動 smoke-testers が彼らの OS からの結果を報告するのを待ちます。 =begin original The procedure for doing this is roughly as follows (using the example of of tonyc's smoke-me branch called win32stat): =end original これをするための手順は大まかに次のようなものです (tonyc による win32stat と呼ばれる smoke-me ブランチの例を使います): =begin original First, make a local branch and switch to it: =end original まず、ローカルブランチを作ってそれに切り替えます: % git checkout -b win32stat =begin original Make some changes, build perl and test your changes, then commit them to your local branch. Then push your local branch to a remote smoke-me branch: =end original 変更を行い、perl をビルドして変更をテストし、ローカルブランチに コミットします。 それからローカルブランチをリモートの smoke-me ブランチにプッシュします: % git push origin win32stat:smoke-me/tonyc/win32stat =begin original Now you can switch back to blead locally: =end original ここでローカルの blead に戻します: % git checkout blead =begin original and continue working on other things while you wait a day or two, keeping an eye on the results reported for your smoke-me branch at L. =end original そして他の作業をして数日待ち、smoke-me ブランチに対する報告される結果 L を注視します。 =begin original If all is well then update your blead branch: =end original 全てがうまくいっていれば、手元の blead ブランチを更新します: % git pull =begin original then checkout your smoke-me branch once more and rebase it on blead: =end original それからもう一度手元の smoke-me ブランチをチェックアウトして、 それを blead にリベースします: % git rebase blead win32stat =begin original Now switch back to blead and merge your smoke-me branch into it: =end original ここで blead に戻して、smoke-me ブランチをマージします: % git checkout blead % git merge win32stat =begin original As described earlier, if there are many changes on your smoke-me branch then you should prepare a merge commit in which to give an overview of those changes by using the following command instead of the last command above: =end original 前述したように、smoke-me ブランチに多くの変更がある場合は、 前述の最後のコマンドの代わりに次のコマンドを使うことで、 これらの変更の概要を記録するためのマージコミットを準備するべきです: % git merge win32stat --no-ff --no-commit =begin original You should now build perl and test your (merged) changes one last time (ideally run the whole test suite, but failing that at least run the F tests) before pushing your changes as usual: =end original ここで perl をビルドして、いつものように変更をプッシュする前に、 あなたの(マージされた)変更を最後にもう一度テストするべきです (理想的には、テストスイート全体を実行します; しかし、 少なくとも F テストを実行します) 。 % git push origin blead =begin original Finally, you should then delete the remote smoke-me branch: =end original 最後に、リモートの smoke-me ブランチを削除して: % git push origin :smoke-me/tonyc/win32stat =begin original (which is likely to produce a warning like this, which can be ignored: =end original (これはおそらく次のような警告を出しますが、無視できます: remote: fatal: ambiguous argument 'refs/heads/smoke-me/tonyc/win32stat': unknown revision or path not in the working tree. remote: Use '--' to separate paths from revisions =begin original ) and then delete your local branch: =end original ) そしてローカルブランチを削除します: % git branch -d win32stat =head2 A note on camel and dromedary (camel と dromedary に関する注意) =begin original The committers have SSH access to the two servers that serve C. One is C itself (I), which is the 'master' repository. The second one is C (I), which can be used for general testing and development. Dromedary syncs the git tree from camel every few minutes, you should not push there. Both machines also have a full CPAN mirror in /srv/CPAN, please use this. To share files with the general public, dromedary serves your ~/public_html/ as C =end original コミッタは、C にサービスを提供する二つの サーバにアクセスできます。 C 自身 (I) で、 これが「マスター」リポジトリです。 二つ目は C (I) で、 一般的なテストと開発に使用できます。 dromedary は数分ごとに camel から git ツリーを同期するので、そこに プッシュしてはいけません。 両方のマシンには /srv/CPAN に完全な CPAN ミラーもあるので、 これを使ってください。 dromedary はファイルを一般公開するために、 ~/public_html/ を C として 提供しています。 =begin original These hosts have fairly strict firewalls to the outside. Outgoing, only rsync, ssh and git are allowed. For http and ftp, you can use http://webproxy:3128 as proxy. Incoming, the firewall tries to detect attacks and blocks IP addresses with suspicious activity. This sometimes (but very rarely) has false positives and you might get blocked. The quickest way to get unblocked is to notify the admins. =end original これらのホストは、外部に対してかなり厳格なファイアウォールを持っています。 送信は rsync、ssh、git だけが許可されています。 http と ftp に対しては、プロキシとして http://webproxy:3128 を使用できます。 受信は、ファイアウォールは攻撃を検出し、疑わしいアクティビティを持つ IP アドレスをブロックしようとします。 これは時に(非常にまれに)誤検出があり、ブロックされる可能性があります。 ブロックを解除する最も簡単な方法は、管理者に通知することです。 =begin original These two boxes are owned, hosted, and operated by booking.com. You can reach the sysadmins in #p5p on irc.perl.org or via mail to C. =end original これら二つのボックスは、booking.com によって所有され、ホストされ、 運営されています。 システム管理者には、irc.perl.org の #p5p か、 C へのメールで連絡できます。 =begin meta Translate: SHIRAKATA Kentaro Status: completed =end meta