Git: Difference between revisions
(Random fixes.) |
|||
| Line 1: | Line 1: | ||
= Gerrit = | = Gerrit = | ||
As part of our move to gerrit, git was introduced as primary SCM. | As part of our move to [https://code.google.com/p/gerrit/ gerrit], [http://gitscm.com/ git] was introduced as primary SCM. | ||
== Register with gerrit == | == Register with gerrit == | ||
For authenticated access (to submit patches) you'll need a gerrit account which you can register at http://review.coreboot.org/. | For authenticated access (to submit patches) you'll need a gerrit account which you can register at http://review.coreboot.org/. | ||
You also need to add your ssh key(s) (used for authenticating your connections to the repo) and your email address(es) (used to match up Signed-off-by: statements) to your gerrit user data at http://review.coreboot.org/#settings | You also need to add your ssh key(s) (used for authenticating your connections to the repo) and your email address(es) (used to match up Signed-off-by: statements) to your gerrit user data at http://review.coreboot.org/#settings. | ||
=== OpenID === | === OpenID === | ||
| Line 10: | Line 10: | ||
== Gerrit workflow == | == Gerrit workflow == | ||
Gerrit interprets each Git commit as an individual change. Changes are autobuilt by Jenkins, and can be reviewed by developers. Once a change has gotten a positive review and | Gerrit interprets each Git commit as an individual change. Changes are autobuilt by [http://jenkins-ci.org/ Jenkins], and can be reviewed by developers. Once a change has gotten a positive review and has no build issues, it is applied to the master branch. Thus, no developer directly pushes to master. | ||
Reviews grant points on a scale from -2 to 2. The meaning is: | Reviews grant points on a scale from -2 to 2. The meaning is: | ||
| Line 37: | Line 37: | ||
= Anonymous read access = | = Anonymous read access = | ||
Read-only access is available anonymously: | Read-only access is available anonymously: | ||
git clone http://review.coreboot.org/p/coreboot | git clone <nowiki>http://review.coreboot.org/p/coreboot</nowiki> | ||
= Authenticated read/write access = | = Authenticated read/write access = | ||
| Line 53: | Line 53: | ||
Git does not enforce a commit message style, although perhaps it should. For all aspects of Git to work the best, it's important to follow these simple guidelines for commit messages: | Git does not enforce a commit message style, although perhaps it should. For all aspects of Git to work the best, it's important to follow these simple guidelines for commit messages: | ||
# The first line of the commit message has a short (less than 65 characters, | # The first line of the commit message has a short (less than 65 characters, absolute maximum is 75) summary | ||
# The second line is empty (no whitespace at all) | # The second line is empty (no whitespace at all) | ||
# The third and any number of following lines contain a longer description of the commit as is neccessary, including relevant background information and quite possibly rationale for why the issue was solved in this particular way. These lines should never be longer than 75 characters. | # The third and any number of following lines contain a longer description of the commit as is neccessary, including relevant background information and quite possibly rationale for why the issue was solved in this particular way. These lines should never be longer than 75 characters. | ||
| Line 60: | Line 60: | ||
# A Signed-off-by: line according to [[Development_Guidelines#Sign-off_Procedure|the development guidelines]] | # A Signed-off-by: line according to [[Development_Guidelines#Sign-off_Procedure|the development guidelines]] | ||
Please do not create Change-Id: and Signed-off-by: manually because it is boring and error-prone. Instead, please install the commit-msg hook as described [[#Authenticated_read/write_access|above]] or by running | Please do not create Change-Id: and Signed-off-by: manually because it is boring and error-prone. Instead, please install the commit-msg hook as described [[#Authenticated_read/write_access|above]] or by running... | ||
make gitconfig | make gitconfig | ||
..and remember to always use git commit -s to have git add your Signed-off-by: automatically. | ...and remember to always use '''git commit -s''' to have git add your Signed-off-by: automatically. | ||
Here is an example of a well-formatted commit message: | Here is an example of a well-formatted commit message: | ||
examplecomponent: Refactor duplicated setup into a function | examplecomponent: Refactor duplicated setup into a function. | ||
Setting up the demo device correctly requires the exact same register | Setting up the demo device correctly requires the exact same register | ||
| Line 77: | Line 78: | ||
== Pushing changes == | == Pushing changes == | ||
First ensure that the git remote you want to use for pushing refers to an ssh:// URL (see Authenticated read/write access above). If you need to change this after the fact, ie. if you registered on gerrit only after having cloned anonymously, you can. Assuming that your remote is called ''origin'' (this is the default) you can run: | First ensure that the git remote you want to use for pushing refers to an ssh:// URL (see [[#Authenticated read/write access]] above). If you need to change this after the fact, ie. if you registered on gerrit only after having cloned anonymously, you can. Assuming that your remote is called ''origin'' (this is the default) you can run: | ||
git config remote.origin.url ssh://<username>@review.coreboot.org:29418/coreboot | git config remote.origin.url ssh://<username>@review.coreboot.org:29418/coreboot | ||
Then run the following command once, to tell git that by default you want to submit all commits in the currently checked-out branch for review on gerrit: | Then run the following command once, to tell git that by default you want to submit all commits in the currently checked-out branch for review on gerrit: | ||
git config remote.origin.push HEAD:refs/for/master | git config remote.origin.push HEAD:refs/for/master | ||
After this, the command to push your changes is: | After this, the command to push your changes is: | ||
git push origin | git push origin | ||
If you always push from the same or a few branches the workflow can be simplified further by running once for each branch: | If you always push from the same or a few branches the workflow can be simplified further by running once for each branch: | ||
git config branch.<particularbranchname>.remote origin | git config branch.<particularbranchname>.remote origin | ||
...after which you then push changes with any of the configured branches checked out with a simple: | ...after which you then push changes with any of the configured branches checked out with a simple: | ||
git push | git push | ||
| Line 95: | Line 101: | ||
'''NB!''' If you have applied patches from gerrit on a branch and you later push that branch, gerrit will think that you are submitting new versions of the patches that you had applied. This may or may not be what you intend. You can always run | '''NB!''' If you have applied patches from gerrit on a branch and you later push that branch, gerrit will think that you are submitting new versions of the patches that you had applied. This may or may not be what you intend. You can always run | ||
git log origin/master.. | git log origin/master.. | ||
For automating patch submission further (ie. more ways of simplifying the command line), see the last paragraph of http://review.coreboot.org/Documentation/user-upload.html#push_create | before '''git push''' to verify which commits you are about to send for review. | ||
For automating patch submission further (ie. more ways of simplifying the command line), see the last paragraph of [http://review.coreboot.org/Documentation/user-upload.html#push_create this gerrit documentation]. | |||
== Further Git reading == | == Further Git reading == | ||
There are tons of git tutorials out there. Take a look at http://git-scm.com/ | There are tons of git tutorials out there. Take a look at some of these documents: | ||
* http://git-scm.com/ | |||
* http://www.kernel.org/pub/software/scm/git/docs/v1.7.5.4/gittutorial.html | |||
* http://git.or.cz/course/svn.html | |||
* and in particular the [http://progit.org/ Pro Git book] | |||
Please also feel free to ask Git questions in the coreboot IRC channel or on the mailing list. | Please also feel free to ask Git questions in the [[IRC|coreboot IRC channel]] or on the [[Mailinglist|mailing list]]. | ||
= Browsing = | = Browsing = | ||
Revision as of 17:43, 9 June 2011
Gerrit
As part of our move to gerrit, git was introduced as primary SCM.
Register with gerrit
For authenticated access (to submit patches) you'll need a gerrit account which you can register at http://review.coreboot.org/. You also need to add your ssh key(s) (used for authenticating your connections to the repo) and your email address(es) (used to match up Signed-off-by: statements) to your gerrit user data at http://review.coreboot.org/#settings.
OpenID
It seems that gerrit is picky about the OpenID format. Always provide a full URL, including protocol (ie. http:// or https:// prefix). Unfortunately the error messages are non-intuitive.
Gerrit workflow
Gerrit interprets each Git commit as an individual change. Changes are autobuilt by Jenkins, and can be reviewed by developers. Once a change has gotten a positive review and has no build issues, it is applied to the master branch. Thus, no developer directly pushes to master.
Reviews grant points on a scale from -2 to 2. The meaning is:
- -2: Do not merge (blocks gerrit from merging)
- -1: I'd prefer you don't merge it
- 0: neutral
- +1: Looks good, but I won't make the last call on it
- +2: Looks good, go ahead and merge (gerrit provides a "submit" function once it has a +2 vote)
-2 and +2 are only available to core developers as it's comparable to commit rights in SVN.
Gerrit and CLI
Reviews normally happens through the website.
Since gerrit exposes an interface through its ssh daemon, it's also possible to do reviews from CLI or mail. Unfortunately there doesn't seem to be any standing tradition on how to build a workflow around these parts, so we'll document our best practices here once they settled.
Gerrit and Email
Gerrit has poor email integration (in fact, it doesn't really have any at all). We send a couple of notifications to the mailing list, but that is a coreboot specific extension. Peter intends to build a mail-to-gerrit gateway should the need arise.
This gateway will provide:
- no patch submission mechanism ("git push" is CLI friendly)
- patch review (maybe openpgp signed "Acked-by" mails)
- patch submission (automatically with Acked-by?)
- maybe patch rejection? (openpgp signed "Nacked-by" mails)
Anonymous read access
Read-only access is available anonymously:
git clone http://review.coreboot.org/p/coreboot
Authenticated read/write access
git clone ssh://<username>@review.coreboot.org:29418/coreboot
Inside the checkout you should install the commit-msg hook which prepares commit messages to fit the style required by gerrit. This needs to happen only once per clone and can be done with
wget -O .git/hooks/commit-msg http://review.coreboot.org/tools/hooks/commit-msg && \ chmod +x .git/hooks/commit-msg
Working with Git
Git is a distributed version control system. This means that you can manage commits and branches completely without restriction in your local clone of the coreboot repository. Peter wrote a Git introduction after the switch to Git had been announced on the mailing list.
Commit messages
Git does not enforce a commit message style, although perhaps it should. For all aspects of Git to work the best, it's important to follow these simple guidelines for commit messages:
- The first line of the commit message has a short (less than 65 characters, absolute maximum is 75) summary
- The second line is empty (no whitespace at all)
- The third and any number of following lines contain a longer description of the commit as is neccessary, including relevant background information and quite possibly rationale for why the issue was solved in this particular way. These lines should never be longer than 75 characters.
- The next line is empty (no whitespace at all)
- A Change-Id: line to let gerrit track this logical change
- A Signed-off-by: line according to the development guidelines
Please do not create Change-Id: and Signed-off-by: manually because it is boring and error-prone. Instead, please install the commit-msg hook as described above or by running...
make gitconfig
...and remember to always use git commit -s to have git add your Signed-off-by: automatically.
Here is an example of a well-formatted commit message:
examplecomponent: Refactor duplicated setup into a function. Setting up the demo device correctly requires the exact same register values to be written into each of the PCI device functions. Moving the writes into a function allows also otherexamplecomponent to use them. Signed-off-by: Joe Hacker <joe@hacker.email>
The example is missing a Change-Id: line. This is OK because Joe Hacker has set up the commit-msg hook as mentioned above, which adds a Change-Id: automatically when the commit message is saved.
Pushing changes
First ensure that the git remote you want to use for pushing refers to an ssh:// URL (see #Authenticated read/write access above). If you need to change this after the fact, ie. if you registered on gerrit only after having cloned anonymously, you can. Assuming that your remote is called origin (this is the default) you can run:
git config remote.origin.url ssh://<username>@review.coreboot.org:29418/coreboot
Then run the following command once, to tell git that by default you want to submit all commits in the currently checked-out branch for review on gerrit:
git config remote.origin.push HEAD:refs/for/master
After this, the command to push your changes is:
git push origin
If you always push from the same or a few branches the workflow can be simplified further by running once for each branch:
git config branch.<particularbranchname>.remote origin
...after which you then push changes with any of the configured branches checked out with a simple:
git push
Pushing several commits not yet in the coreboot repository at once will create one review request on gerrit per commit.
NB! If you have applied patches from gerrit on a branch and you later push that branch, gerrit will think that you are submitting new versions of the patches that you had applied. This may or may not be what you intend. You can always run
git log origin/master..
before git push to verify which commits you are about to send for review.
For automating patch submission further (ie. more ways of simplifying the command line), see the last paragraph of this gerrit documentation.
Further Git reading
There are tons of git tutorials out there. Take a look at some of these documents:
- http://git-scm.com/
- http://www.kernel.org/pub/software/scm/git/docs/v1.7.5.4/gittutorial.html
- http://git.or.cz/course/svn.html
- and in particular the Pro Git book
Please also feel free to ask Git questions in the coreboot IRC channel or on the mailing list.
Browsing
There is no code browser that's properly synced with our gerrit instance at this time. This is a work in progress.