Changes between Version 8 and Version 9 of GitMirror

Timestamp:

02/26/09 16:22:17 (4 years ago)

Author:

pv

Comment:

--

GitMirror

@@ -1 @@
-There are automatically updated git mirrors of Numpy (and Scipy) on github:
+There are automatically updated git mirrors of Numpy (and Scipy) available:
 
   - http://github.com/pv/numpy-svn
   - http://github.com/pv/scipy-svn
 
-One can also be found here:
-
+You can use these to make developing contributions to Numpy and Scipy easier.
+An example workflow is discussed on this page.
+
+There are also several developer's work repositories there, for example:
+
+  - http://github.com/pv/scipy-work
   - http://github.com/cournape/numpy
 
-I won't talk about how to use git, only some points to keep in mind when using the mirror. There is a lot of resources to learn git on the web.
-
-= Download the git =
-
-Cloning the repository is straightforward:
-{{{
-git clone http://github.com/pv/numpy-svn.git
-}}}
-
-= Importing svn meta-data =
-
-Unfortunately, the clone command of git does not copy the svn metadata by default. To do so, you have to do the following for each clone:
-
-== Get the SVN branches ==
-
-Edit .git/config to look something like this:
+You may also find Git's documentation useful:
+
+  - http://git-scm.com/documentation
+
+There are also a lot of other resources to learn git on the web; this text concentrates more on using this specific SVN mirror.
+
+= Preparations =
+
+== Clone the Git mirror ==
+
+You need to clone the Git mirror of Scipy's SVN repository first.
+This needs to be done only once.
+{{{
+git clone git://github.com/pv/scipy-svn.git scipy.git
+}}}
+This will take some time, as the repository (ca. 30 MB) contains Scipy's whole history.
+
+Then, get the SVN branch pointers. First, edit `scipy.git/.git/config` and change
+the `remote "origin"` section to look like this:
 {{{
 [remote "origin"]
-        url = git://github.com/pv/numpy-svn.git
+        url = git://github.com/pv/scipy-svn.git
         fetch = +refs/remotes/*:refs/remotes/*
-[branch "master"]
-        remote = origin
-        merge = refs/remotes/trunk
-}}}
-This ensures that you get the most recent SVN branch pointers when you run ''git fetch''.
-
-Alternatively, execute the following command to get them only once:
-{{{
-git fetch git://github.com/pv/numpy-svn.git +refs/remotes/*:refs/remotes/*
-}}}
-This will tell git to download all the svn branch/tags info available on the git mirror just this time.
-
-== Configure git-svn ==
-
-If you want to commit back to SVN, or to get changes directly from SVN, you need to configure git-svn for the clone:
-
-Edit your .git/config, and add the follwing:
-{{{
-[svn-remote "svn"]
-        url = http://svn.scipy.org/svn/numpy
-        fetch = trunk:refs/remotes/trunk
-        branches = branches/*:refs/remotes/*
-        tags = tags/*:refs/remotes/tags/*
-}}}
-This tells git-svn where to get svn meta-data.
-
-To update the svn metadata, run:
-{{{
-git checkout master && git svn rebase -l
-}}}
-This should be reasonably fast.
-
+}}}
+ie. change `heads` to `remotes` and `origin` to `svn`. Then run
+{{{
+git fetch
+}}}
+`XXX: this is mildly ugly, we can investigate if it's possible to streamline this`
+
+Now you can do
+{{{
+git log trunk
+}}}
+to view the commit log of Scipy's trunk. Or, list branches and tags in SVN:
+{{{
+git branch -r
+}}}
+
+== Initializing git-svn ==
+
+This is optional, but needs to be done if you want to use git-svn
+to commit your changes back to SVN.
+{{{
+git-svn init -s http://svn.scipy.org/svn/scipy
+git-svn rebase -l
+}}}
+This should be very fast.
 
 = Using the git clone =
@@ -65 +65 @@
 == Create a branch ==
 
-There is one rule to always remember: NEVER WORK ON A SVN BRANCH DIRECTLY, ALWAYS ON A BRANCH MADE FROM IT!
+There is one rule to always remember:
+'''never work on a remote (eg. SVN) branch directly, always on a branch made from it!'''
+
 Concretely, if you want to work on the trunk
-
 {{{
 # Make a branch 'work' based on trunk, and switch to it
 git checkout -b work trunk
 }}}
-
-== Committing to svn ==
-
-If you have set up git-svn as instructed above, you can commit back to the scipy svn repository with git svn dcommit:
+You can list available branches with
+{{{
+git branch       # <- your branches
+git branch -r    # <- remote branches
+}}}
+
+== Edit and commit ==
+
+For this point, things function as explained in the Git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
+
+Commands typically needed:
+{{{
+git add FILES       # add new files
+git commit FILES    # commit. If you don't supply files, supply -a to commit everything
+}}}
+
+== Staying abreast SVN ==
+
+To fetch new items from the SVN mirror, just do
+{{{
+git fetch
+}}}
+
+Then, you'll need to merge your changes with those in trunk.
+Two options: rebase or merge.
+
+If you haven't published your changes, you can just use rebase:
+{{{
+git rebase trunk
+}}}
+If there are conflicts, it will ask you to resolve them. After
+all is done, your commits will lie on top of those in SVN.
+Note that if one of your commits exactly matches changes made in SVN,
+it will silently disappear in rebasing.
+
+An alternative is merging, which does not rewrite history,
+{{{
+git merge trunk
+}}}
+`XXX: but committing changes back using git-svn may be more hairy if there are merges? Also, you get duplicate commits, since SVN cannot contain merge commits`
+
+= Collaboration via git =
+
+This should work similarly as in standard Git, but let's briefly mention some main points:
+
+== Publishing your branches ==
+
+For example http://github.com offers free space for publishing your work on Open-source projects.
+It's one of the most prominent providers, so we concentrate on it for now.
+
+For github, you can fork the scipy-svn repository via the web interface, so that you don't need
+to transfer a lot of data the first time.
+Note that you need to have a SSH private key to upload. Check the documentation
+
+    http://github.com/guides/home
+
+for how to get started with this.
+
+After that, tell git about your github account and the repository there
+{{{
+git remote add github git@github.com:pv/scipy-work.git
+}}}
+The address is specific to your account, so change it accordingly.
+
+Pushing your branch there:
+{{{
+git push github BRANCHNAME
+}}}
+
+
+== Viewing other people's changes ==
+
+First, tell Git about someone's branch:
+{{{
+git remote add pauli git://github.com/pv/scipy-work.git
+git fetch pauli
+git remote show pauli
+}}}
+
+Switch the working tree to it:
+{{{
+git checkout pauli/ticket-503-special-iv-fix
+}}}
+
+Examine what was done there:
+{{{
+git log trunk..
+git diff trunk
+git show bb21c
+git show 7f738
+}}}
+
+If you want to hack on it yourself, again create a branch of your own:
+{{{
+git checkout -b ticket-503-special-iv-fix pauli/ticket-503-special-iv-fix
+}}}
+
+== Dealing with changes in SVN ==
+
+`XXX: todo, find out and explain what to do if you have made changes to someone's stuff, and he/she has rebased against SVN in the meantime`
+
+
+= Dealing directly with SVN =
+
+If you configured git-svn as instructed above, you can interface directly to SVN.
+
+== Fetching items directly from SVN ==
+
+You can update your repository directly from SVN. It will still stay compatible with the SVN mirror even if you do this.
+{{{
+git svn fetch
+}}}
+
+== Committing to SVN ==
+
+Commit back to the scipy svn repository with git svn dcommit:
 {{{
 git svn dcommit
 }}}
-
-Before actually committing, it is a good idea to check whether you are committing where you think you are committing (with the dry run option of git svn dcommit):
+Note that this will create one commit for each one you have in Git.
+
+If you want to compress things to more compact form, you can use rebase
+{{{
+git rebase -i HASH
+}}}
+where HASH is a commit preceding the one, starting from which you want to
+compress history. This interactive rebasing allows you e.g. to edit commit
+messages, reorder commits (may cause conflicts), or squash several commits
+into a single one. 
+
+It may be wise to do create a separate branch for working on this
+in case you mess up.
+
+Before actually committing, it is also a good idea to check whether you are
+committing where you think you are committing (with the dry run option of
+`git svn dcommit`):
 {{{
 git svn dcommit -n
 }}}
-
-== Updating from numpy svn repository ==
-
-Use the rebase command. For example, updating the trunk is a matter of:
-{{{
-git checkout trunk
-git svn rebase -l
-}}}