.. index::
   remote repository
   github
   backup


.. _`sec:remote_repository`:


Remote repository
-----------------

Create an account on `github <https://github.com/>`_. 

Usually, you either create a new project remotely, then clone it locally. 
Or, you start a project locally and then you decide to back it up remotely. 
Here, the second option is explored.


Creating an Empty GitHub Repository 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This guide walks you through creating an empty repository on GitHub and pushing your first local commit.

Step 1: Create an Empty Repository on GitHub

1. Go to github and log in.
2. Click the **“+”** icon in the upper-right corner and choose **“New repository”**.
3. Fill in the repository name (e.g., ``my-project``).
4. **Leave the following options unchecked**:

   + ✅ Do **not** initialize with a README
   + ✅ Do **not** add a .gitignore or license

5. Click the **“Create repository”** button.

After creation, GitHub will show you instructions under the section: 
*"... or push an existing repository from the command line”*. Use those in the next steps.


Remote Repositories
^^^^^^^^^^^^^^^^^^^

Stage and commit the local files:

.. code-block:: console

    $ git add .
    $ git commit


Connecting to a **remote**:

Remote repositories (e.g., on GitHub) allow collaboration and backup.

.. code-block:: console

   $ git remote add origin https://github.com/user/my-project.git

This sets the remote called ``origin``.

**Pushing** changes for the first time after a branch creation:

.. code-block:: console

   $ git push -u origin my-branch

Then, subsequent push:

.. code-block:: console

   $ git push

This uploads your local commits to the remote repository.



If several people work on the project, you will have to regularly download the modifications of others. 
**Pulling** is done by:

.. code-block:: console

   $ git pull

This fetches and merges changes from the remote into your local branch.

**Fetching** but without merging:

.. code-block:: console

   $ git fetch

This downloads changes but does not apply them. You can inspect them before merging.


Credentials
^^^^^^^^^^^

It is practical to edit your ``.gitconfig`` file to add:

.. code-block:: console

   [credential]
      helper = store --file ~/.github_cred

and to put your credential in the ``.github_cred`` file.