mirror of
https://github.com/wassname/scikit-image.git
synced 2026-08-05 13:21:12 +08:00
Add gitwash documentation.
This commit is contained in:
Stefan van der Walt
+6
-2
@@ -1,5 +1,9 @@
|
||||
Development process
|
||||
-------------------
|
||||
|
||||
:doc:`Read this overview <gitwash/index>` of how to use Git with
|
||||
``scikits.image``. Here's the long and short of it:
|
||||
|
||||
* Go to `http://github.com/stefanv/scikits.image
|
||||
<http://github.com/stefanv/scikits.image>`_ and follow the instructions on
|
||||
making your own fork/branch.
|
||||
@@ -17,8 +21,8 @@ All of this may be intimidating if you've never used git before, so we'd
|
||||
happily accept plain old unified diffs (``git diff`` or ``diff -u a.txt
|
||||
b.txt``) as well.
|
||||
|
||||
Guidelines:
|
||||
```````````
|
||||
Guidelines
|
||||
``````````
|
||||
* All code should have tests (see "Test coverage" below for more details).
|
||||
* All code should be documented, to the same
|
||||
`standard <http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines>`_
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
@@ -0,0 +1,89 @@
|
||||
.. _configure-git:
|
||||
|
||||
===============
|
||||
Configure git
|
||||
===============
|
||||
|
||||
.. _git-config-basic:
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
::
|
||||
|
||||
git config --global user.email you@yourdomain.example.com
|
||||
git config --global user.name "Your Name Comes Here"
|
||||
|
||||
|
||||
In detail
|
||||
=========
|
||||
|
||||
This is to tell git_ who you are, for labeling any changes you make to
|
||||
the code. The simplest way to do this is from the command line::
|
||||
|
||||
git config --global user.email you@yourdomain.example.com
|
||||
git config --global user.name "Your Name Comes Here"
|
||||
|
||||
This will write the settings into your git configuration file - a file
|
||||
called ``.gitconfig`` in your home directory.
|
||||
|
||||
Advanced git configuration
|
||||
==========================
|
||||
|
||||
You might well benefit from some aliases to common commands.
|
||||
|
||||
For example, you might well want to be able to shorten ``git checkout`` to ``git co``.
|
||||
|
||||
The easiest way to do this, is to create a ``.gitconfig`` file in your
|
||||
home directory, with contents like this::
|
||||
|
||||
[core]
|
||||
editor = emacs
|
||||
[user]
|
||||
email = you@yourdomain.example.com
|
||||
name = Your Name Comes Here
|
||||
[alias]
|
||||
st = status
|
||||
stat = status
|
||||
co = checkout
|
||||
[color]
|
||||
diff = auto
|
||||
status = true
|
||||
|
||||
(of course you'll need to set your email and name, and may want to set
|
||||
your editor). If you prefer, you can do the same thing from the command
|
||||
line::
|
||||
|
||||
git config --global core.editor emacs
|
||||
git config --global user.email you@yourdomain.example.com
|
||||
git config --global user.name "Your Name Comes Here"
|
||||
git config --global alias.st status
|
||||
git config --global alias.stat status
|
||||
git config --global alias.co checkout
|
||||
git config --global color.diff auto
|
||||
git config --global color.status true
|
||||
|
||||
These commands will write to your user's git configuration file
|
||||
``~/.gitconfig``.
|
||||
|
||||
To set up on another computer, you can copy your ``~/.gitconfig`` file,
|
||||
or run the commands above.
|
||||
|
||||
Other configuration recommended by Yarik
|
||||
========================================
|
||||
|
||||
In your ``~/.gitconfig`` file alias section::
|
||||
|
||||
wdiff = diff --color-words
|
||||
|
||||
so that ``git wdiff`` gives a nicely formatted output of the diff.
|
||||
|
||||
To enforce summaries when doing merges(``~/.gitconfig`` file again)::
|
||||
|
||||
[merge]
|
||||
summary = true
|
||||
|
||||
|
||||
.. include:: git_links.txt
|
||||
|
||||
|
||||
@@ -0,0 +1,233 @@
|
||||
.. _development-workflow:
|
||||
|
||||
====================
|
||||
Development workflow
|
||||
====================
|
||||
|
||||
You already have your own forked copy of the scikits.image_ repository, by
|
||||
following :ref:`forking`, :ref:`set-up-fork`, and you have configured
|
||||
git_ by following :ref:`configure-git`.
|
||||
|
||||
Workflow summary
|
||||
================
|
||||
|
||||
* Keep your ``master`` branch clean of edits that have not been merged
|
||||
to the main scikits.image_ development repo. Your ``master`` then will follow
|
||||
the main scikits.image_ repository.
|
||||
* Start a new *feature branch* for each set of edits that you do.
|
||||
* If you can avoid it, try not to merge other branches into your feature
|
||||
branch while you are working.
|
||||
* Ask for review!
|
||||
|
||||
This way of working really helps to keep work well organized, and in
|
||||
keeping history as clear as possible.
|
||||
|
||||
See - for example - `linux git workflow`_.
|
||||
|
||||
Making a new feature branch
|
||||
===========================
|
||||
|
||||
::
|
||||
|
||||
git branch my-new-feature
|
||||
git checkout my-new-feature
|
||||
|
||||
Generally, you will want to keep this also on your public github_ fork
|
||||
of scikits.image_. To do this, you `git push`_ this new branch up to your github_
|
||||
repo. Generally (if you followed the instructions in these pages, and
|
||||
by default), git will have a link to your github_ repo, called
|
||||
``origin``. You push up to your own repo on github_ with::
|
||||
|
||||
git push origin my-new-feature
|
||||
|
||||
From now on git_ will know that ``my-new-feature`` is related to the
|
||||
``my-new-feature`` branch in the github_ repo.
|
||||
|
||||
The editing workflow
|
||||
====================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
::
|
||||
|
||||
# hack hack
|
||||
git add my_new_file
|
||||
git commit -am 'NF - some message'
|
||||
git push
|
||||
|
||||
In more detail
|
||||
--------------
|
||||
|
||||
#. Make some changes
|
||||
#. See which files have changed with ``git status`` (see `git status`_).
|
||||
You'll see a listing like this one::
|
||||
|
||||
# On branch ny-new-feature
|
||||
# Changed but not updated:
|
||||
# (use "git add <file>..." to update what will be committed)
|
||||
# (use "git checkout -- <file>..." to discard changes in working directory)
|
||||
#
|
||||
# modified: README
|
||||
#
|
||||
# Untracked files:
|
||||
# (use "git add <file>..." to include in what will be committed)
|
||||
#
|
||||
# INSTALL
|
||||
no changes added to commit (use "git add" and/or "git commit -a")
|
||||
|
||||
#. Check what the actual changes are with ``git diff`` (`git diff`_).
|
||||
#. Add any new files to version control ``git add new_file_name`` (see
|
||||
`git add`_).
|
||||
#. To commit all modified files into the local copy of your repo,, do
|
||||
``git commit -am 'A commit message'``. Note the ``-am`` options to
|
||||
``commit``. The ``m`` flag just signals that you're going to type a
|
||||
message on the command line. The ``a`` flag - you can just take on
|
||||
faith - or see `why the -a flag?`_. See also the `git commit`_ manual
|
||||
page.
|
||||
#. To push the changes up to your forked repo on github_, do a ``git
|
||||
push`` (see `git push`).
|
||||
|
||||
Asking for code review
|
||||
======================
|
||||
|
||||
#. Go to your repo URL - e.g. ``http://github.com/your-user-name/scikits.image``.
|
||||
#. Click on the *Branch list* button:
|
||||
|
||||
.. image:: branch_list.png
|
||||
|
||||
#. Click on the *Compare* button for your feature branch - here ``my-new-feature``:
|
||||
|
||||
.. image:: branch_list_compare.png
|
||||
|
||||
#. If asked, select the *base* and *comparison* branch names you want to
|
||||
compare. Usually these will be ``master`` and ``my-new-feature``
|
||||
(where that is your feature branch name).
|
||||
#. At this point you should get a nice summary of the changes. Copy the
|
||||
URL for this, and post it to the `scikits.image mailing list`_, asking for
|
||||
review. The URL will look something like:
|
||||
``http://github.com/your-user-name/scikits.image/compare/master...my-new-feature``.
|
||||
There's an example at
|
||||
http://github.com/matthew-brett/nipy/compare/master...find-install-data
|
||||
See: http://github.com/blog/612-introducing-github-compare-view for
|
||||
more detail.
|
||||
|
||||
The generated comparison, is between your feature branch
|
||||
``my-new-feature``, and the place in ``master`` from which you branched
|
||||
``my-new-feature``. In other words, you can keep updating ``master``
|
||||
without interfering with the output from the comparison. More detail?
|
||||
Note the three dots in the URL above (``master...my-new-feature``) and
|
||||
see :ref:`dot2-dot3`.
|
||||
|
||||
Asking for your changes to be merged with the main repo
|
||||
=======================================================
|
||||
|
||||
When you are ready to ask for the merge of your code:
|
||||
|
||||
#. Go to the URL of your forked repo, say
|
||||
``http://github.com/your-user-name/scikits.image.git``.
|
||||
#. Click on the 'Pull request' button:
|
||||
|
||||
.. image:: pull_button.png
|
||||
|
||||
Enter a message; we suggest you select only ``scikits.image`` as the
|
||||
recipient. The message will go to the `scikits.image mailing list`_. Please
|
||||
feel free to add others from the list as you like.
|
||||
|
||||
Merging from trunk
|
||||
==================
|
||||
|
||||
This updates your code from the upstream `scikits.image github`_ repo.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
::
|
||||
|
||||
# go to your master branch
|
||||
git checkout master
|
||||
# pull changes from github
|
||||
git fetch upstream
|
||||
# merge from upstream
|
||||
git merge upstream master
|
||||
|
||||
In detail
|
||||
---------
|
||||
|
||||
We suggest that you do this only for your ``master`` branch, and leave
|
||||
your 'feature' branches unmerged, to keep their history as clean as
|
||||
possible. This makes code review easier::
|
||||
|
||||
git checkout master
|
||||
|
||||
Make sure you have done :ref:`linking-to-upstream`.
|
||||
|
||||
Merge the upstream code into your current development by first pulling
|
||||
the upstream repo to a copy on your local machine::
|
||||
|
||||
git fetch upstream
|
||||
|
||||
then merging into your current branch::
|
||||
|
||||
git merge upstream/master
|
||||
|
||||
Deleting a branch on github_
|
||||
============================
|
||||
|
||||
::
|
||||
|
||||
git checkout master
|
||||
# delete branch locally
|
||||
git branch -D my-unwanted-branch
|
||||
# delete branch on github
|
||||
git push origin :my-unwanted-branch
|
||||
|
||||
(Note the colon ``:`` before ``test-branch``. See also:
|
||||
http://github.com/guides/remove-a-remote-branch
|
||||
|
||||
Several people sharing a single repository
|
||||
==========================================
|
||||
|
||||
If you want to work on some stuff with other people, where you are all
|
||||
committing into the same repository, or even the same branch, then just
|
||||
share it via github_.
|
||||
|
||||
First fork scikits.image into your account, as from :ref:`forking`.
|
||||
|
||||
Then, go to your forked repository github page, say
|
||||
``http://github.com/your-user-name/scikits.image``
|
||||
|
||||
Click on the 'Admin' button, and add anyone else to the repo as a
|
||||
collaborator:
|
||||
|
||||
.. image:: pull_button.png
|
||||
|
||||
Now all those people can do::
|
||||
|
||||
git clone git@githhub.com:your-user-name/scikits.image.git
|
||||
|
||||
Remember that links starting with ``git@`` use the ssh protocol and are
|
||||
read-write; links starting with ``git://`` are read-only.
|
||||
|
||||
Your collaborators can then commit directly into that repo with the
|
||||
usual::
|
||||
|
||||
git commit -am 'ENH - much better code'
|
||||
git push origin master # pushes directly into your repo
|
||||
|
||||
Exploring your repository
|
||||
=========================
|
||||
|
||||
To see a graphical representation of the repository branches and
|
||||
commits::
|
||||
|
||||
gitk --all
|
||||
|
||||
To see a linear list of commits for this branch::
|
||||
|
||||
git log
|
||||
|
||||
You can also look at the `network graph visualizer`_ for your github_
|
||||
repo.
|
||||
|
||||
.. include:: git_links.txt
|
||||
@@ -0,0 +1,28 @@
|
||||
.. _dot2-dot3:
|
||||
|
||||
========================================
|
||||
Two and three dots in difference specs
|
||||
========================================
|
||||
|
||||
Thanks to Yarik Halchenko for this explanation.
|
||||
|
||||
Imagine a series of commits A, B, C, D... Imagine that there are two
|
||||
branches, *topic* and *master*. You branched *topic* off *master* when
|
||||
*master* was at commit 'E'. The graph of the commits looks like this::
|
||||
|
||||
|
||||
A---B---C topic
|
||||
/
|
||||
D---E---F---G master
|
||||
|
||||
Then::
|
||||
|
||||
git diff master..topic
|
||||
|
||||
will output the difference from G to C (i.e. with effects of F and G),
|
||||
while::
|
||||
|
||||
git diff master...topic
|
||||
|
||||
would output just differences in the topic branch (i.e. only A, B, and
|
||||
C).
|
||||
@@ -0,0 +1,36 @@
|
||||
.. _following-latest:
|
||||
|
||||
=============================
|
||||
Following the latest source
|
||||
=============================
|
||||
|
||||
These are the instructions if you just want to follow the latest
|
||||
*scikits.image* source, but you don't need to do any development for now.
|
||||
|
||||
The steps are:
|
||||
|
||||
* :ref:`install-git`
|
||||
* get local copy of the git repository from github_
|
||||
* update local copy from time to time
|
||||
|
||||
Get the local copy of the code
|
||||
==============================
|
||||
|
||||
From the command line::
|
||||
|
||||
git clone git://github.com/scikits.image/scikits.image.git
|
||||
|
||||
You now have a copy of the code tree in the new ``scikits.image`` directory.
|
||||
|
||||
Updating the code
|
||||
=================
|
||||
|
||||
From time to time you may want to pull down the latest code. Do this with::
|
||||
|
||||
cd scikits.image
|
||||
git pull
|
||||
|
||||
The tree in ``scikits.image`` will now have the latest changes from the initial
|
||||
repository.
|
||||
|
||||
.. include:: git_links.txt
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
@@ -0,0 +1,33 @@
|
||||
.. _forking:
|
||||
|
||||
==========================================
|
||||
Making your own copy (fork) of scikits.image
|
||||
==========================================
|
||||
|
||||
You need to do this only once. The instructions here are very similar
|
||||
to the instructions at http://help.github.com/forking/ - please see that
|
||||
page for more detail. We're repeating some of it here just to give the
|
||||
specifics for the scikits.image_ project, and to suggest some default names.
|
||||
|
||||
Set up and configure a github_ account
|
||||
======================================
|
||||
|
||||
If you don't have a github_ account, go to the github_ page, and make one.
|
||||
|
||||
You then need to configure your account to allow write access - see the
|
||||
``Generating SSH keys`` help on `github help`_.
|
||||
|
||||
Create your own forked copy of scikits.image_
|
||||
=========================================
|
||||
|
||||
#. Log into your github_ account.
|
||||
#. Go to the scikits.image_ github home at `scikits.image github`_.
|
||||
#. Click on the *fork* button:
|
||||
|
||||
.. image:: forking_button.png
|
||||
|
||||
Now, after a short pause and some 'Hardcore forking action', you
|
||||
should find yourself at the home page for your own forked copy of scikits.image_.
|
||||
|
||||
.. include:: git_links.txt
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
.. _git-development:
|
||||
|
||||
=====================
|
||||
Git for development
|
||||
=====================
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
forking_hell
|
||||
set_up_fork
|
||||
configure_git
|
||||
development_workflow
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
.. _install-git:
|
||||
|
||||
=============
|
||||
Install git
|
||||
=============
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
================ =============
|
||||
Debian / Ubuntu ``sudo apt-get install git-core``
|
||||
Fedora ``sudo yum install git-core``
|
||||
Windows Download and install msysGit_
|
||||
OS X Use the git-osx-installer_
|
||||
================ =============
|
||||
|
||||
In detail
|
||||
=========
|
||||
|
||||
See the git_ page for the most recent information.
|
||||
|
||||
Have a look at the github_ install help pages available from `github help`_
|
||||
|
||||
There are good instructions here: http://book.git-scm.com/2_installing_git.html
|
||||
|
||||
.. include:: git_links.txt
|
||||
@@ -0,0 +1,18 @@
|
||||
==============
|
||||
Introduction
|
||||
==============
|
||||
|
||||
These pages describe a git_ and github_ workflow for the scikits.image_
|
||||
project.
|
||||
|
||||
There are several different workflows here, for different ways of
|
||||
working with *scikits.image*.
|
||||
|
||||
This is not a comprehensive git_ reference, it's just a workflow for our
|
||||
own project. It's tailored to the github_ hosting service. You may well
|
||||
find better or quicker ways of getting stuff done with git_, but these
|
||||
should get you started.
|
||||
|
||||
For general resources for learning git_ see :ref:`git-resources`.
|
||||
|
||||
.. include:: git_links.txt
|
||||
@@ -0,0 +1,70 @@
|
||||
.. This (-*- rst -*-) format file contains commonly used link targets
|
||||
and name substitutions. It may be included in many files,
|
||||
therefore it should only contain link targets and name
|
||||
substitutions. Try grepping for "^\.\. _" to find plausible
|
||||
candidates for this list.
|
||||
|
||||
.. NOTE: reST targets are
|
||||
__not_case_sensitive__, so only one target definition is needed for
|
||||
nipy, NIPY, Nipy, etc...
|
||||
|
||||
.. scikits.image
|
||||
|
||||
.. _`scikits.image`: http://stefanv.github.com/scikits.image
|
||||
|
||||
.. _`scikits.image github`: http://github.com/stefanv/scikits.image
|
||||
|
||||
.. _`scikits.image mailing list`: http://groups.google.com/group/scikits-image
|
||||
|
||||
.. PROJECTNAME placeholders
|
||||
.. _PROJECTNAME: http://neuroimaging.scipy.org
|
||||
.. _`PROJECTNAME github`: http://github.com/nipy
|
||||
.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
|
||||
|
||||
.. nipy
|
||||
.. _nipy: http://neuroimaging.scipy.org
|
||||
.. _`nipy github`: http://github.com/nipy
|
||||
.. _`nipy mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
|
||||
|
||||
.. ipython
|
||||
.. _ipython: http://ipython.scipy.org
|
||||
.. _`ipython github`: http://github.com/ipython
|
||||
.. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
|
||||
|
||||
.. git stuff
|
||||
.. _git: http://git-scm.com/
|
||||
.. _github: http://github.com
|
||||
.. _github help: http://help.github.com
|
||||
.. _msysgit: http://code.google.com/p/msysgit/downloads/list
|
||||
.. _git-osx-installer: http://code.google.com/p/git-osx-installer/downloads/list
|
||||
.. _subversion: http://subversion.tigris.org/
|
||||
.. _git cheat sheet: http://github.com/guides/git-cheat-sheet
|
||||
.. _pro git book: http://progit.org/
|
||||
.. _git svn crash course: http://git-scm.com/course/svn.html
|
||||
.. _learn.github: http://learn.github.com/
|
||||
.. _network graph visualizer: http://github.com/blog/39-say-hello-to-the-network-graph-visualizer
|
||||
.. _git user manual: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
|
||||
.. _git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
|
||||
.. _git community book: http://book.git-scm.com/
|
||||
.. _git ready: http://www.gitready.com/
|
||||
.. _git casts: http://www.gitcasts.com/
|
||||
.. _Fernando's git page: http://www.fperez.org/py4science/git.html
|
||||
.. _git magic: http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html
|
||||
.. _git concepts: http://www.eecs.harvard.edu/~cduan/technical/git/
|
||||
.. _git clone: http://www.kernel.org/pub/software/scm/git/docs/git-clone.html
|
||||
.. _git checkout: http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html
|
||||
.. _git commit: http://www.kernel.org/pub/software/scm/git/docs/git-commit.html
|
||||
.. _git push: http://www.kernel.org/pub/software/scm/git/docs/git-push.html
|
||||
.. _git pull: http://www.kernel.org/pub/software/scm/git/docs/git-pull.html
|
||||
.. _git add: http://www.kernel.org/pub/software/scm/git/docs/git-add.html
|
||||
.. _git status: http://www.kernel.org/pub/software/scm/git/docs/git-status.html
|
||||
.. _git diff: http://www.kernel.org/pub/software/scm/git/docs/git-diff.html
|
||||
.. _git log: http://www.kernel.org/pub/software/scm/git/docs/git-log.html
|
||||
.. _git branch: http://www.kernel.org/pub/software/scm/git/docs/git-branch.html
|
||||
.. _git remote: http://www.kernel.org/pub/software/scm/git/docs/git-remote.html
|
||||
.. _git config: http://www.kernel.org/pub/software/scm/git/docs/git-config.html
|
||||
.. _why the -a flag?: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
|
||||
.. _git staging area: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
|
||||
.. _git management: http://kerneltrap.org/Linux/Git_Management
|
||||
.. _linux git workflow: http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html
|
||||
.. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html
|
||||
@@ -0,0 +1,57 @@
|
||||
.. _git-resources:
|
||||
|
||||
================
|
||||
git_ resources
|
||||
================
|
||||
|
||||
Tutorials and summaries
|
||||
=======================
|
||||
|
||||
* `github help`_ has an excellent series of how-to guides.
|
||||
* `learn.github`_ has an excellent series of tutorials
|
||||
* The `pro git book`_ is a good in-depth book on git.
|
||||
* A `git cheat sheet`_ is a page giving summaries of common commands.
|
||||
* The `git user manual`_
|
||||
* The `git tutorial`_
|
||||
* The `git community book`_
|
||||
* `git ready`_ - a nice series of tutorials
|
||||
* `git casts`_ - video snippets giving git how-tos.
|
||||
* `git magic`_ - extended introduction with intermediate detail
|
||||
* Fernando Perez' git page - `Fernando's git page`_ - many links and tips
|
||||
* A good but technical page on `git concepts`_
|
||||
* Th `git parable`_ is an easy read explaining the concepts behind git.
|
||||
* `git svn crash course`_: git_ for those of us used to subversion_
|
||||
|
||||
Advanced git workflow
|
||||
=====================
|
||||
|
||||
There are many ways of working with git_; here are some posts on the
|
||||
rules of thumb that other projects have come up with:
|
||||
|
||||
* Linus Torvalds on `git management`_
|
||||
* Linus Torvalds on `linux git workflow`_ . Summary; use the git tools
|
||||
to make the history of your edits as clean as possible; merge from
|
||||
upstream edits as little as possible in branches where you are doing
|
||||
active development.
|
||||
|
||||
Manual pages online
|
||||
===================
|
||||
|
||||
You can get these on your own machine with (e.g) ``git help push`` or
|
||||
(same thing) ``git push --help``, but, for convenience, here are the
|
||||
online manual pages for some common commands:
|
||||
|
||||
* `git add`_
|
||||
* `git branch`_
|
||||
* `git checkout`_
|
||||
* `git clone`_
|
||||
* `git commit`_
|
||||
* `git config`_
|
||||
* `git diff`_
|
||||
* `git log`_
|
||||
* `git pull`_
|
||||
* `git push`_
|
||||
* `git remote`_
|
||||
* `git status`_
|
||||
|
||||
.. include:: git_links.txt
|
||||
@@ -0,0 +1,18 @@
|
||||
.. _using-git:
|
||||
|
||||
Working with *scikits.image* source code
|
||||
======================================
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
git_intro
|
||||
git_install
|
||||
following_latest
|
||||
patching
|
||||
git_development
|
||||
git_resources
|
||||
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
================
|
||||
Making a patch
|
||||
================
|
||||
|
||||
You've discovered a bug or something else you want to change in scikits.image_ - excellent!
|
||||
|
||||
You've worked out a way to fix it - even better!
|
||||
|
||||
You want to tell us about it - best of all!
|
||||
|
||||
The easiest way is to make a *patch* or set of patches. Here we explain
|
||||
how. Making a patch is the simplest and quickest, but if you're going
|
||||
to be doing anything more than simple quick things, please consider
|
||||
following the :ref:`git-development` model instead.
|
||||
|
||||
.. _making-patches:
|
||||
|
||||
Making patches
|
||||
==============
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
::
|
||||
|
||||
# tell git who you are
|
||||
git config --global user.email you@yourdomain.example.com
|
||||
git config --global user.name "Your Name Comes Here"
|
||||
# get the repository if you don't have it
|
||||
git clone git://github.com/scikits.image/scikits.image.git
|
||||
# make a branch for your patching
|
||||
cd scikits.image
|
||||
git branch the-fix-im-thinking-of
|
||||
git checkout the-fix-im-thinking-of
|
||||
# hack, hack, hack
|
||||
# Tell git about any new files you've made
|
||||
git add somewhere/tests/test_my_bug.py
|
||||
# commit work in progress as you go
|
||||
git commit -am 'BF - added tests for Funny bug'
|
||||
# hack hack, hack
|
||||
git commit -am 'BF - added fix for Funny bug'
|
||||
# make the patch files
|
||||
git format-patch -M -C master
|
||||
|
||||
Then, send the generated patch files to the `scikits.image mailing list`_ - where we will thank you warmly.
|
||||
|
||||
In detail
|
||||
---------
|
||||
|
||||
#. Tell git_ who you are so it can label the commits you've made::
|
||||
|
||||
git config --global user.email you@yourdomain.example.com
|
||||
git config --global user.name "Your Name Comes Here"
|
||||
|
||||
#. If you don't already have one, clone a copy of the scikits.image_ repository::
|
||||
|
||||
git clone git://github.com/scikits.image/scikits.image.git
|
||||
cd scikits.image
|
||||
|
||||
#. Make a 'feature branch'. This will be where you work on your bug
|
||||
fix. It's nice and safe and leaves you with access to an unmodified
|
||||
copy of the code in the main branch::
|
||||
|
||||
git branch the-fix-im-thinking-of
|
||||
git checkout the-fix-im-thinking-of
|
||||
|
||||
#. Do some edits, and commit them as you go::
|
||||
|
||||
# hack, hack, hack
|
||||
# Tell git about any new files you've made
|
||||
git add somewhere/tests/test_my_bug.py
|
||||
# commit work in progress as you go
|
||||
git commit -am 'BF - added tests for Funny bug'
|
||||
# hack hack, hack
|
||||
git commit -am 'BF - added fix for Funny bug'
|
||||
|
||||
Note the ``-am`` options to ``commit``. The ``m`` flag just signals
|
||||
that you're going to type a message on the command line. The ``a``
|
||||
flag - you can just take on faith - or see `why the -a flag?`_.
|
||||
|
||||
#. When you have finished, check you have committed all your changes::
|
||||
|
||||
git status
|
||||
|
||||
#. Finally, make your commits into patches. You want all the commits
|
||||
since you branched from the ``master`` branch::
|
||||
|
||||
git format-patch -M -C master
|
||||
|
||||
You will now have several files named for the commits::
|
||||
|
||||
0001-BF-added-tests-for-Funny-bug.patch
|
||||
0002-BF-added-fix-for-Funny-bug.patch
|
||||
|
||||
Send these files to the `scikits.image mailing list`_.
|
||||
|
||||
When you are done, to switch back to the main copy of the code, just
|
||||
return to the ``master`` branch::
|
||||
|
||||
git checkout master
|
||||
|
||||
Moving from patching to development
|
||||
===================================
|
||||
|
||||
If you find you have done some patches, and you have one or more feature
|
||||
branches, you will probably want to switch to development mode. You can
|
||||
do this with the repository you have.
|
||||
|
||||
Fork the scikits.image_ repository on github_ - :ref:`forking`. Then::
|
||||
|
||||
# checkout and refresh master branch from main repo
|
||||
git checkout master
|
||||
git pull origin master
|
||||
# rename pointer to main repository to 'upstream'
|
||||
git remote rename origin upstream
|
||||
# point your repo to default read / write to your fork on github
|
||||
git remote add origin git@github.com:your-user-name/scikits.image.git
|
||||
# push up any branches you've made and want to keep
|
||||
git push origin the-fix-im-thinking-of
|
||||
|
||||
Then you can, if you want, follow the :ref:`development-workflow`.
|
||||
|
||||
.. include:: git_links.txt
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
@@ -0,0 +1,68 @@
|
||||
.. _set-up-fork:
|
||||
|
||||
==================
|
||||
Set up your fork
|
||||
==================
|
||||
|
||||
First you follow the instructions for :ref:`forking`.
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
::
|
||||
|
||||
git clone git@github.com/your-user-name/scikits.image.git
|
||||
cd scikits.image
|
||||
git remote add upstream git://github.com/scikits.image/scikits.image.git
|
||||
|
||||
In detail
|
||||
=========
|
||||
|
||||
Clone your fork
|
||||
---------------
|
||||
|
||||
#. Clone your fork to the local computer with ``git clone
|
||||
git@github.com:your-user-name/scikits.image.git``
|
||||
#. Investigate. Change directory to your new repo: ``cd scikits.image``. Then
|
||||
``git branch -a`` to show you all branches. You'll get something
|
||||
like::
|
||||
|
||||
* master
|
||||
remotes/origin/master
|
||||
|
||||
This tells you that you are currently on the ``master`` branch, and
|
||||
that you also have a ``remote`` connection to ``origin/master``.
|
||||
What remote repository is ``remote/origin``? Try ``git remote -v`` to
|
||||
see the URLs for the remote. They will point to your github_ fork.
|
||||
|
||||
Now you want to connect to the upstream `scikits.image github`_ repository, so
|
||||
you can merge in changes from trunk.
|
||||
|
||||
.. _linking-to-upstream:
|
||||
|
||||
Linking your repository to the upstream repo
|
||||
--------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
cd scikits.image
|
||||
git remote add upstream git://github.com/scikits.image/scikits.image.git
|
||||
|
||||
``upstream`` here is just the arbitrary name we're using to refer to the
|
||||
main scikits.image_ repository at `scikits.image github`_.
|
||||
|
||||
Note that we've used ``git://`` for the URL rather than ``git@``. The
|
||||
``git://`` URL is read only. This means we that we can't accidentally
|
||||
(or deliberately) write to the upstream repo, and we are only going to
|
||||
use it to merge into our own code.
|
||||
|
||||
Just for your own satisfaction, show yourself that you now have a new
|
||||
'remote', with ``git remote -v show``, giving you something like::
|
||||
|
||||
upstream git://github.com/scikits.image/scikits.image.git (fetch)
|
||||
upstream git://github.com/scikits.image/scikits.image.git (push)
|
||||
origin git@github.com:your-user-name/scikits.image.git (fetch)
|
||||
origin git@github.com:your-user-name/scikits.image.git (push)
|
||||
|
||||
.. include:: git_links.txt
|
||||
|
||||
Reference in New Issue
Block a user