# =========================================================================== #

This file is intended for developers wanting to contribute to the main
BerkeleyGW repository using git.  From 2018 on, the main branch will be hosted
on GitHub, under the private BerkeleyGW organization. The present file offers
a step-by-step guide for setting up your git environment and pushing your
contributions to the main branch.


0.  Before you start

    You need three thing: a working installation of git, an account on github,
    and being part of the BerkeleyGW organization on github.
    
    For the first two steps, you can refer to the github online documentation:
        https://help.github.com/articles/set-up-git/
        https://help.github.com/articles/signing-up-for-a-new-github-account/

    If you are completely new to git and github, we recommend that you also
    look at the basic tutorials, such as
        https://guides.github.com/activities/hello-world/

    Finally, to request membership to the BerkeleyGW organization on github,
    have a look at the page https://github.com/BerkeleyGW
    and contact one of the administrators, such as Jack Deslippe (jdeslip),
    Felipe Jornada (jornada), or Gabriel Antonius (GkAntonius).


1.  Fork the main repository

    Once you are signed in on github, visit the page
    https://github.com/BerkeleyGW/BerkeleyGW
    and hit the 'Fork' button on the upper right region of the page,
    then select your own account as the forking location.


2.  Download the repository on your machine

    On your machine, go to the place that will contain the main BerkeleyGW
    directory and issue the command

        git clone https://github.com/USERNAME/BerkeleyGW.git

    where USERNAME should be replaced by your username. The full address
    that you need here can be seen by hitting the 'Clone or Download' button
    on the github page of *your own fork* of the project.

    The 'clone' command will create a directory named 'BerkeleyGW' and download
    the main distribution therein. You can specify a different name for this
    directory as an optional argument.


3.  Setup remote repositories

    Descend into the directory created by the previous step.
    At the moment, git knows only about the 'origin' location,
    which refers to your own fork of the project. We need to add one more
    remote location, that is, the 'main' repository. Issue

        git remote add main https://github.com/BerkeleyGW/BerkeleyGW.git

    Now, we want to set the default behavior of git so that you can easily
    push your modifications into your own forked repository (origin),
    and pull the latest modifications from the 'main' repository.

    First, set the 'main' remote repository as the default location
    for the master branch (both push and pull). This is achieved with
    the command

        git config branch.master.remote main

    Next, we set the 'origin' remote repository as the default location
    to push push to, with the command

        git config remote.pushDefault origin 

    Usually, one has to specify the remote location and the branch
    from which to push and pull.  With the present configuration,
    the commands 'git pull' and 'git push' without extra arguments
    point to the desired location and branches.

4.  Verify your configuration

    You can list the locations known by this git repository with the command

        git remote -v

    You should see the output

        main    https://github.com/BerkeleyGW/BerkeleyGW.git (fetch)
        main    https://github.com/BerkeleyGW/BerkeleyGW.git (push)
        origin  https://github.com/USERNAME/BerkeleyGW.git (fetch)
        origin  https://github.com/USERNAME/BerkeleyGW.git (push)

    Also, have a look at the file '.git/config'. It summarizes the
    configuration that we set in the previous step. We could have done this
    configuration by directly editing this file.


# =========================================================================== #
