[ << Working with source code ] | [Top][Contents][Index][ ? ] | [ Compiling >> ] | ||
[ < Merging branches ] | [ Up : Basic Git procedures ] | [ Understanding commits > ] |
3.3.4 Commits and patches
Understanding commits | ||
Making commits | ||
Commit messages | ||
Making patches | ||
Uploading a patch for review |
[ << Working with source code ] | [Top][Contents][Index][ ? ] | [ Compiling >> ] | ||
[ < Commits and patches ] | [ Up : Commits and patches ] | [ Making commits > ] |
Understanding commits
Technically, a commit is a single point in the history of a branch, but most developers use the term to mean a commit object, which stores information about a particular revision. A single commit can record changes to multiple source files, and typically represents one logical set of related changes (such as a bug-fix). You can list the ten most recent commits in your current branch with this command:
git log -10 --oneline
If you’re using an older version of Git and get an ‘unrecognized argument’ error, use this instead:
git log -10 --pretty=oneline --abbrev-commit
More interactive lists of the commits on the remote master
branch are available at
http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog and
http://git.sv.gnu.org/cgit/lilypond.git/log/.
[ << Working with source code ] | [Top][Contents][Index][ ? ] | [ Compiling >> ] | ||
[ < Understanding commits ] | [ Up : Commits and patches ] | [ Commit messages > ] |
Making commits
Once you have modified some source files in your working directory, you can make a commit with the following procedure:
- Make sure you’ve configured Git properly (see Configuring Git). Check that your changes meet the requirements described in Code style and/or Documentation policy. For advanced edits, you may also want to verify that the changes don’t break the compilation process.
-
Run the following command:
git status
to make sure you’re on the right branch, and to see which files have been modified, added or removed, etc. You may need to tell Git about any files you’ve added by running one of these:
git add file # add untracked file individually git add . # add all untracked files in current directory
After
git add
, rungit status
again to make sure you got everything. You may also need to modify ‘GNUmakefile’. -
Preview the changes about to be committed (to make sure everything
looks right) with:
git diff HEAD
The
HEAD
argument refers to the most recent commit on the currently checked-out branch. -
Generate the commit with:
git commit -a
The ‘-a’ is short for ‘--all’ which includes modified and deleted files, but only those newly created files that have previously been added.
[ << Working with source code ] | [Top][Contents][Index][ ? ] | [ Compiling >> ] | ||
[ < Making commits ] | [ Up : Commits and patches ] | [ Making patches > ] |
Commit messages
When you run the git commit -a
command, Git
automatically opens the default text editor so you can enter a
commit message. If you find yourself in a foreign editing
environment, you’re probably in vi
or vim
. If
you want to switch to an editor you’re more familiar with, quit by
typing :q!
and pressing <Enter>
. See
Configuring Git for instructions on changing the default
editor.
In any case, Git will open a text file for your commit message that looks like this:
# Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # On branch master # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # modified: working.itexi #
Your commit message should begin with a one-line summary describing the change (no more than 50 characters long), and if necessary a blank line followed by several lines giving the details:
Doc: add Baerenreiter and Henle solo cello suites Added comparison of solo cello suite engravings to new essay with high-res images, fixed cropping on Finale example.
Commit messages often start with a short prefix describing the general location of the changes. If a commit affects the documentation in English (or in several languages simultaneously) the commit message should be prefixed with “Doc: ”. If the commit affects only one of the translations, the commit message should be prefixed with “Doc-**: ”, where ** is the two-letter language code. Commits that affect the website should use “Web: ” for English, and “Web-**: ” for the other languages. Also, changes to a single file are often prefixed with the name of the file involved. Visit the links listed in Understanding commits for examples.
[ << Working with source code ] | [Top][Contents][Index][ ? ] | [ Compiling >> ] | ||
[ < Commit messages ] | [ Up : Commits and patches ] | [ Uploading a patch for review > ] |
Making patches
If you want to share your changes with other contributors and developers, you need to generate patches from your commits. We prefer it if you follow the instructions in Uploading a patch for review. However, we present an alternate method here.
You should always run git pull -r
(translators
should leave off the ‘-r’) before doing this to ensure that
your patches are as current as possible.
Once you have made one or more commits in your local repository, and pulled the most recent commits from the remote branch, you can generate patches from your local commits with the command:
git format-patch origin
The origin
argument refers to the remote tracking branch at
git.sv.gnu.org
. This command generates a separate patch
for each commit that’s in the current branch but not in the remote
branch. Patches are placed in the current working directory and
will have names that look something like this:
0001-Doc-Fix-typos.patch 0002-Web-Remove-dead-links.patch ⋮
Send an email (must be less than 64 KB) to lilypond-devel@gnu.org briefly explaining your work, with the patch files attached. Translators should send patches to translations@lilynet.net. After your patches are reviewed, the developers may push one or more of them to the main repository or discuss them with you.
[ << Working with source code ] | [Top][Contents][Index][ ? ] | [ Compiling >> ] | ||
[ < Making patches ] | [ Up : Commits and patches ] | [ Advanced Git procedures > ] |
Uploading a patch for review
Any non-trivial change should be uploaded to our “Rietveld” code review website:
http://codereview.appspot.com/
git-cl
install
LilyDev users should skip over these ‘install’ instructions.
-
Install
git-cl
by entering:git clone https://github.com/gperciva/git-cl.git
If that command fails for some reason, try this instead:
git clone git://github.com/gperciva/git-cl.git
-
Add the ‘git-cl/’ directory to your PATH,
or create a symbolic link to the
git-cl
andupload.py
scripts in one of your PATH directories (such as ‘$HOME/bin’).In Ubuntu (and LilyDev), you can add directories to PATH by adding this line to a hidden file ‘.bashrc’, located in your home directory:
PATH=~/type-here-directory-containing-git-cl:"${PATH}"
git-cl
configuration
LilyDev users should perform these ‘configuration’ instructions.
-
You must have a google account; please create one if you do not
have one already.
Note that a google account does not need to be a gmail account; you can use any email address for your google account when you sign up.
-
Move into the top source directory and then configure
git cl
with the following commands:cd $LILYPOND_GIT git cl config
For the “Rietveld server” question, the default value (“codereview.appspot.com”) should be accepted by answering with a newline (CR).
The “CC list” question should be answered with:
lilypond-devel@gnu.org
The “Tree status URL” value should be left blank. So should the “ViewVC URL” value, since it is used by
git cl dcommit
which is only for repositories which usegit svn
(LilyPond doesn’t).
Uploading patch set
Note: Unless you are familiar with branches, only work on one set of changes at once.
There are two methods, depending on your git setup.
-
Master branch: (easy option, and used in
lily-git.tcl
)If you added your patch to
master
, then:git pull -r git cl upload origin/master
If you have git push ability, make sure that you remove your patch (with
git rebase
orgit reset
) before pushing other stuff.Notifications of patches are automatically added to our issue tracker to reduce the chance of patches getting lost. To suppress this (not recommended), add the
-n / --no-code-issue
option. -
Separate branch: (complicated option)
Ensure your changes are committed in a separate branch, which should differ from the reference branch to be used by just the changes to be uploaded. If the reference branch is to be origin/master, ensure this is up-to-date. If necessary, use git rebase to rebase the branch containing the changes to the head of origin/master. Finally, check out branch with the changes and enter the command:
git cl upload <reference SHA1 ID>
where <reference SHA1 ID> is the SHA1 ID of the commit to be used as a reference source for the patch. Generally, this will be the SHA1 ID of origin/master, and in that case the command:
git cl upload origin/master
can be used.
First you will see a terminal editor where you can edit the
message that will accompany your patch. git-cl
will
respect the EDITOR
environment variable if defined,
otherwise it will use vi
as the default editor.
After prompting for your Google email address and password, the patch set will be posted to Rietveld, and you will be given a URL for your patch.
Note: Some installations of git-cl fail when uploading a patch with certain filename extensions. If this happens, it can generally be fixed by editing the list of exceptions at top of ‘git-cl.py’.
Announcing your patch set
You should then announce the patch by logging into the code review issue webpage and using “Publish + Mail Comments” to add a (mostly bogus) comment to your issue. The text of your comment will be sent to our developer mailing list.
Note: There is no automatic notification of a new patch; you must add a comment yourself.
Revisions
As revisions are made in response to comments, successive patch sets for the same issue can be uploaded by reissuing the git-cl command with the modified branch checked out.
Sometimes in response to comments on revisions, the best way to work may require creation of a new branch in git. In order to associate the new branch with an existing Rietveld issue, the following command can be used:
git cl issue issue-number
where issue-number
is the number of the existing Rietveld
issue.
Resetting git cl
If git cl
becomes confused, you can “reset” it by
running:
git cl issue 0
Wait for a countdown
Your patch will be available for reviews for the next few hours or
days. Three times a week, patches with no known problems are
gathered into a “patch countdown” and their status changed to
patch-countdown
. The countdown is a 48-hour waiting period
in which any final reviews or complaints should be made.
During the countdown, your patch may be set to
patch-needs_work
, indicating that you should fix something
(or at least discuss why the patch needs no modification). If no
problems are found, the patch will be set to patch-push
.
Once a patch has patch-push
, it should be sent to your
mentor for uploading. If you have git push ability, look at
Pushing to staging.
[ << Working with source code ] | [Top][Contents][Index][ ? ] | [ Compiling >> ] | ||
[ < Making patches ] | [ Up : Commits and patches ] | [ Advanced Git procedures > ] |