+
+=head1 Cleaning a working directory
+
+The command C<git clean> can with varying arguments be used as a
+replacement for C<make clean>.
+
+To reset your working directory to a pristine condition you can do:
+
+ % git clean -dxf
+
+However, be aware this will delete ALL untracked content. You can use
+
+ % git clean -Xf
+
+to remove all ignored untracked files, such as build and test
+byproduct, but leave any manually created files alone.
+
+If you only want to cancel some uncommitted edits, you can use C<git
+checkout> and give it a list of files to be reverted, or C<git checkout
+-f> to revert them all.
+
+If you want to cancel one or several commits, you can use C<git reset>.
+
+=head1 Bisecting
+
+C<git> provides a built-in way to determine, with a binary search in
+the history, which commit should be blamed for introducing a given bug.
+
+Suppose that we have a script F<~/testcase.pl> that exits with C<0>
+when some behaviour is correct, and with C<1> when it's faulty. You need
+an helper script that automates building C<perl> and running the
+testcase:
+
+ % cat ~/run
+ #!/bin/sh
+ git clean -dxf
+
+ # If you get './makedepend: 1: Syntax error: Unterminated quoted
+ # string' when bisecting versions of perl older than 5.9.5 this hack
+ # will work around the bug in makedepend.SH which was fixed in
+ # version 96a8704c. Make sure to comment out `git checkout makedepend.SH'
+ # below too.
+ git show blead:makedepend.SH > makedepend.SH
+
+ # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
+ # if Encode is not needed for the test, you can speed up the bisect by
+ # excluding it from the runs with -Dnoextensions=Encode
+ sh Configure -des -Dusedevel -Doptimize="-g"
+ test -f config.sh || exit 125
+ # Correct makefile for newer GNU gcc
+ perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
+ # if you just need miniperl, replace test_prep with miniperl
+ make test_prep
+ [ -x ./perl ] || exit 125
+ ./perl -Ilib ~/testcase.pl
+ ret=$?
+ [ $ret -gt 127 ] && ret=127
+ # git checkout makedepend.SH
+ git clean -dxf
+ exit $ret
+
+This script may return C<125> to indicate that the corresponding commit
+should be skipped. Otherwise, it returns the status of
+F<~/testcase.pl>.
+
+You first enter in bisect mode with:
+
+ % git bisect start
+
+For example, if the bug is present on C<HEAD> but wasn't in 5.10.0,
+C<git> will learn about this when you enter:
+
+ % 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 C<HEAD> and
+C<perl-5.10.0>. You can then run the bisecting process with:
+
+ % git bisect run ~/run
+
+When the first bad commit is isolated, C<git bisect> will tell you so:
+
+ ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
+ commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
+ Author: Dave Mitchell <davem@fdisolutions.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 C<git bisect log> and
+C<git bisect visualize>. C<git bisect reset> will get you out of bisect
+mode.
+
+Please note that the first C<good> state must be an ancestor of the
+first C<bad> state. If you want to search for the commit that I<solved>
+some bug, you have to negate your test case (i.e. exit with C<1> if OK
+and C<0> if not) and still mark the lower bound as C<good> and the
+upper as C<bad>. The "first bad commit" has then to be understood as
+the "first commit where the bug is solved".
+
+C<git help bisect> has much more information on how you can tweak your
+binary searches.
+
+=head1 Submitting a patch via GitHub
+
+GitHub is a website that makes it easy to fork and publish projects
+with Git. First you should set up a GitHub account and log in.
+
+Perl's git repository is mirrored on GitHub at this page:
+
+ http://github.com/mirrors/perl/tree/blead
+
+Visit the page and click the "fork" button. This clones the Perl git
+repository for you and provides you with "Your Clone URL" from which
+you should clone:
+
+ % git clone git@github.com:USERNAME/perl.git perl-github
+
+The same patch as above, using github might look like this:
+
+ % cd perl-github
+ % git remote add upstream git://perl5.git.perl.org/perl.git
+ % git pull upstream blead
+ % git checkout -b orange
+ % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
+ % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
+ % git push origin orange
+
+The orange branch has been pushed to GitHub, so you should now send an
+email (see L</Submitting a patch>) with a description of your changes
+and the following information:
+
+ http://github.com/USERNAME/perl/tree/orange
+ git://github.com/USERNAME/perl.git branch orange
+
+=head1 Merging from a branch via GitHub
+
+If someone has provided a branch via GitHub and you are a committer,
+you should use the following in your perl-ssh directory:
+
+ % 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
+
+
+=head1 Topic branches and rewriting history
+
+Individual committers should create topic branches under
+B<yourname>/B<some_descriptive_name>. Other committers should check
+with a topic branch's 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<yourname>/B<some_descriptive_name>, you
+might sometimes find that the original author has edited the branch's
+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 C<refspec>'s
+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:> it is forbidden at the repository level to delete any of the
+"primary" branches. That is any branch matching
+C<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<not> edit the history of the blead and
+maint-* branches. If a typo (or worse) sneaks into a commit to blead or
+maint-*, we'll fix it in another commit. The only types of updates
+allowed on these branches are "fast-forward's", 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.)
+
+=head1 Committing to maintenance versions
+
+Maintenance versions should only be altered to add critical bug
+fixes, see L<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 C<maint-5.005>, which tracks the
+remote branch C<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 C<git cherry-pick> command. It is recommended to use the
+B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
+original commit in the new commit message.
+
+=head1 Grafts
+
+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
+C<.git/info/grafts> file:
+
+ 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
+
+It is particularly important to have this graft line if any bisecting
+is done in the area of the "merge" in question.
+
+=head1 SEE ALSO
+
+=over
+
+=item *
+
+The git documentation, accessible via the C<git help> command
+
+=item *
+
+L<perlpolicy> - Perl core development policy
+
+=back
+
+=cut