[pygr-notify] [pygr commit] r44 - wiki

[codesite-noreply at google.com]

Author: cjlee112
Date: Wed Jun 18 00:57:55 2008
New Revision: 44

Added:
   wiki/UsingGit.wiki

Log:
Created wiki page through web user interface.

Added: wiki/UsingGit.wiki
==============================================================================
--- (empty file)
+++ wiki/UsingGit.wiki	Wed Jun 18 00:57:55 2008
@@ -0,0 +1,95 @@
+#summary How to best use git for Pygr development.
+
+= Why Git? =
+
+Git is the front-runner of a new generation of "distributed source 
code management" tools that make it much easier for a dispersed group 
of developers to collaborate on a complex open source project like the 
Linux kernel.  The first thing to understand is that git dumps the 
previously universal assumption of a centralized repository, which 
developers check out files (from) and check in changes (to).  Instead, 
with git, *every* developer has the complete repository, storing the 
complete revision history.  That makes it much easier for each 
developer to work independently -- s/he doesn't even need a net 
connection to make commits.  Developers can clone a repository from 
each other, pull changes from each other, email patches to each other, 
push changes to a public site etc.  Second, git makes it spectacularly 
easy to work with branches: at any moment, you can create a new branch 
off your current code, make experimental changes as a series of commits 
on that branch -- without in any way affecting your "master" branch or 
any other branch -- and switch instantly between different branches.  
Merging in changes from one branch to another is amazingly easy and 
powerful in git, so if you decide you like your experimental changes, 
you can apply them to your "master" branch easily -- typically with 
just a single command "git merge".  Git has great momentum now, and it 
has already been a terrific boost to Pygr development.
+
+= Overview of How We're Using Git =
+The Pygr project is tiny in comparison with Linux kernel, so we can 
get away with a pretty simple development model:
+  * I own the "master" branch; i.e. all proposed changes pass through me.
+  * I make changes in my git repository.
+  * I push changes to the public git repository.
+  * Anyone else can get their own copy of the repository by using "git 
clone" from the public repository.
+  * Anyone else can create their own branch (in their own git 
repository), to try out changes that they want to make.  *Don't make 
changes in the master branch* as this will complicate your ability to 
pull from the public repository in the future; instead always create a 
separate branch in which to make your changes.  In doing so, you just 
commit your changes as usual, but in your branch, not in the "master" branch.
+  * If you have finalized changes that you want incorporated into the 
master branch, send them to me as email patches.  I will then examine 
them (typically as a temporary branch in my repository), and if I see 
no problems, will merge them into the master branch.
+  * We can create separate branches for a specific release cycle.  
E.g. I created a branch v0_7 for bug fixes to version 0.7.  It's 
trivial to pull bug fixes from the master branch into the v0_7 branch, 
and vice versa.
+
+= Git Usage Examples =
+=== Get a copy of the public repository ===
+{{{
+git clone git://repo.or.cz/pygr.git
+}}}
+
+=== Get the latest changes from the public repository ===
+{{{
+git checkout master
+git pull --rebase
+}}}
+The first command is only necessary if you were previously working on 
a different branch than "master".
+
+=== Make an experimental branch and commit changes there ===
+{{{
+git branch trythis
+git checkout trythis
+# edit one or more files, test your changes...
+git add pygr/sqlgraph.py tests/nosebase.py # whatever files you changed
+git add tests/new_test.py # you can also add new files to the repository
+git rm tests/old_test.py # and even delete a file (from this branch)
+git commit -m 'put a meaningful explanation of your changes here'
+# edit some more files...
+git add some_more_files.py
+git commit -m 'explain your new changes here'
+# and so on...
+}}}
+The basic process for making changes in git is:
+  * first, just edit whatever files you want.  You don't have to do 
anything to "check out" those files!
+  * use *git add* on your changed files, to "stage" these changes for committing.
+  * use *git commit* to commit all those changes as a single atomic 
revision.  Note that every commit has a unique ID (long hexadecimal 
code).  You can generally use this ID (or just its first few digits as 
long as it's unique) to specify a specific commit in any git command.
+
+=== See a list of branches in your repository ==
+{{{
+git branch
+}}}
+The current branch is marked with an asterisk.
+
+=== Switch to a different branch ===
+{{{
+git checkout master
+}}}
+Substitute the name of the branch you want for "master".
+
+=== See the current state of any edits you may have made, but not yet 
checked in ===
+{{{
+git status
+}}}
+
+=== See the history and branch structure of the repository with a 
graphical tool ===
+{{{
+gitk --all
+}}}
+Requires X windows and Tk.
+
+=== See repository history as text ===
+{{{
+git log
+}}}
+
+=== Merge new changes from one branch to another ===
+{{{
+git checkout trythis
+git merge master
+}}}
+This example automatically applies any changes from the master branch 
that have been made after you created your *trythis* branch.  Git is 
able to do most merges completely automatically; only if the changes 
overlap the same lines of code will it ask you to sort out the conflict 
(it puts diff markers in the relevant file; your job is to edit that 
file to be the way you want it).
+
+=== Apply a single commit from one branch to another ===
+{{{
+git checkout trythis
+git cherry-pick 37d1f89
+}}}
+Here we switch to the branch we want to change (in case we're not 
already on that branch).
+Then you specify the commit you want to apply via its SHA1 hash code, 
or in this case just its first few digits.
+
+Add your content here.  Format your content with:
+  * Text in *bold* or _italic_
+  * Headings, paragraphs, and lists
+  * Automatic links to other wiki pages
\ No newline at end of file