Gerrit/チュートリアル
このチュートリアルは、Gerrit で変更点を作成/変更するために Git を使用する方法を説明するものです。
- 特定のタスクについての説明文書については、代わりに Gerrit/高度な使用法 をチェックしてください。
- Gerrit を試したいだけで、「実際の」ウィキメディア ソフトウェア プロジェクトのパッチを書きたいわけではない場合は、代わりに Gerrit テスト インスタンスを使用してください。
このチュートリアルでは、入力するコマンドは以下のようにドル記号 ($) で始まります: コマンド。
$ 接頭辞は入力しないでください。
コマンドに、自分で変更する必要がある変数も含まれている場合、変数は赤で表示されます: コマンド 変数。
Git とは
Gitは、無料でオープンソースの分散型バージョン管理システムです。 「分散」は、リポジトリの中央管理コピーがないことを意味します。 Git では、リポジトリのクローンを作成すると、ソースコードの完全に機能するコピーが、すべてのブランチとタグ付きリリースを含めてダウンロードされます。
ウィキメディア開発者アカウントの作成
ウィキメディア開発者アカウントをまだお持ちではない場合は、アカウントを作成してください。 同じ利用者名とパスワードが、下記の Gerrit へのログインでも使用されます。
Git をセットアップする
これらの手順では、Git をコマンド ライン (ターミナル ウィンドウ) ツールとしてインストールする方法を説明します。 コマンド ラインではなくグラフィカル ユーザー インターフェイス (GUI) を使用したい場合は、Git プロジェクトが管理しているクライアント一覧を確認してください。 別のインストール手順については、公式の説明文書を参照してください。
インストール
Follow Installing Git to learn how to install git on your operating system.
Gitの設定
git config -lを使用してください。さてGitがインストールされて、個人情報を設定する時間です。 1回だけはこれを行う必要があります。 これらのコマンドを再度実行することによって、いつでも個人情報を変更することもできます。
Gitは利用者の名前とメールをチェックすることによって、各々のコミットを誰が行ったのか追跡します。 さらに、この情報はあなたのコミットをあなたのGerritアカウントと関連付けるために使われます。
以下の2つのコマンドを入力して、あなたの利用者名とメールアドレスを設定してください。 Gerrituserを自分のウィキメディア開発者アカウントの利用者に置換してください (これは以前「Wikitech」、「Gerrit」、「LDAP」利用者名として知られていたもので、これらはすべて同じものです)。 gerrituser@example.com を自分のメールアドレスに置換してください。 そして、shell_user を (ウィキメディア開発者アカウントを作成するときに選択した) シェル ユーザー名に置換してください:
git config --global user.email "gerrituser@example.com"
git config --global user.name "Gerrituser"
git config --global url."ssh://shell_user@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"
GerritでSSH鍵をセットアップする
あなたのコンピュータとGerritの間に安全な接続を確立するために、SSH鍵を使います。
2021年8月現在、ウィキメディアセキュリティチームは、最適なセキュリティとパフォーマンスのために、利用者がSSH鍵の作成に ed25519 タイプを使うことを推奨します。
SSH鍵を取得する
Follow SSH keys#Generating a new SSH key.
SSH公開鍵をGerritアカウントに追加する
- Gerritのウェブインターフェースにログインします。 Gerritの利用者名とパスワードは、ウィキメディア開発者アカウントと同一です。
- 右上隅にあるユーザー名をクリックし、「設定」を選択します。
- 左側のメニューで「SSHキー」をクリックします。
- SSH公開鍵を対応する欄に貼り付けて、 "ADD NEW SSH KEY"をクリックしてください。
Gerrit SSHの接続をテストする
ssh経由でGerritサーバーに接続し、すべてが期待どおりに動作しているかどうかを確認します。
Replace shell_user by your shell username as shown in your Gerrit settings:
ssh -p 29418 shell_user@gerrit.wikimedia.org
- Be mindful and compare that the "ed25519 key fingerprint" is the same as the SSH fingerprint for gerrit.wikimedia.org:29418. If it is the same, answer "Yes" to "Are you sure you want to continue connecting?". Then enter the passphrase for your key.
- You should get a message "Welcome to Gerrit Code Review". The last line should show "Connection to gerrit.wikimedia.org closed."
- If you run into problems, use
ssh -p 29418 -v shell_user@gerrit.wikimedia.org(replace shell_user by your shell username).-vは問題を見つけるのを手助けするために冗長出力を提供します。 それからGerritトラブルシューティングを読んでください。
Gerrit SSH接続成功メッセージの例はこのようになります：
gerrituser@machine:/mw/sandbox$ ssh -p 29418 gerrituser@gerrit.wikimedia.org The authenticity of host '[gerrit.wikimedia.org]:29418 ([208.80.154.85]:29418)' can't be established. ed25519 key fingerprint is dc:e9:68:7b:99:1b:27:d0:f9:fd:ce:6a:2e:bf:92:e1. Are you sure you want to continue connecting (yes/no)? yes Warning permanently added '[gerrit.wikimedia.org]:29418 ([208.80.154.85]:29418)' (ed25519) to the list of known hosts. Enter passphrase for key '/home/gerrituser/.ssh/id_ed25519': **** Welcome to Gerrit Code Review **** Hi gerrituser, you have successfully connected over SSH. Unfortunately, interactive shells are disabled. To clone a hosted Git repository, use: git clone ssh://gerrit.wikimedia.org:29418/REPOSITORY_NAME.git Connection to gerrit.wikimedia.org closed. gerrituser@machine:/mw/sandbox$
Gitを使ってコードをダウンロードする
サンドボックス
Gerrit の使用法を練習したい場合は、このチュートリアルが使用している「sandbox」というリポジトリをダウンロード (「クローン」とも言います) してください。
以下をGit Bashコマンドラインで実行します：
git clone https://gerrit.wikimedia.org/r/sandbox
This will copy the entire history and the code base of the "sandbox" extension repository into your machine.
You will have a working directory of the extension's main branch (usually also called "git master").
Enter the new directory (via the command cd sandbox).
Now you can look at the code and start editing it.
既存のリポジトリ
Cloning the Sandbox repository will not give you a development environment setup or a running MediaWiki installation. (Running will require MediaWiki Core and placing the code you checked out in a location expected by your web server.) See Download from Git for how to download MediaWiki Core, extensions, skins, or any other project repository hosted at gerrit.wikimedia.org from Git.
Vagrant
Vagrant を使用して MediaWiki や拡張機能をダウンロードした場合、Git が HTTPS ではなく SSH を使用してコードをプッシュするように構成されていることを確認してください。
Gerritで作業する準備
Gerrit requires that your commit message must have a "change ID".
それらはI（iの大文字）で始まるChange-Id: Ibd3be19ed1a23c8638144b4a1d32f544ca1b5f97のようなものです。
Each time you amend a commit to improve an existing patch in Gerrit, this change ID stays the same, so Gerrit understands it as a new "patch set" to address the same code change.
There's a git add-on called git-review that adds a Change-Id line to your commits.
Using git-review is recommended.
It makes it easier to configure your Git clone, to submit a change or to fetch an existing one.
git-review のインストール
ウィキメディア Gerritは、git-review バージョン1.27以降を必要とすることに注意してください。
詳細は、Gerrit/git-review#インストールを参照してください。
Linux
- Linuxディストリビューションのグラフィカルソフトウェアパッケージ管理ツールを使用して、
git-reviewパッケージをインストールします。 - git-reviewがディストリビューションにパッケージ化されていない場合は、pip Pythonパッケージインストーラーを使ってgit-reviewをインストールするなどのその他のオプションをgit-reviewで確認してください。
- FreeBSDを使っているならば、portsでgit-reviewをインストールしてください。
Windows
- git-review Windowsを参照してください。
macOS
- For OS X 10.11 El Capitan and later, follow Method 1.
- On versions prior to 10.11, use the pip Python package installer by following Method 2.
git-reviewを設定する
Gitのデフォルトのリモートホスト名は"origin"です。 この名前はウィキメディアプロジェクトでも使われます。 git-reviewにそのホストを使うように教える必要があります。 gerrituserをあなたのGerrit利用者名で置き換えてください：
git config --global gitreview.remote origin
git config --global gitreview.username gerrituser
git-reviewをセットアップする
リポジトリをダウンロード（「クローン」）した後、git-reviewのためにセットアップする必要があります。 This will automatically happen the first time you try to submit a commit, but it's generally better to do it right after cloning. Make sure that you are in the directory of the project that you cloned (otherwise you will get an error "fatal: Not a git repository"). それからこのコマンドを実行してください：
git review -s --verbose
出力の最後の方に、このようなものが表示されるはずです：
Found origin Push URL: ssh://gerrit.wikimedia.org:29418/PROJECT Fetching commit hook from: scp://gerrit.wikimedia.org:29418/hooks/commit-msg 2019-02-19 12:40:16.712892 Running: scp -P29418 gerrit.wikimedia.org:hooks/commit-msg .git/hooks/commit-msg
使用しているシェルのユーザー名と異なる場合、これはgitのユーザー名を尋ねるかもしれません。
git-review, then you could use the Gerrit patch uploader or Gerrit/Web tutorial to submit a patch.By default git-review uses the branch master.
If the repo you're working on uses another branch, e.g. main, you need to set the config variable gitreview.branch.
This can be done with the following command (where main is the branch name):
git config --add gitreview.branch main
パッチを投稿する
あなたが関心のあるコードリポジトリをクローンしたことを確かめてください（上述のGitを使ってコードをダウンロードするを参照）。
コードリポジトリのディレクトリにいることを確かめてください（コマンドpwdはあなたがどこにいるのか正確に教えてくれます）。
Update the main development branch
Make sure that the main development branch (the branch created when you initially cloned the repository) is up to date:
git pull origin master
However, note that some repositories use a different name for their main development branch (for example main instead of master, or the operations/puppet repository has a production instead of a master branch).
ブランチの作成
まず、あなたの新しい変更についてローカルブランチを作成します。
以下のBRANCHNAMEを短いけれど適度に説明的な名前で置き換えます。（例えば、あなたの変更に対応するPhabricatorのタスクが存在するならばT1234としたり、cleanup-something、あるいはbadtitle-error）。
他の人たちもあなたのブランチを識別するために、この名前を使用します。
git checkout -b BRANCHNAME origin/master
gerrituser@example:~/dev/mw$ git checkout -b cleanup-something origin/master # Switched to a new branch 'cleanup-something' gerrituser@example:~/dev/mw$ git branch * cleanup-something master
This will create a new branch (called BRANCHNAME) from the latest 'master' and check it out for you.
上記の例では、新しいブランチをcleanup-somethingと呼びます。
変更を行う
ローカルのコードに変更を行います。
好きなテキストエディタを使ってファイルを修正してください。
以下の例では、ファイルREADME.mdを編集して単語を追加しています。
それからテキストエディタを閉じて、ファイルやディレクトリの中で、最後のコミット以降にあなたが行った変更をチェックしてください：
git diff
gerrituser@machine:/mw/sandbox$ git diff diff --git a/README.md b/README.md index 1d25b27..bc54021 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Hello world! -You can make test changes and experiment with Gerrit in this repository! +You can make test changes and experiment with Wikimedia Gerrit in this repository! Don't worry about messing this repository up; it is meant for testing. gerrituser@machine:/mw/examples$
git diffはあなたの変更をユニファイド形式 (Unified format)で表示します：除去された行はマイナス (-) から始まり、追加された行はプラス (+) から始まります。
これらの変更はまだ次のコミットのために（git addによって）「ステージ」されていません。
変更をコミットするためにステージする
どの変更をあなたのコミットに組み込むべきか決定するために、git statusを実行してください。
これによりディレクトリの中であなたが変更したファイルの一覧が表示されます。
この時点では、出力の最後の行に "no changes added to commit"（コミットに変更が追加されていません）と表示されます。
あなたの変更したファイルを次のあなたのコミットに組み込むにはgit addを使用してください。
上記の例ではファイルREADME.mdを修正しましたので、コマンドは以下のようになります：
git add README.md
git addに渡していないあらゆる変更したファイルは、次のステップでgit commitを実行するときに無視されます。
git statusを実行することによって、既にステージした変更をいつでも見直すことができます。
git addを実行した後には、git statusはもう "no changes added to commit" （コミットに変更が追加されていません）という行を表示しません。git diff --cached to see which changes are staged and will go into the next commit.
出力は上記のgit diffコマンドと同じように見えます。
ステージした変更をコミットする
git add によって追加した変更の一覧に満足したら、以下を使用することでこれらの変更をローカル リポジトリにコミットすることができます
git commit
Short subject line More details. The blank line between the subject and body is mandatory. The subject line is used to represent the commit in code-review emails, search results, git-rebase, and more. Bug: T999999 # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # # On branch cleanup-something # Your branch is up to date with 'origin/master'. # # Changes to be committed: # modified: README.md
その後テキストエディタであなたのコミットに対する説明的な要約を追加するように求められます。 コミット メッセージの指針に従わなければなりません。 これはコードリポジトリの変更履歴を見るときに、他の人たちが参照するものです。
コミットメッセージを保存してテキストエディタを閉じてください。 A summary (the commit ID, your subject line, the files and lines changed) will be displayed.
git commitをするとき、ローカルコピーにコミットしています。
Gerritへコミットをプッシュする準備
Synchronise your changeset with any changes that may have occurred in the master branch while you've been working ("rebasing"). From within your branch, run:
git pull --rebase origin master
gerrituser@machine:/mw/sandbox$ git pull --rebase origin master From ssh://gerrit.wikimedia.org:29418/sandbox * branch master -> FETCH_HEAD Current branch cleanup-something is up to date. gerrituser@machine:/mw/sandbox$
git pull --rebase origin master will fetch new commits from the remote and then rebase your local commits on top of them.
それは、一時的にブランチで行った変更を取り置き、マスターで行われたすべての変更を作業ブランチに適用した後、ブランチに行ったすべての変更を再度マージ (再コミット) します。 Doing this will help avoid future merge conflicts.
Plus, it gives you an opportunity to test your changes against the latest code in master.さてレビューのためにGerritへコードをプッシュする準備ができました。 もし関連するコミットを複数回行っていたならば、 レビューのためにそれらを単一のコミットにマージすることを検討してください。
Gerritへコミットをプッシュする
If you followed #Prepare to work with Gerrit above and installed git-review and ran git review -s, then the command to push changes to Gerrit is:
git review
gerrituser@machine:/mw/sandbox$ git review Creating a git remote called 'gerrit' that maps to: ssh://gerrit.wikimedia.org:29418/sandbox.git Your change was committed before the commit hook was installed. Amending the commit to add a gerrit change id. remote: remote: Processing changes: new: 1, done remote: remote: New Changes: remote: https://gerrit.wikimedia.org/r/#/c/sandbox/+/563720 Test for https://www.mediawiki.org/wiki/Gerrit/Tutorial remote: To ssh://gerrit.wikimedia.org:29418/sandbox.git * [new branch] HEAD -> refs/for/master%topic=cleanup-something gerrituser@machine:/mw/examples$
Upon success, you'll get a confirmation and a link to the changeset in Gerrit. In the example above, that link is: https://gerrit.wikimedia.org/r/#/c/sandbox/+/563720
Congratulations! Your patch is in Gerrit and hopefully will get reviewed soon!
If git review fails
git review を実行する際にユーザー名とパスワードの入力を求められた場合、それは Git が SSH を使用できるようにまだ設定されていないことを意味します。
Review the steps at #Set up Git. In particular, run the following command:
git config --global url."ssh://shell_user@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"
This is okay to run again if you're not sure whether you did it already. Replace shell_user with the shell username for your Wikimedia Developer account.
Permission denied (publickey). fatal: Could not read from remote repository. を受け取った場合は、SSHキー の手順を確認し、SSH エージェントが実行中であり、あなたの識別情報が追加されていることを確認してください。 Git Bash シェルを閉じるとサインアウトされ、毎回これらの手順を再度実行する必要があります。
View the Change / Next Steps
Open the link to your Gerrit changeset in a web browser.
「ファイル」配下で、一覧内の任意のファイルの右端にある下矢印をクリックすると、ファイルごとの変更差分を閲覧できます。古い行は赤色で表示され、新しい行は緑色で表示されます。
コミットが Phabricator のチケットに関連している場合、コミット メッセージのガイドラインに従っていれば、Phabricator タスクにコメントが自動的に追加されます。 そうしなかった場合は、コミット メッセージを修正する (新しいパッチセットを作成する)、または Phabricator チケットに Gerrit の変更セットへのリンクを含むコメントを手動で追加できます。
その他のよくある状況
もしあなたの状況がここで取り扱われていなければ、Gerritの高度な使用法も参照してください。
Squash several commits into one single commit via rebase
レビュー用に提出したい場合に、ローカル リポジトリに関連する複数のコミットを作成していた場合は、それらのコミットを 1 つのコミットにまとめる (スカッシュする) べきです。
The --interactive or -i option allows you to change (rewrite) your commit history.
各コミットについて、コミット メッセージの変更、ファイルの追加または削除、その他の修正を行えます。
First you need to tell git how far back you want to pull. To get a list of all changes in your branch:
git rebase -i origin/master
You can also limit the displayed list of recent changes. HEAD~3 means pull the last three commits:
git rebase -i HEAD~3
このコマンドを入力すると、テキスト エディターにコミットが逆順で表示され、利用可能なコマンドの一覧が表示されます:
pick aa8cf1d Adding method customFilterFunctionGetRiskyCountryCodeScore() to GatewayAdapter. pick 38828e2 Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php pick be33007 Fix a typo # Rebase 95ccd28..be33007 onto 95ccd28 # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # x, exec = run command (the rest of the line) using shell # # If you remove a line here THAT COMMIT WILL BE LOST. # However, if you remove everything, the rebase will be aborted. #
レビューに送信するのは 1 つのコミットのみなので、最後の 2 つのコミットを最初のコミットに統合 (スカッシュ) します。
Hence change all but the first pick to squash:
pick aa8cf1d Adding method customFilterFunctionGetRiskyCountryCodeScore() to GatewayAdapter. squash 38828e2 Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php squash be33007 Fix a typo
ピック/スカッシュが完了しファイルを保存すると、別のファイルがテキスト エディターで開かれ、コミット メッセージを編集/マージできるようになります。
Change-Id の行は 1 つだけ残し、メッセージの最後に 1 行空けて配置するように注意してください。
以前のコミットからのメッセージがこのメッセージに自動的に挿入されます:
# This is a combination of 3 commits. # The first commit's message is: (mingle-fr-2012-69) Adding a custom filter for risky countries. Adding method customFilterFunctionGetRiskyCountryCodeScore() to GatewayAdapter. # This is the 2nd commit message: Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php # This is the 3rd commit message: Fix a typo Change-Id: I33e44ec0d93628d9a53c15e08eb89f352b7d5fe0 # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # Not currently on any branch. # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # modified: donationinterface.php # modified: gateway_common/gateway.adapter.php #
Remember to put your (updated) summary message in the commit. In this case the new summary message will be:
(mingle-fr-2012-69) Adding a custom filter for risky countries.
Change-Id you choose.If all goes well, you should see a successful rebase message:
[detached HEAD 02f5e63] (mingle-fr-2012-69) Adding a custom filter for risky countries. 2 files changed, 92 insertions(+), 3 deletions(-) Successfully rebased and updated refs/heads/mingle-fr-2012-69.
Afterwards, submit your patch for review:
git review
You should see a message like this showing your git review went to Gerrit (in this example, to https://gerrit.wikimedia.org/r/7187):
remote: Resolving deltas: 100% (4/4) remote: (W) 02f5e63: commit message lines >70 characters; manually wrap lines remote: remote: New Changes: remote: https://gerrit.wikimedia.org/r/7187 remote: To ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/DonationInterface.git * [new branch] HEAD -> refs/for/master/mingle-fr-2012-69
Amending a change (your own or someone else's)
Sometimes, you might need to amend a submitted change. You can amend a change as long as the change hasn't been merged yet.
You can amend your own changes. To amend changes submitted by someone else, you need to be a member of Gerrit's Trusted-Contributors group. To become a member of Trusted-Contributors, find someone who is a member and ask them to add you. The group is viral in that members can add new members, use your powers responsibly.
First, checkout the change with this command:
git review -d changeNumber 例: git review -d 1814356
You can look in Gerrit to figure out the changeNumber. It is the number in the URL of your code review page.
次に、好きなテキストエディタで何らかの変更を行います。
git add the files as needed, then commit the change (ensuring you are amending the commit):
git add Example/Example.body.php
git commit --amend
-m flag to specify a commit summary: that will override the previous summary and regenerate the Change-Id.
Instead, use your text editor to change the commit summary (in the file .git/COMMIT_EDITMSG) if needed, and keep the Change-Id line intact.変更をプッシュします：
git review
リベース (パッチを他の変更を含むように更新する)
パッチを更新して、それが提出された後にリポジトリ内で発生したすべての変更を含むようにしたい場合があります。 これを「リベース」と呼びます。 通常、これを行う必要はありませんが、レビューに時間がかかっており、変更がソフトウェアの最新バージョンでも機能するか確認したい場合や、Gerrit が変更にマージ競合を報告している場合には必要です。
ローカルで git rebase コマンドを使用して適切なオプションを指定して実行できますが、Gerrit のウェブ インターフェースを使用する方が便利です。
最も簡単なシナリオでは、「リベース」をクリックし、「master ブランチの上にリベースする」という既定の選択肢を維持し、再度「リベース」をクリックして確認します。
パッチにマージ競合がある場合は、エラーが表示されます。 その後、「競合を許可してリベース」をチェックして再試行できます。これにより、Git コマンドで生成されるのと似た競合マーカーが含まれるパッチが修正されます。 その後、自分で手動でファイルを編集し、競合を解決する必要があります。
また、他のパッチで提案された変更 (そのパッチへの依存を追加) を含めるためにパッチを更新したい場合もありますが、まだマージされていない場合があります。 その場合は、「特定の変更、参照、またはコミットの上にリベース」を選択し、入力フィールドに変更を指定してください。
パッチに既にそのような依存関係がある場合、依存関係を削除するために「master ブランチの上にリベースする (リレーション チェーンを破棄)」オプションも選択できます。 「すべての先祖をリベースする」オプションも選択できます。これにより、パッチとその依存関係が一緒にリベースされます。
git rebase コマンドを使用する場合、リベースの更新は別のパッチとして作成するのが最適です。これにより、コード レビュー担当者は、あなたが行った変更と他のパッチで行われた変更をより簡単に確認できます。
トラブルシューティング
問題とその解決方法については、Gerrit/トラブルシューティングを参照してください。
関連項目
これらのページも有用です：
Third party guides to Git
- Video tutorials how to use Git (on Wikimedia Commons)
- Try Git (interactive demo)
- GitMagic A git guide with translations
- Git Community Book will take you gently into Git internals.
(It is hard to "get" git until knowing something about how it works internally.)
- Git's website with documentation
- Another useful OpenStack Git guide (if you subtract away GitHub stuff)
- Understanding the Git Workflow by Benjamin Sandofsky