git clone git://perl5.git.perl.org/perl.git perl-git
-This clones the repository and makes a local copy in the 'perl-git'
+This clones the repository and makes a local copy in the F<perl-git>
directory.
If your local network does not allow you to use port 9418, then you can
git clone http://perl5.git.perl.org/perl.git perl-http
-This clones the repository and makes a local copy in the 'perl-http'
+This clones the repository and makes a local copy in the F<perl-http>
directory.
=head2 WRITE ACCESS TO THE REPOSITORY
% git remote add camel user@camel:/gitroot/perl.git
This allows you to update your local repository by pulling from
-C<origin>, which is faster and doesn't require you to authentify, and
+C<origin>, which is faster and doesn't require you to authenticate, and
to push your changes back with the C<camel> remote:
% git fetch camel
Once you have changed into the repository directory, you can inspect
it.
-
After a clone the repository will contain a single local branch, which
-will be the current branch as well, as indicated by the asterix.
+will be the current branch as well, as indicated by the asterisk.
% git branch
* blead
-Using the -a switch to branch will also show the remote tracking
+Using the -a switch to C<branch> will also show the remote tracking
branches in the repository:
% git branch -a
% git checkout origin/maint-5.8-dor
+To make a local branch of a remote branch:
+
+ % git checkout -b maint-5.10 origin/maint-5.10
+
To switch back to blead:
% git checkout blead
% git checkout blead
% git pull
+(It's preferable to patch against the latest blead version, since patches
+are usually integrated from blead to the maintainance branches. This
+does not apply, obviously, in the rare case where your patch is specific
+to a maintaince release.)
+
Now that we have everything up to date, we need to create a temporary
new branch for these changes and switch into it:
You can see what files are changed:
% git status
- # On branch blead
+ # On branch orange
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
% git branch -D orange
Deleted branch orange.
+=head2 A note on derived files
+
+Be aware that many files in the distribution are derivative--avoid
+patching them, because git won't see the changes to them, and the
+build process will overwrite them.
+Patch the originals instead. Most utilities (like perldoc) are in
+this category, i.e. patch utils/perldoc.PL rather than utils/perldoc.
+Similarly, don't create patches for files under $src_root/ext from
+their copies found in $install_root/lib. If you are unsure about the
+proper location of a file that may have gotten copied while building
+the source distribution, consult the C<MANIFEST>.
+
+=head2 A note on binary files
+
+Since the patch(1) utility cannot deal with binary files, it's important
+that you either avoid the use of binary files in your patch, generate the
+files dynamically, or that you encode any binary files using the
+F<uupacktool.pl> utility.
+
+Assuming you needed to include a gzip-encoded file for a module's test
+suite, you might do this as follows using the F<uupacktool.pl> utility:
+
+ $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz
+ Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed
+
+This will replace the C<t.gz> file with an encoded counterpart. During
+C<make test>, before any tests are run, perl's Makefile will restore all
+the C<.packed> files mentioned in the MANIFEST to their original name.
+This means that the test suite does not need to be aware of this packing
+scheme and will not need to be altered.
+
+=head2 Getting your patch accepted
+
+The first thing you should include with your patch is a description of the
+problem that the patch corrects. If it is a code patch (rather than a
+documentation patch) you should also include a small test case that
+illustrates the bug (a patch to an existing test file is preferred).
+
+If you are submitting a code patch there are several other things that
+you need to do.
+
+=over 4
+
+=item Comments, Comments, Comments
+
+Be sure to adequately comment your code. While commenting every
+line is unnecessary, anything that takes advantage of side effects of
+operators, that creates changes that will be felt outside of the
+function being patched, or that others may find confusing should
+be documented. If you are going to err, it is better to err on the
+side of adding too many comments than too few.
+
+=item Style
+
+In general, please follow the particular style of the code you are patching.
+
+In particular, follow these general guidelines for patching Perl sources:
+
+ 8-wide tabs (no exceptions!)
+ 4-wide indents for code, 2-wide indents for nested CPP #defines
+ try hard not to exceed 79-columns
+ ANSI C prototypes
+ uncuddled elses and "K&R" style for indenting control constructs
+ no C++ style (//) comments
+ mark places that need to be revisited with XXX (and revisit often!)
+ opening brace lines up with "if" when conditional spans multiple
+ lines; should be at end-of-line otherwise
+ in function definitions, name starts in column 0 (return value is on
+ previous line)
+ single space after keywords that are followed by parens, no space
+ between function name and following paren
+ avoid assignments in conditionals, but if they're unavoidable, use
+ extra paren, e.g. "if (a && (b = c)) ..."
+ "return foo;" rather than "return(foo);"
+ "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
+
+=item Testsuite
+
+When submitting a patch you should make every effort to also include
+an addition to perl's regression tests to properly exercise your
+patch. Your testsuite additions should generally follow these
+guidelines (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
+
+ Know what you're testing. Read the docs, and the source.
+ Tend to fail, not succeed.
+ Interpret results strictly.
+ Use unrelated features (this will flush out bizarre interactions).
+ Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
+ Avoid using hardcoded test numbers whenever possible (the
+ EXPECTED/GOT found in t/op/tie.t is much more maintainable,
+ and gives better failure reports).
+ Give meaningful error messages when a test fails.
+ Avoid using qx// and system() unless you are testing for them. If you
+ do use them, make sure that you cover _all_ perl platforms.
+ Unlink any temporary files you create.
+ Promote unforeseen warnings to errors with $SIG{__WARN__}.
+ Be sure to use the libraries and modules shipped with the version
+ being tested, not those that were already installed.
+ Add comments to the code explaining what you are testing for.
+ Make updating the '1..42' string unnecessary. Or make sure that
+ you update it.
+ Test _all_ behaviors of a given operator, library, or function:
+ - All optional arguments
+ - Return values in various contexts (boolean, scalar, list, lvalue)
+ - Use both global and lexical variables
+ - Don't forget the exceptional, pathological cases.
+
+=back
+
=head1 ACCEPTING A PATCH
If you have received a patch file generated using the above section,
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.
+
+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
% 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
+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 SEE ALSO
+
+The git documentation, accessible via C<git help command>.
projects / p5sagit/p5-mst-13.2.git / blobdiff