|o||Which commit caused this example code to break?|
|o||Which commit caused this example code to start working?|
|o||Which commit added the first file to match this regex?|
|o||Which commit removed the last file to match this regex?|
If you require more flexibility than Porting/bisect.pl has to offer, youll need to run git bisect yourself. Its most useful to use git bisect run to automate the building and testing of perl revisions. For this youll need a shell script for git to call to test a particular revision. An example script is Porting/bisect-example.sh, which you should copy <B>outsideB> of the repository, as the bisect process will reset the state to a clean checkout as it runs. The instructions below assume that you copied it as ~/run and then edited it as appropriate.
You first enter in bisect mode with:
% git bisect start
% git bisect bad
% git bisect good perl-5.10.0
Bisecting: 853 revisions left to test after this
This results in checking out the median commit between HEAD and perl-5.10.0. You can then run the bisecting process with:
% git bisect run ~/run
When the first bad commit is isolated, git bisect will tell you so:
ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
Author: Dave Mitchell <email@example.com>
Date: Sat Feb 9 14:56:23 2008 +0000
[perl #49472] Attributes + Unknown Error
bisect run success
You can peek into the bisecting process with git bisect log and git bisect visualize. git bisect reset will get you out of bisect mode.
Please note that the first good state must be an ancestor of the first bad state. If you want to search for the commit that solved some bug, you have to negate your test case (i.e. exit with 1 if OK and 0 if not) and still mark the lower bound as good and the upper as bad. The first bad commit has then to be understood as the first commit where the bug is solved.
git help bisect has much more information on how you can tweak your binary searches.
Individual committers should create topic branches under <B>yournameB>/<B>some_descriptive_nameB>. Other committers should check with a topic branchs creator before making any change to it.
The simplest way to create a remote topic branch that works on all versions of git is to push the current head as a new branch on the remote, then check it out locally:
$ branch="$yourname/$some_descriptive_name" $ git push origin HEAD:$branch $ git checkout -b $branch origin/$branch
Users of git 1.7 or newer can do it in a more obvious manner:
$ branch="$yourname/$some_descriptive_name" $ git checkout -b $branch $ git push origin -u $branch
If you are not the creator of <B>yournameB>/<B>some_descriptive_nameB>, you might sometimes find that the original author has edited the branchs history. There are lots of good reasons for this. Sometimes, an author might simply be rebasing the branch onto a newer source point. Sometimes, an author might have found an error in an early commit which they wanted to fix before merging the branch to blead.
Currently the master repository is configured to forbid non-fast-forward merges. This means that the branches within can not be rebased and pushed as a single step.
The only way you will ever be allowed to rebase or modify the history of a pushed branch is to delete it and push it as a new branch under the same name. Please think carefully about doing this. It may be better to sequentially rename your branches so that it is easier for others working with you to cherry-pick their local changes onto the new version. (XXX: needs explanation).
If you want to rebase a personal topic branch, you will have to delete your existing topic branch and push as a new version of it. You can do this via the following formula (see the explanation about refspecs in the git push documentation for details) after you have rebased your branch:
# first rebase $ git checkout $user/$topic $ git fetch $ git rebase origin/blead # then "delete-and-push" $ git push origin :$user/$topic $ git push origin $user/$topic
<B>NOTE:B> it is forbidden at the repository level to delete any of the primary branches. That is any branch matching m!^(blead|maint|perl)!. Any attempt to do so will result in git producing an error like this:
$ git push origin :blead *** It is forbidden to delete blead/maint branches in this repository error: hooks/update exited with error code 1 error: hook declined to update refs/heads/blead To ssh://perl5.git.perl.org/perl ! [remote rejected] blead (hook declined) error: failed to push some refs to ssh://perl5.git.perl.org/perl
As a matter of policy we do <B>notB> edit the history of the blead and maint-* branches. If a typo (or worse) sneaks into a commit to blead or maint-*, well fix it in another commit. The only types of updates allowed on these branches are fast-forwards, where all history is preserved.
Annotated tags in the canonical perl.git repository will never be deleted or modified. Think long and hard about whether you want to push a local tag to perl.git before doing so. (Pushing unannotated tags is not allowed.)
The perl history contains one mistake which was not caught in the conversion: a merge was recorded in the history between blead and maint-5.10 where no merge actually occurred. Due to the nature of git, this is now impossible to fix in the public repository. You can remove this mis-merge locally by adding the following line to your .git/info/grafts file:
It is particularly important to have this graft line if any bisecting is done in the area of the merge in question.
Once you have write access, you will need to modify the URL for the origin remote to enable pushing. Edit .git/config with the git-config(1) command:
% git config remote.origin.url ssh://perl5.git.perl.org/perl.git
You can also set up your user name and e-mail address. Most people do this once globally in their ~/.gitconfig by doing something like:
% git config --global user.name "AEvar Arnfjoerd` Bjarmason" % git config --global user.email firstname.lastname@example.org
However, if youd like to override that just for perl, execute something like the following in perl:
% git config user.email email@example.com
It is also possible to keep origin as a git remote, and add a new remote for ssh access:
% git remote add camel perl5.git.perl.org:/perl.git
This allows you to update your local repository by pulling from origin, which is faster and doesnt require you to authenticate, and to push your changes back with the camel remote:
% git fetch camel % git push camel
The fetch command just updates the camel refs, as the objects themselves should have been fetched when pulling from origin.
If you have received a patch file generated using the above section, you should try out the patch.
First we need to create a temporary new branch for these changes and switch into it:
% git checkout -b experimental
Patches that were formatted by git format-patch are applied with git am:
% git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch Applying Rename Leon Brocard to Orange Brocard
If just a raw diff is provided, it is also possible use this two-step process:
% git apply bugfix.diff % git commit -a -m "Some fixing" --author="That Guy <firstname.lastname@example.org>"
Now we can inspect the change:
% git show HEAD commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 Author: Leon Brocard <email@example.com> Date: Fri Dec 19 17:02:59 2008 +0000 Rename Leon Brocard to Orange Brocard diff --git a/AUTHORS b/AUTHORS index 293dd70..722c93e 100644 --- a/AUTHORS +++ b/AUTHORS @@ -541,7 +541,7 @@ Lars Hecking <firstname.lastname@example.org> Laszlo Molnar <email@example.com> Leif Huhn <firstname.lastname@example.org> Len Johnson <email@example.com> -Leon Brocard <firstname.lastname@example.org> +Orange Brocard <email@example.com> Les Peters <firstname.lastname@example.org> Lesley Binks <email@example.com> Lincoln D. Stein <firstname.lastname@example.org>
If you are a committer to Perl and you think the patch is good, you can then merge it into blead then push it out to the main repository:
% git checkout blead % git merge experimental % git push origin blead
If you want to delete your temporary branch, you may do so with:
% git checkout blead % git branch -d experimental error: The branch experimental is not an ancestor of your current HEAD. If you are sure you want to delete it, run git branch -D experimental. % git branch -D experimental Deleted branch experimental.
The blead branch will become the next production release of Perl.
Before pushing any local change to blead, its incredibly important that you do a few things, lest other committers come after you with pitchforks and torches:
o Make sure you have a good commit message. See Commit message in perlhack for details. o Run the test suite. You might not think that one typo fix would break a test file. Youd be wrong. Heres an example of where not running the suite caused problems. A patch was submitted that added a couple of tests to an existing .t. It couldnt possibly affect anything else, so no need to test beyond the single affected .t, right? But, the submitters email address had changed since the last of their submissions, and this caused other tests to fail. Running the test target given in the next item would have caught this problem. o If you dont run the full test suite, at least make test_porting. This will run basic sanity checks. To see which sanity checks, have a look in t/porting. o If you make any changes that affect miniperl or core routines that have different code paths for miniperl, be sure to run make minitest. This will catch problems that even the full test suite will not catch because it runs a subset of tests under miniperl rather than perl.
Simple, one-off commits pushed to the blead branch should be simple commits that apply cleanly. In other words, you should make sure your work is committed against the current position of blead, so that you can push back to the master repository without merging.
Sometimes, blead will move while youre building or testing your changes. When this happens, your push will be rejected with a message like this:
To ssh://perl5.git.perl.org/perl.git ! [rejected] blead -> blead (non-fast-forward) error: failed to push some refs to ssh://perl5.git.perl.org/perl.git To prevent you from losing history, non-fast-forward updates were rejected Merge the remote changes (e.g. git pull) before pushing again. See the Note about fast-forwards section of git push --help for details.
When this happens, you can just rebase your work against the new position of blead, like this (assuming your remote for the master repository is p5p):
$ git fetch p5p $ git rebase p5p/blead
You will see your commits being re-applied, and you will then be able to push safely. More information about rebasing can be found in the documentation for the git-rebase(1) command.
For larger sets of commits that only make sense together, or that would benefit from a summary of the sets purpose, you should use a merge commit. You should perform your work on a topic branch, which you should regularly rebase against blead to ensure that your code is not broken by blead moving. When you have finished your work, please perform a final rebase and test. Linear history is something that gets lost with every commit on blead, but a final rebase makes the history linear again, making it easier for future maintainers to see what has happened. Rebase as follows (assuming your work was on the branch committer/somework):
$ git checkout committer/somework $ git rebase blead
Then you can merge it into master like this:
$ git checkout blead $ git merge --no-ff --no-commit committer/somework $ git commit -a
The switches above deserve explanation. --no-ff indicates that even if all your work can be applied linearly against blead, a merge commit should still be prepared. This ensures that all your work will be shown as a side branch, with all its commits merged into the mainstream blead by the merge commit.
--no-commit means that the merge commit will be prepared but not committed. The commit is then actually performed when you run the next command, which will bring up your editor to describe the commit. Without --no-commit, the commit would be made with nearly no useful message, which would greatly diminish the value of the merge commit as a placeholder for the works description.
When describing the merge commit, explain the purpose of the branch, and keep in mind that this description will probably be used by the eventual release engineer when reviewing the next perldelta document.
Maintenance versions should only be altered to add critical bug fixes, see perlpolicy.
To commit to a maintenance version of perl, you need to create a local tracking branch:
% git checkout --track -b maint-5.005 origin/maint-5.005
This creates a local branch named maint-5.005, which tracks the remote branch origin/maint-5.005. Then you can pull, commit, merge and push as before.
You can also cherry-pick commits from blead and another branch, by using the git cherry-pick command. It is recommended to use the <B>-xB> option to git cherry-pick in order to record the SHA1 of the original commit in the new commit message.
Before pushing any change to a maint version, make sure youve satisfied the steps in Committing to blead above.
While we dont encourage the submission of patches via GitHub, that will still happen. Here is a guide to merging patches from a GitHub repository.
% git remote add avar git://github.com/avar/perl.git % git fetch avar
Now you can see the differences between the branch and blead:
% git diff avar/orange
And you can see the commits:
% git log avar/orange
If you approve of a specific commit, you can cherry pick it:
% git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae
Or you could just merge the whole branch if you like it all:
% git merge avar/orange
And then push back to the repository:
% git push origin blead
Sometimes a change affects code paths which you cannot test on the OSes which are directly available to you and it would be wise to have users on other OSes test the change before you commit it to blead.
Fortunately, there is a way to get your change smoke-tested on various OSes: push it to a smoke-me branch and wait for certain automated smoke-testers to report the results from their OSes.
The procedure for doing this is roughly as follows (using the example of of tonycs smoke-me branch called win32stat):
First, make a local branch and switch to it:
% git checkout -b win32stat
Make some changes, build perl and test your changes, then commit them to your local branch. Then push your local branch to a remote smoke-me branch:
% git push origin win32stat:smoke-me/tonyc/win32stat
Now you can switch back to blead locally:
% git checkout blead
If all is well then update your blead branch:
% git pull
then checkout your smoke-me branch once more and rebase it on blead:
% git rebase blead win32stat
Now switch back to blead and merge your smoke-me branch into it:
% git checkout blead % git merge win32stat
As described earlier, if there are many changes on your smoke-me branch then you should prepare a merge commit in which to give an overview of those changes by using the following command instead of the last command above:
% git merge win32stat --no-ff --no-commit
You should now build perl and test your (merged) changes one last time (ideally run the whole test suite, but failing that at least run the t/porting/*.t tests) before pushing your changes as usual:
% git push origin blead
Finally, you should then delete the remote smoke-me branch:
% git push origin :smoke-me/tonyc/win32stat
(which is likely to produce a warning like this, which can be ignored:
remote: fatal: ambiguous argument refs/heads/smoke-me/tonyc/win32stat: unknown revision or path not in the working tree. remote: Use -- to separate paths from revisions
) and then delete your local branch:
% git branch -d win32stat
The committers have SSH access to the two servers that serve perl5.git.perl.org. One is perl5.git.perl.org itself (camel), which is the master repository. The second one is users.perl5.git.perl.org (dromedary), which can be used for general testing and development. Dromedary syncs the git tree from camel every few minutes, you should not push there. Both machines also have a full CPAN mirror in /srv/CPAN, please use this. To share files with the general public, dromedary serves your ~/public_html/ as http://users.perl5.git.perl.org/~yourlogin/
These hosts have fairly strict firewalls to the outside. Outgoing, only rsync, ssh and git are allowed. For http and ftp, you can use http://webproxy:3128 as proxy. Incoming, the firewall tries to detect attacks and blocks IP addresses with suspicious activity. This sometimes (but very rarely) has false positives and you might get blocked. The quickest way to get unblocked is to notify the admins.
These two boxes are owned, hosted, and operated by booking.com. You can reach the sysadmins in #p5p on irc.perl.org or via mail to email@example.com.
|perl v5.22.1||PERLGIT (1)||2015-10-17|