Git Cheat-Sheet
===============

The following is a brief summary of the feature-branch workflow and important Git commands

* To get a local working copy of a repository (typically a fork of XGC-Devel or XGC-Full-f)

  .. code-block:: bash
  
     git clone https://[username]@github.com/PrincetonUniversity/[repo name].git
     
  * This will create a directory called ``[repo name]`` which contains the code of the branch ``master``
  * We do not work with the branch ``master`` itself;
    it is intended to hold the stable, verified version of the code and is updated only through pull requests.
  * You have to either checkout a feature branch or create a new branch for your code development.

* Get a branch (other than ``master``) from the GitHub repository

  * In directory ``[repo name]`` run

    .. code-block:: bash

       git checkout [branch]

  * This will create a working copy of the branch ``[branch]`` in the remote repository on GitHub on your local computer.
    This working copy is a branch itself with the name ``[branch]``.

* To display the branches available (only the ones that you have checked out before)

  .. code-block:: bash

     git branch

* To display all branches (including branches that are not on your computer but only in the online repository), remote branches will have the prefix ``remotes/``

  .. code-block:: bash

     git branch -a

* To get remote branches to your local working copy

  .. code-block:: bash

     git fetch

* To switch between branches

  .. code-block:: bash

     git checkout [branch]

* You can get a list of commits with

  .. code-block:: bash

     git log
 
* You can check out a specific commit by using the hexa-decimal number of that commit. Be sure that this commit was for your current branch.

  .. code-block:: bash

     git checkout [commit]

* Suppose you want to add a feature to the code. To do this, you first checkout the branch you want to start from (typically: ``master``)  and then create a copy of it with a different name

  .. code-block:: bash

     git checkout [branch name]
     git checkout –b [username]/[new branch name] [branch name]

  * This creates a local branch called ``[username]/[new branch name]`` on your local computer, which is a copy of the branch ``[branch name]`` in the remote repository.
  * Now you can work on your own branch. When you have finished something and want to keep it, you commit the modifications with

    .. code-block:: bash
    
       git commit –am 'a message explaining what you did'

  * Keep in mind:

    * No commit message is better than a non-descriptive, generic commit message.
      So include details that help other users understand what a specific commit includes (especially if you fixed a bug).
    * Use the following format (use enter for line breaks; the commit is executed only after the closing single quote is entered):

      .. code-block:: bash

         'Subject line:
         descriptive message'

  * **NEVER COMMIT DIRTY CODE**

    * Make sure that your code compiles and runs before you commit.
    * By committing code that does not compile or run, you make it impossible to use useful tools like ``git bisect`` that helps to identify commits that introduced a bug.
    * If you have already made a commit and later discover that it does not compile, then it is still possible to correct this mistake so long as the commit has not been merged.
      Follow `these instructions to rewrite history <https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History>`_, typically via ``git commit --amend`` (for the most recent commit) or ``git rebase -i`` (for older commits).

  * If you want to revert your modifications use

    .. code-block:: bash

       git checkout .

  * To make your branch available for others on GitHub, you have to ‘push’ it to the remote repository
  * To be safe (the branch you have been working on might exist already in the remote repository and others might have modified it) you should ‘pull’ from the remote repository first:

    .. code-block:: bash

       git pull origin [your current branch]

  * This will merge any changes made by others to this branch into your local copy and will notify you if there are any conflicts.
  * After resolving  any conflicts and committing the corresponding changes using ``git commit``, you are ready to ``push``

    .. code-block:: bash

       git push origin [your current branch]

* When you are done testing and verifying your modifications in your branch ``[username]/[branch name]`` and think it is ready to be merged into ``master``

  * First get an up-to-date copy of ``master``

    .. code-block:: bash

       git checkout master
       git pull origin master
       git checkout [username]/[branch name]

  * For safety (in case someone else is working on your branch):

    .. code-block:: bash

       git pull origin [username]/[new feature]

  * Now merge master into your branch

    .. code-block:: bash

       git merge master

  * Now push to the upstream repository (i.e. GitHub)

    .. code-block:: bash

       git push origin [username]/[new feature]

  * Go to GitHub and create a pull request for your changes to be merged into master of the parent XGC repository and select appropriate reviewers and notify them of you pull request.

* If you like, implement the scripts git-completion.bash and git-prompt.sh (in the directory utils/git_tools in the repository) in your shell environment.
  The first will add GIT command completion to your shell.
  The second will display a prompt indicating your current branch and other useful information once you cd to a GIT repository.
  Instructions for the installation of these scripts is included in the scripts.
  A small example:
  
  .. code-block:: bash

     11:47 core_dev ~/Work/Code_development/HBPS Project/XGC-Full-f/XGC-0$

  * To use those scripts add the following lines to your ``~/.bashrc`` (``~/.profile`` on OSX)

    .. code-block:: bash

       [ -f ~/bin/git-prompt.sh ] && . ~/bin/git-prompt.sh \
       PS1="\A$bold$magenta\$(ret=\$?; [ \$ret -ne 0 ] && echo -n \" \$ret\")$nbold $red\h $cyan\$(__git_ps1 '%s') $green\w$normal\\$ " \
       source ~/bin/git-completion.bash</code>` 


.. toctree::
   :maxdepth: 3