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を自分自身の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接続成功メッセージの例はこのようになります：
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.
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 -R
The -R option tells git-review not to perform a rebase before submitting the change to Gerrit.
gerrituser@machine:/mw/sandbox$ git review -R 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 -R fails
If you are asked to enter your username and password credentials when running git review -R, 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.
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:
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. #
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:
# 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.
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.
Rebasing
Rebase to bring your local branch up to date with the remote. It's best to make rebase updates a separate patch, so that your code reviewers have an easy time seeing what changes you've made. Assuming you are using Gerrit, you can do this by clicking the "Rebase Change" button when viewing your patch in Gerrit's web interface.
Hard reset and checkout the change with this command:
(BEWARE: git review -d performs a hard reset that destroys all local changes. Stash or commit changes first which you wish to preserve!)
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
Make changes and push
次に、好きなテキストエディタで何らかの変更を行います。
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 -R
ここでは-Rが重要です。
It tells git-review to not rebase your change against master, which clutters diffs between patch set 1 and 2.
master以外のブランチにプッシュする
上記では、コミットはmasterブランチにプッシュされていました。
The branch name only appeared as the topic of the commit in the Gerrit UI.
もし本当にmasterとは異なるブランチにプッシュしたいのであれば、git review <branch name>でプッシュする必要があります。
トラブルシューティング
問題とその解決方法については、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