Collaborating with others
=========================

Using version control systems to collaborate with others is essentially no
different to working solo on multiple machines, except that you perhaps have
less knowledge of exactly what changes have been made by others.

Suppose my colleague Barbara has also been working on the same code: she cloned my
repository at version 0, and since then has been working independently. I'm a
little wary of pulling in her changes, so first I can take a look at what she's
changed:

First I add Barbara's repository as a "remote":

.. image:: images/sourcetree_add_remote.png

.. image:: images/sourcetree_add_remote2.png

Then I can fetch her changes to look at them, *without* merging them into my code.

.. image:: images/sourcetree_fetch_from_barbara.png

.. image:: images/sourcetree_fetch_from_barbara2.png

Looks like there may be some problems, since I've also changed parameters in CUBA.py,
and I'm saving figures to PNG format, not postscript. Oh, well, deep breath, let's plunge in:

.. code-block:: bash

    $ git pull /Users/barbara/our_network_model
    remote: Counting objects: 13, done.
    remote: Compressing objects: 100% (6/6), done.
    remote: Total 6 (delta 3), reused 0 (delta 0)
    Unpacking objects: 100% (6/6), done.
    From /Users/barbara/our_network_model
     * branch            HEAD       -> FETCH_HEAD
    Auto-merging CUBA.py
    CONFLICT (content): Merge conflict in CUBA.py
    Auto-merging COBAHH.py
    CONFLICT (content): Merge conflict in COBAHH.py
    Automatic merge failed; fix conflicts and then commit the result.

Doing the pull in SourceTree gives a similar message:

.. image:: images/sourcetree_merge_conflicts.png

Unlike last time, when our changes were in different parts of the file, and so
could be merged automatically, here Barbara has changed some of the same lines
as me, and Git can't choose which changes to keep.


Dealing with conflicting changes
--------------------------------


If we now look at :file:`CUBA.py`, we can see the conflicts marked with
``<<<<<<<`` and ``>>>>>>>``:


.. code-block:: python

    ...
    from brian import *
    import time

    start_time=time.time()
    <<<<<<< HEAD
    taum=15*ms
    taue=3*ms
    taui=5*ms
    =======
    taum=25*ms
    taue=5*ms
    taui=10*ms
    >>>>>>> 58a6d1659c88502e66e2aa27396a92949be24172
    Vt=-50*mV
    Vr=-65*mV
    El=-49*mV

    ...

    <<<<<<< HEAD
    +savefig("CUBA_output.png")
    =======
    savefig("firing_rate_CUBA.eps")
    >>>>>>> 58a6d1659c88502e66e2aa27396a92949be24172


Well, it makes sense for both me and Barbara to explore different parameters,
and it makes sense to allow different file formats, so let's move the
parameters into a separate file, and parameterize the file format. The file
now looks like this:

.. code-block:: python

    ...
    from brian import *
    import time
    from parameters import TAU_M, TAU_E, TAU_I, FILE_FORMAT

    start_time=time.time()
    taum = TAU_M*ms
    taue = TAU_E*ms
    taui = TAU_I*ms
    Vt=-50*mV
    Vr=-65*mV
    El=-49*mV

    ...

    assert FILE_FORMAT in ('eps', 'png', 'jpg')
    savefig("firing_rate_CUBA.%s" % FILE_FORMAT)


.. image:: images/sourcetree_conflict_resolved.png


After manually editing :file:`COBAHH.py` as well, I can now do a commit:


.. code-block:: bash

    $ git add COBAHH.py CUBA.py parameters.py

.. code-block:: bash

    $ git commit -m "Merged Barbara's changes; moved parameters to separate file"


SourceTree shows us how the graph has changed.

.. image:: images/sourcetree_conflict_resolved_committed.png


.. note:: I decided to add the new :file:`parameters.py` to the repository. This means
          Barbara and I will still have conflicts in future if we're using different
          parameters, but at least the conflicts will be localized to this one file. It
          might have been better not to have :file:`parameters.py` under version control,
          since it changes so often, but then we need another mechanism, in addition to
          version control, to keep track of our parameters.

I send Barbara an e-mail to tell her what I've done. Now all she has to do is
run :command:`git pull`.

.. code-block:: bash

    (barbara)$ cd ~/our_network_model
    (barbara)$ git pull /Volumes/USERS/andrew/my_network_model
    remote: Counting objects: 13, done.
    remote: Compressing objects: 100% (5/5), done.
    remote: Total 5 (delta 2), reused 0 (delta 0)
    Unpacking objects: 100% (5/5), done.
    From /Volumes/USERS/andrew/my_network_model
       0d285ea..f02997c  master     -> origin/master
    Updating e0a1383..f02997c
    Fast-forward
     COBAHH.py     |  4 ++--
     CUBA.py       | 10 ++++++----
     parameters.py |  4 ++++
     3 files changed, 12 insertions(+), 6 deletions(-)
     create mode 100644 parameters.py

Now she has the new file, :file:`parameters.py`, as well as the modified versions
of :file:`CUBA.py` and :file:`COBAHH.py`.

.. image:: images/sourcetree_all_synced.png


Recap #2
--------

You should now be able to use Git for:

  * quick and easy backups of your code
  * keeping your work in sync between multiple computers
  * collaborating with colleagues