{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# How to use `git` for your notebooks?" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This notebook describes the workflow you can adopt to work efficently on your notebooks with your colleagues, and how you can share notebooks through simple shareable links with anyone.\n", "\n", "`git` it is a version control system, designed to help team work on a set of shared files. There are two main uses of git:\n", "1. Each member of the notebook development team can work on the files and send his/her changes to the files to a `git` server.\n", "2. The `git` server can also be configured to allow a public read-only access to the files, allowing anyone to get a copy of the files.\n", "\n", "For point 2. (sharing your git repository to your audience) read [this notebook](../../TeachingHowTos/ShareNotebooksWithStudents.ipynb)!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Getting ready to use `git`\n", "This notebook does _not_ go into details on how to use `git`.
\n", "Have a look at other resources on the web, for instance [this tutorial on how to share Jupyter Notebooks with `git`](https://reproducible-science-curriculum.github.io/sharing-RR-Jupyter/01-sharing-github/) and [these tutorials on how to use `git` in general](https://try.github.io/).\n", "\n", "# What git server should you use?\n", "\n", "We recommand using a `git` server to store your work on your notebooks and to share them with colleagues and students.\n", "\n", "![git server](Images/sharing_with_git.png)\n", "\n", "*figure: git server at the center of your workflow.*\n", "\n", "\n", "There are many places around the web providing `git` services:\n", "\n", "* EPFL's [`c4science`](https://gitlab.epfl.ch/) - using your GASPAR account\n", "* EPFL's [`gitlab`](https://gitlab.epfl.ch/) - using your GASPAR account\n", "* [`github`](https://github.com/) - you need a `github` account\n", "\n", "While ![noto](../../Images/noto_inline_transparent.png) works perfectly with any of these `git` servers, we would like to stress out the fact that you should care about **where** in the the world your data is stored. By using EPFL's services you ensure your data stays in Switzerland and that your work will not be impacted by possible changes in the law on data protection.\n", "\n", "# Setting up your environment for working with a git server\n", "\n", "## For public repositories\n", "\n", "Usually, once your `git` tool is installed on your personal computer (just like it is in ![noto](../../Images/noto_inline_transparent.png)), you are ready to go and you can clone right away any `git` public repository.\n", "Most public `git` repositories are read-only, meaning that you can not contribute back by sending the changes you made. To contribute (push your changes to the `git` server), you need to authenticate and ,of course, have write access on the `git` repository! (see next section)\n", "\n", "## Authenticating on a remote git server\n", "\n", "There are two ways to authenticate on a remote server: using a **username** and a **password** or to user **SSH keys**. While both methods will work from the command line (`git` command will ask your username and password), it is much more convenient to setup SSH keys: the `git` command will make use of your SSH keys and not ask for your password everytime and the `git` interface from Jupyterlab will be able to interact with the server.\n", "We recommend you take some time to set up SSH keys authentication - it not a long process and that will certainly speed up your \n", "\n", "Here are the required steps for having SSH keys authentication to work:\n", "\n", "* Make sure the remote URL of your git folder starts with `ssh://...`. When you clone and existing repository, use the `ssh://...` URL (not the `https://...` version).\n", "* Make sure your SSH keys on ![noto](../../Images/noto_inline_transparent.png) are ready (see the \"using git\" notebook in your Documentation directory)\n", "* Make sure you imported your public key over to your account on the remote server. On most `git` services, in your user's settings page, there is a place to add new SSH keys.\n", "\n", "This should be enough to have SSH key authentication working.\n", "Should you need to troubleshoot, the `jupyterlab-git` extension (then part that provide the JupyterLab integration with `git`) is unfortunately not really helpfull.\n", "So, always give it a go in your Terminal for a more verbose feedback.\n", "\n", "## Making `git` work easier\n", "\n", "There are a few things to consider when using `git` for Jupyter notebooks:\n", "\n", "1. It is much more convinient to only commit *clean* notebooks: you should remove your outputs before your commit. Once that is done, it is much easier to see the differences from one version to another. Also, it gives the opportunity to your readers to run the notebook themselves. **Reproducibility** is an important aspect of the work you are sharing: it is more important to ensure that the notebooks work perfectly and that anyone can reproduce the output than just pushing your own outputs to the `git` server.\n", "\n", "2. Jupyter and Python produce temporary files that you do not want to be part of your repository: make sure that the root of your `git` repository contains a `.gitignore' file with the following content:\n", "\n", "```\n", "**/.ipynb_checkpoints\n", "**/__pycache__\n", "```\n", "\n", "3. Avoid putting large binary files, especially content that could be hosted somewhere else. e.g. if you need a video from youtube, import it as [link](../EmbedExternalResources/EmbedExternalResources.ipynb#Videos).\n", "\n", "# Sharing notebooks through shareable links using git\n", "\n", "On noto, you can use a mechanism called `nbgitpuller` (it *clones* or *pulls* your `git` repository into the user's workspace and opens a notebook). This allows you to share your notebooks with anyone by simply sending a link. Any person clicking this link gets to a specific notebook from your `git` repository, loaded on noto.\n", "\n", "For teachers, this is a very convenient way to share notebooks, for instance by publishing a link to one of your notebooks on your course's Moodle page. Your students click and they get to the notebook directly.\n", "\n", "[More information on how to use it **in this notebook**.](../../TeachingHowTos/SharingNotebooksWithStudents.ipynb)\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", "\n", "**End of the notebook**" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.8" } }, "nbformat": 4, "nbformat_minor": 4 }