From: Leon Brocard Date: Tue, 23 Dec 2008 16:52:13 +0000 (+0000) Subject: Remove inconsistent formatting in pod/perlrepository.pod with Porting/podtidy X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6acba58e99cd9b39fe8819489c5ef1fba1528787;p=p5sagit%2Fp5-mst-13.2.git Remove inconsistent formatting in pod/perlrepository.pod with Porting/podtidy --- diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index 23183a8..384e290 100644 --- a/pod/perlrepository.pod +++ b/pod/perlrepository.pod @@ -5,8 +5,8 @@ perlrepository - Using the Perl source repository =head1 SYNOPSIS All of Perl's source code is kept centrally in a Git repository. The -repository contains many Perl revisions from Perl 1 onwards and all -the revisions from Perforce, the version control system we were using +repository contains many Perl revisions from Perl 1 onwards and all the +revisions from Perforce, the version control system we were using previously. This repository is accessible in different ways. The full repository takes up about 80MB of disk space. A check out of @@ -45,8 +45,8 @@ directory. =head2 WRITE ACCESS TO THE REPOSITORY -If you are a committer, then you can fetch a copy of the repository that -you can push back on with: +If you are a committer, then you can fetch a copy of the repository +that you can push back on with: git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh @@ -54,8 +54,8 @@ This clones the repository and makes a local copy in the 'perl-ssh' directory. If you clone using git, which is faster than ssh, then you will need to -modify your config in order to enable pushing. Edit F<.git/config> where -you will see something like: +modify your config in order to enable pushing. Edit F<.git/config> +where you will see something like: [remote "origin"] url = git://perl5.git.perl.org/perl.git @@ -65,27 +65,33 @@ change that to something like this: [remote "origin"] url = ssh://perl5.git.perl.org/gitroot/perl.git -NOTE: there are symlinks set up so that the /gitroot is actually optional. +NOTE: there are symlinks set up so that the /gitroot is actually +optional. You can also set up your user name and e-mail address. For example % git config user.name "Leon Brocard" % git config user.email acme@astray.com -It is also possible to keep C as a git remote, and add a new remote for ssh access: +It is also possible to keep C as a git remote, and add a new +remote for ssh access: % git remote add camel user@camel:/gitroot/perl.git -This allows you to update your local repository by pulling from C, which is faster and doesn't require you to authentify, and to push your changes back with the C remote: +This allows you to update your local repository by pulling from +C, which is faster and doesn't require you to authentify, and +to push your changes back with the C remote: % git fetch camel % git push camel -The C command just updates the C refs, as the objects themselves should have been fetched when pulling from C. +The C command just updates the C refs, as the objects +themselves should have been fetched when pulling from C. =head1 OVERVIEW OF THE REPOSITORY -Once you have changed into the repository directory, you can inspect it. +Once you have changed into the repository directory, you can inspect +it. After a clone the repository will contain a single local branch, which @@ -94,8 +100,8 @@ will be the current branch as well, as indicated by the asterix. % git branch * blead -Using the -a switch to branch will also show the remote tracking branches in the -repository: +Using the -a switch to branch will also show the remote tracking +branches in the repository: % git branch -a * blead @@ -103,42 +109,43 @@ repository: origin/blead ... -The branches that begin with "origin" correspond to the "git remote" that -you cloned from (which is named "origin"). Each branch on the remote will -be exactly tracked by theses branches. You should NEVER do work on these -remote tracking branches. You only ever do work in a local branch. Local -branches can be configured to automerge (on pull) from a designated remote -tracking branch. This is the case with the default branch C which -will be configured to merge from the remote tracking branch -C. +The branches that begin with "origin" correspond to the "git remote" +that you cloned from (which is named "origin"). Each branch on the +remote will be exactly tracked by theses branches. You should NEVER do +work on these remote tracking branches. You only ever do work in a +local branch. Local branches can be configured to automerge (on pull) +from a designated remote tracking branch. This is the case with the +default branch C which will be configured to merge from the +remote tracking branch C. You can see recent commits: % git log -And pull new changes from the repository, and update your local repository -(must be clean first) +And pull new changes from the repository, and update your local +repository (must be clean first) % git pull -Assuming we are on the branch C immediately after a pull, this command -would be more or less equivalent to: +Assuming we are on the branch C immediately after a pull, this +command would be more or less equivalent to: % git fetch % git merge origin/blead -In fact if you want to update your local repository without touching your working -directory you do: +In fact if you want to update your local repository without touching +your working directory you do: % git fetch -And if you want to update your remote-tracking branches for all defined remotes -simultaneously you can do +And if you want to update your remote-tracking branches for all defined +remotes simultaneously you can do % git remote update -Neither of these last two commands will update your working directory, however -both will update the remote-tracking branches in your repository. +Neither of these last two commands will update your working directory, +however both will update the remote-tracking branches in your +repository. To switch to another branch: @@ -154,11 +161,11 @@ The most common git command you will use will probably be % git status -This command will produce as output a description of the current state of the -repository, including modified files and unignored untracked files, and in addition -it will show things like what files have been staged for the next commit, -and usually some useful information about how to change things. For instance the -following: +This command will produce as output a description of the current state +of the repository, including modified files and unignored untracked +files, and in addition it will show things like what files have been +staged for the next commit, and usually some useful information about +how to change things. For instance the following: $ git status # On branch blead @@ -179,13 +186,14 @@ following: # # deliberate.untracked -This shows that there were changes to this document staged for commit, and -that there were further changes in the working directory not yet staged. It -also shows that there was an untracked file in the working directory, and as -you can see shows how to change all of this. It also shows that there -is one commit on the working branch C which has not been pushed to the -C remote yet. B: that this output is also what you see as a -template if you do not provide a message to C. +This shows that there were changes to this document staged for commit, +and that there were further changes in the working directory not yet +staged. It also shows that there was an untracked file in the working +directory, and as you can see shows how to change all of this. It also +shows that there is one commit on the working branch C which +has not been pushed to the C remote yet. B: that this +output is also what you see as a template if you do not provide a +message to C. Assuming we commit all the mentioned changes above: @@ -206,8 +214,9 @@ We can re-run git status and see something like this: nothing added to commit but untracked files present (use "git add" to track) -When in doubt, before you do anything else, check your status and read it -carefully, many questions are answered directly by the git status output. +When in doubt, before you do anything else, check your status and read +it carefully, many questions are answered directly by the git status +output. =head1 SUBMITTING A PATCH @@ -220,15 +229,14 @@ Then change into the directory: % cd perl-git -Alternatively, if you already have a Perl repository, you should -ensure that you're on the I branch, and your repository -is up to date: +Alternatively, if you already have a Perl repository, you should ensure +that you're on the I branch, and your repository is up to date: % git checkout blead % git pull -Now that we have everything up to date, we need to create a temporary new -branch for these changes and switch into it: +Now that we have everything up to date, we need to create a temporary +new branch for these changes and switch into it: % git checkout -b orange @@ -304,12 +312,14 @@ switch into it: % git checkout -b experimental -Patches that were formatted by C are applied with C: +Patches that were formatted by C are applied with +C: % 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: +If just a raw diff is provided, it is also possible use this two-step +process: % git apply bugfix.diff % git commit -am "Some fixing" --author="That Guy " @@ -357,7 +367,8 @@ If you want to delete your temporary branch, you may do so with: =head1 CLEANING A WORKING DIRECTORY -The command C can with varying arguments be used as a replacement for make-clean. +The command C can with varying arguments be used as a +replacement for make-clean. To reset your working directory to a pristine condition you can do: @@ -367,14 +378,18 @@ 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. +to remove all ignored untracked files, such as build and test +byproduct, but leave any manually created files alone. =head1 BISECTING -C provides a built-in way to determine, with a binary search in the history, which commit should be blamed for introducing a given bug. +C 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. We need an helper script that automates building C and running the testcase: +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. We need +an helper script that automates building C and running the +testcase: % cat ~/run #!/bin/sh @@ -384,19 +399,23 @@ Suppose that we have a script F<~/testcase.pl> that exits with C<0> when some be make || exit 125 ./perl -Ilib ~/testcase.pl -This script may return C<125> to indicate that the corresponding commit should be skipped. Otherwise, it returns the status of F<~/testcase.pl>. +This script may return C<125> to indicate that the corresponding commit +should be skipped. Otherwise, it returns the status of +F<~/testcase.pl>. We first enter in bisect mode with: % git bisect start -For example, if the bug is present on C but wasn't in 5.10.0, C will learn about this when you enter: +For example, if the bug is present on C but wasn't in 5.10.0, +C 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 and C. We can then run the bisecting process with: +This results in checking out the median commit between C and +C. We can then run the bisecting process with: % git bisect run ~/run @@ -412,11 +431,19 @@ When the first bad commit is isolated, C will tell you so: bisect run success -You can peek into the bisecting process with C and C. C will get you out of bisect mode. +You can peek into the bisecting process with C and +C. C will get you out of bisect +mode. -Please note that the first C state must be an ancestor of the first C state. If you want to search for the commit that I 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 and the upper as C. The "first bad commit" has then to be understood as the "first commit where the bug is solved". +Please note that the first C state must be an ancestor of the +first C state. If you want to search for the commit that I +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 and the +upper as C. The "first bad commit" has then to be understood as +the "first commit where the bug is solved". -C has much more information on how you can tweak your binary searches. +C has much more information on how you can tweak your +binary searches. =head1 COMITTING TO MAINTENANCE VERSIONS @@ -426,5 +453,6 @@ 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. +branch origin/maint-5.005. Then you can pull, commit, merge and push as +before. +