git command cheatsheet
======================

**N.B.** To learn about the development workflow (including branching strategy) that is used for the IPbus software and firmware repositories, please take a look at the :ref:`developmentWorkflow` page

Cloning
-------

To clone the whole repo, and work from the default branch:

.. code-block:: sh

  git clone <repo_url>

To clone the whole repo, and switch to branch/tag ``my_cool_feature``:

.. code-block:: sh

  git clone -b my_cool_feature


Switching working copy of repo to a different branch, tag or commit
-------------------------------------------------------------------

.. code-block:: sh

  git checkout <commit-sha-or-name-of-branch-or-tag>


Committing
----------

To check what files you have changed:

.. code-block:: sh

  git status

To add files to 'staging area' for the next commit:

.. code-block:: sh

  git add path/to/some-file path/to/another-file

To create commit from current contents of the 'staging area':

.. code-block:: sh

  git commit -m "A useful, but not too long, message that explains this commit's purpose"

To push files to the remote repository's branch that the current local branch is tracking:

.. code-block:: sh

  git push


Removing a file or directory
----------------------------

.. code-block:: sh

  git rm path/to/file-or-directory


Modifying the most recent commit
--------------------------------

Scenario: You just created a commit (probably not even pushed to remote repo); after creating the commit, you realised that you forgot to add a particular file / change, or screwed up the commit message

#. Add to the 'staging area', any changes that you want to include in the commit (**skip this step if you just want to change the commit's message**):

  .. code-block:: sh

    git add path/to/some-file path/to/another-file

#. Amend the last commit to include changes currently in the 'staging area'; this command brings up you default text editor allowing you to change the commit message as well

  .. code-block:: sh

    git commit --amend


Modifying multiple commits
--------------------------

Scenario: You created a series of commits on the current branch (maybe not even pushed to remote repo), but you now realise that you screwed up the messages for several of them.

Letting ``N`` be the number of commits that you need to go back in order to include all alterations ...

.. code-block:: sh

  git rebase -i HEAD~N


Tagging
-------

To create an annotated tag, named ``myCoolTag``:

.. code-block:: sh

  git tag -a myCoolTag -m "The message for this tag" <commit-sha>

To push that tag to the remote named ``origin``:

.. code-block:: sh

  git push origin myCoolTag