Gerrit/チュートリアル

This page is a translated version of the page Gerrit/Tutorial and the translation is 52% complete.
Outdated translations are marked like this.
コマンドラインとGitの経験がある場合は、代わりに短いハウツーガイド を利用してください。

このチュートリアルは、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の挙動を制御している現状の設定変数を見るには、git config -lを使用してください。

さてGitがインストールされて、個人情報を設定する時間です。 1回だけはこれを行う必要があります。 これらのコマンドを再度実行することによって、いつでも個人情報を変更することもできます。

Gitは利用者の名前とメールをチェックすることによって、各々のコミットを誰が行ったのか追跡します。 さらに、この情報はあなたのコミットをあなたのGerritアカウントと関連付けるために使われます。

以下の2つのコマンドを入力して、あなたの利用者名とメールアドレスを設定してください。 Gerrituserを自分自身のGerrit利用者名で置き換え、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接続成功メッセージの例はこのようになります:

Example:

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/git-review

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

  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

出力の最後の方に、このようなものが表示されるはずです:

Example:

使用しているシェルのユーザー名と異なる場合、これはgitのユーザー名を尋ねるかもしれません。

If you could not install 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

Example:

This will create a new branch (called BRANCHNAME) from the latest 'master' and check it out for you. 上記の例では、新しいブランチをcleanup-somethingと呼びます。

変更を行う

ローカルのコードに変更を行います。 好きなテキストエディタを使ってファイルを修正してください。 以下の例では、ファイルREADME.mdを編集して単語を追加しています。

それからテキストエディタを閉じて、ファイルやディレクトリの中で、最後のコミット以降にあなたが行った変更をチェックしてください:

git diff

Example:

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" (コミットに変更が追加されていません)という行を表示しません。
You can also use git diff --cached to see which changes are staged and will go into the next commit. 出力は上記のgit diffコマンドと同じように見えます。

ステージした変更をコミットする

git add によって追加した変更の一覧に満足したら、以下を使用することでこれらの変更をローカル リポジトリにコミットすることができます

git commit

sandbox/.git/COMMIT_EDITMSG:

その後テキストエディタであなたのコミットに対する説明的な要約を追加するように求められます。 コミット メッセージの指針に従わなければなりません。 これはコードリポジトリの変更履歴を見るときに、他の人たちが参照するものです。

コミットメッセージを保存してテキストエディタを閉じてください。 A summary (the commit ID, your subject line, the files and lines changed) will be displayed.

You can repeat this step over and over until you have a set of changes that you want to have pushed to the master branch.

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

Example:
git pull --rebase origin master will fetch new commits from the remote and then rebase your local commits on top of them.

It will temporarily set aside the changes you've made in your branch, apply all of the changes that have happened in master to your working branch, then merge (recommit) all of the changes you've made back into the branch. 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

Example:

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

If you are asked to enter your username and password credentials when running git review, it means Git has not yet been configured to use 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.

If you get a Permission denied (publickey). fatal: Could not read from remote repository., review the instructions at SSHキー to make sure your ssh agent is running and your identity is added. If you close your Git Bash shell, you will be signed out and need to re-follow these instructions each time.

View the Change / Next Steps

Open the link to your Gerrit changeset in a web browser.

Under "Files", after you clicked the down arrow at the very right of any file in the list, you can see a diff of your changes per file: The old lines are shown in red color and your new lines are shown in green color.

Gerrit's diff algorithm (jGit) is slightly different from git's default diff algorithm. The differences displayed by Gerrit might not look like the differences displayed by Git on your machine.

If your commit addresses a ticket in Phabricator, a comment will be automatically added in the Phabricator task if you followed the Commit message guidelines. If you did not, you could either fix your commit message (by creating an updated patchset), or manually add a comment on that Phabricator ticket which includes a link to your changeset in Gerrit.

その他のよくある状況

もしあなたの状況がここで取り扱われていなければ、Gerritの高度な使用法も参照してください。

Squash several commits into one single commit via rebase

If you made several related commits to your local repository prior to wanting to submit for review, you should squash (merge) those commits into one single commit.

The --interactive or -i option allows you to change (rewrite) your commit history. For each commit, you can modify and change the commit message, add or remove files, or perform other modifications.

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

After you type this command, your text editor will display your commits in reverse order and a list of available commands:

Example:

Since we only want to send one commit to review, we will squash the last two commits into the first. 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

When you finished picking and squashing and saved the file, another file will open in your text editor to allow you get to edit and merge your commit messages. Be careful to only keep one of the Change-Id lines and have it be at bottom of the message after one empty line.

Your messages from your previous commits will automatically be placed in this message:

Example:

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.
In regards to which Change-Id you want to use, squashing a commit into an existing commit (one that's already in Gerrit), you need to pick the Change-Id that belongs to the one you meant to submit a new patchset for (the surviving commit). If your commits are new and are not in Gerrit, it does not matter which Change-Id you choose.

If all goes well, you should see a successful rebase message:

Example:

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):

Example:

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 814356

You can look in Gerrit to figure out the changeNumber. It is the six digit number in the URL of your code review page.

Or, if you already have the change in a branch on your local repository, you can just check it out:

git checkout BRANCHNAME 例: git checkout review/gerrituser/2012/bug12345

次に、好きなテキストエディタで何らかの変更を行います。

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

DO NOT use the -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

Rebasing (updating the patch to include other changes)

Sometimes you might want to update your patch to include all of the changes in the repository that have happened since you submitted it. This is called "rebasing". There's usually no need to do it, unless the review has been taking a long time and you want to make sure your changes still work with the latest version of the software, or if Gerrit reports a merge conflict in your change.

You can do it locally using the git rebase command with the right options, but Gerrit's web interface provides a more convenient way to do it.

In the simplest scenario, just click "Rebase", keep the default selection of "Rebase on top of the master branch", and click "Rebase" again to confirm.

If your patch has a merge conflict, you will get an error. You can then check the "Allow rebase with conflicts" option and try again, which will amend your patch with conflict markers, similar to those generated by Git commands. You will then need to amend it yourself, editing the files manually to resolve the conflicts.

Sometimes you might also want update your patch to include changes proposed in another patch (adding a dependency on that patch), but which have not been merged yet. In this case, select "Rebase on a specific change, ref, or commit" instead and provide the change in the input field.

If your patch already has such a dependency, you will also get the option to select "Rebase on top of the master branch (breaks relation chain)" in order to remove it. You will also get the option to check "Rebase all ancestors", which will rebase the patch together with the dependency.

If you use the git rebase command, it's best to make rebase updates a separate patch, so that your code reviewers have an easier time seeing what changes you've made and which changes have happened in other patches.

トラブルシューティング

問題とその解決方法については、Gerrit/トラブルシューティング を参照してください。

関連項目

これらのページも有用です:

Third party guides to Git

(It is hard to "get" git until knowing something about how it works internally.)

脚注