Workflow using git
Switch branches/tags
Nothing to show
Pull request Compare This branch is 48 commits behind matthew-brett:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


.. -*- rest -*-
.. vim:syntax=rest


A set of documents and an example repository to describe starting with
github and a git workflow.

Our idea is that many projects may have the same workflow, more or less.
Each project needs docs that have exact project-specific command lines
for use with git and github.

It seems a shame to type all this out for every project, when a lot of
it is the same.

Gitwash is one way of solving this problem.  

* You can build the gitwash documents directly to review your workflow.
* The documents designed for re-use in different projects are in the
  ``gitwash`` subdirectory.
* In these documents, we've encoded the various strings you will want to
  replace with strings in ALL CAPS.  The ``PROJECTNAME`` is the name of
  the project as it appears in text - for example ``IPython``.
  ``REPONAME`` is the name of the repository (e.g ``ipython``), and
  ``MAIN_GH_USER`` is the main github user (the user for the central
  github repository - or the name of the github "organization").  This
  results in links to your project repository of the form
* The script ```` will checkout the gitwash repository,
  do a search and replace on these strings and replace them with the
  ones you want, and then output these into your own docs in a place
  that you choose.  For IPython, ``PROJECTNAME`` is 'IPython',
  ``REPONAME`` is 'ipython', and the ``MAIN_GH_USER`` is also 'ipython'.
  An example command for *ipython* might then be:: doc/devel IPython --repo-name=ipython --github-user=ipython

  to dump the search / replaced docs into the ``doc/devel/gitwash``
* When defining your own project, you will need to fill out the links
  for your project in the file ``gitwash/`` - see the
  examples for ``nipy`` and ``ipython`` - just append under there with
  your equivalents.  For example, if your ``PROJECTNAME, REPONAME,
  MAIN_GH_USER`` are 'my_project', 'my_repo', 'my_user', then you would
  want to add these link targets::

     .. _my_project:
     .. _`my_project github`:
     .. _`my_project mailing list`: http://link-to-your-mailing.list

* You might want to have a Makefile target to update gitwash
  automatically from the sources.  For example, in the *nipy* docs
  Makefile, we have::

        python ../tools/ devel/guidelines nipy

nipy is one example of gitwash in use: