docs/source/system_reference_guide/work_with_git.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Working with Git"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Clone a Repository with GitHub\n",
    "\n",
    "Here is an example repository you can use for this getting started guide:\n",
    "https://github.com/MAAP-Project/dps-unit-test\n",
    "\n",
    "1. Copy the Github clone link from https://github.com/MAAP-Project/dps-unit-test\n",
    "![Copy .git link](../_static/clone_demo2.png)\n",
    "\n",
    "2. Open the built-in Jupyter Github UI to the left of the file browser. Choose \"Clone a Repository\" and paste in the .git link you copied from the Github repository. You can also access this menu through the **Git** tab at the top of the Jupyter window. \n",
    "![Clone a Repository](../_static/clone_demo3.png)\n",
    "![Paste .git link](../_static/clone_demo4.png)\n",
    "\n",
    "3. You should see a new folder created with the repo you cloned. If you browse to that folder and open up the Jupyter Github UI again, it will show you some info about that repo.\n",
    "![Algorithm folder was created](../_static/clone_demo5.png)\n",
    "![Browse to folder](../_static/clone_demo6.png)\n",
    "![Look at Github UI](../_static/clone_demo7.png)\n",
    "\n",
    "4. If you want to make changes to the code and have your own copy of it to register, clone the code into a public repository in Github or in MAAP Gitlab.\n",
    "\n",
    "If you would like to create a template from an existing repository, create a new repository on GitHub where you have the option to \"Import a repository\" where you can supply the old repository git link. \n",
    "\n",
    "![Import a Repository](../_static/import_repository.png)\n",
    "\n",
    "Then, clone that new repository into the ADE via the steps above "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with the MAAP GitLab\n",
    "\n",
    ".. note::\n",
    " git can behave slowly and strangely over s3 bucket-based storage (i.e., `my-private-bucket` and `my-public-bucket`). It is recommended to set up your git-tracked repos on the root (somewhere inside of `~` or `/projects`).\n",
    "\n",
    "The MAAP GitLab instance is located at https://repo.maap-project.org/ . Make sure you can access this from the browser using your MAAP (EarthData Login) credentials.\n",
    "\n",
    "For NASA security reasons, MAAP cannot communicate with its GitLab instance over SSH. There also isn’t a username-password authentication option. Therefore, the recommended way to access MAAP repositories is to use GitLab Personal Access Tokens.\n",
    "\n",
    "1. In GitLab, in the top-right corner, click your user icon → “Preferences”\n",
    "![Preferences](../_static/gitlab1.png)\n",
    "\n",
    "2. In the “User settings” menu, navigate to “Access Tokens”.\n",
    "\n",
    "<img src=\"../_static/gitlab2.png\" height=\"450\" alt=\"Access Tokens\">\n",
    "\n",
    "3. Create a new token with at least “read_repository” and “write_repository” permissions.\n",
    "![New Token Configuration](../_static/gitlab3.png)\n",
    "\n",
    "4. After clicking “create personal access token”, you’ll see a message like this pop up. Make sure you copy this token into a text file — you will not be able to access it again.\n",
    "![Access Token Popup Message](../_static/gitlab4.png)\n",
    "\n",
    "5. In the MAAP ADE, include this access token as part of the remote URL; e.g.,\n",
    "\n",
    "```\n",
    "git clone https://username:AccessToken@repo.maap-project.org/username/repo_name\n",
    "```\n",
    "\n",
    "For example:\n",
    "\n",
    "```\n",
    "git clone https://ashiklom:JJVimxhV8nmRNDqcCNr7@repo.maap-project.org/ashiklom/fireatlas\n",
    "````\n",
    "\n",
    "You can also clone the repository via the Git side tab and enter your personal access token instead of password when prompted. \n",
    "![Git Side UI](../_static/clone_demo3.png)\n",
    "\n",
    "If you want to use multiple code repositories, it’s possible to configure a repository to have multiple remotes — e.g.,\n",
    "\n",
    "To add the `maap` remote and set the URL, cd into the repo and use this:\n",
    "```\n",
    "git remote add maap https://username:AccessToken@repo.maap-project.org/username/repo_name\n",
    "```\n",
    "\n",
    "If you already have the remote called `maap` set up, you can set the remote URL using this instead:\n",
    "```\n",
    "git remote set-url maap https://username:AccessToken@repo.maap-project.org/username/repo_name\n",
    "```\n",
    "\n",
    "Then, you can use these commands to push your code and effectively synchronize between Github and MAAP GitLab (for algorithm registration):\n",
    "\n",
    "Push to Github:\n",
    "```\n",
    "git push origin <branch name>\n",
    "```\n",
    "\n",
    "Push to MAAP GitLab:\n",
    "```\n",
    "git push maap <branch name>\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initializing a new repository\n",
    "**Note** It is recommended to create a new repository on Git, then clone it and paste files in, especially if you are starting from scratch and don't have any files yet \n",
    "\n",
    "1. Navigate to the folder you would like to make a Git repository \n",
    "\n",
    "2. Click the Git sidebar\n",
    "![Git Side UI](../_static/clone_demo3.png) \n",
    "\n",
    "3. Select \"Initialize a Repository\"\n",
    "\n",
    "4. Create a new, empty repository on GitHub or MAAP GitLab instance with the same name as your folder \n",
    "\n",
    "5. Add a remote with the following code in your terminal\n",
    "```\n",
    "git remote add origin https://github.com/username/repo_name.git\n",
    "git remote set-url origin https://github.com/username/repo_name.git\n",
    "```\n",
    "\n",
    "Or if you are using MAAP GitLab\n",
    "```\n",
    "git remote add maap https://username:AccessToken@repo.maap-project.org/username/repo_name\n",
    "git remote set-url maap https://username:AccessToken@repo.maap-project.org/username/repo_name\n",
    "```\n",
    "\n",
    "And make code changes with \n",
    "\n",
    "```\n",
    "git add .\n",
    "git commit -m <message>\n",
    "git push --set-upstream origin <branch>\n",
    "```\n",
    "And enter classic personal access token instead of password when prompted "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Committing Changes to a Git Repository\n",
    "\n",
    "\n",
    "Before you update your project with your changes, you need to get a classic personal access token from GitHub. MAAP currently doesn't supported fine-grained tokens. Create a classic personal access token by following [these steps](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) in Developer settings. Remember to save your personal access token for later use. \n",
    "\n",
    "Jupyter notebook checkpoints bloat git unnecessarily, so you can add the following to your `.gitignore` file to prevent this:\n",
    "```\n",
    ".ipynb_checkpoints\n",
    "*/.ipynb_checkpoints/*\n",
    "```\n",
    "For more information on `.gitignore` files, see [here](https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files).\n",
    "\n",
    "Using the left side panel in the Jupyter interface, you can push changes to your Git project whether it is on the MAAP GitLab, or a public repository on GitHub. \n",
    "\n",
    "If you are more comfortable using the command line to interact with Git, you do not need to use the side panel. It will work the same way in the terminal, once you navigate to the project's filepath.\n",
    "\n",
    "When you are ready to update your project with your changes, navigate to the Git panel. Add the files you want to change to the list of staged changes by clicking the + to the right of the file name. Then write a commit message, and blue commit button. \n",
    "\n",
    "<img src=\"../_static/update_project_commit.png\"  width=\"220\" height=\"500\" alt=\"update project commit\">\n",
    "\n",
    "Now you need to push your changes by selecting the push changes button on the toolbar in the upper right.\n",
    "\n",
    "<img src=\"../_static/update_project_push.png\"  width=\"300\" height=\"150\" alt=\"update project push\">\n",
    "\n",
    "You then may be prompted for your Git username and personal access token that you got above \n",
    "\n",
    "<img src=\"../_static/update_project_git_login.png\"  width=\"600\" height=\"150\" alt=\"update project git login\">\n",
    "\n",
    "You should then see \"Successfully pushed\"\n",
    "\n",
    "If you want to check your commit history, look at branches, and confirm your updates have been pushed, you can see this on the history tab.\n",
    "\n",
    "<img src=\"../_static/update_project_history.png\"  width=\"220\" height=\"500\" alt=\"update project history\">"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.11.1 64-bit",
   "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.11.1"
  },
  "vscode": {
   "interpreter": {
    "hash": "5c7b89af1651d0b8571dde13640ecdccf7d5a6204171d6ab33e7c296e100e08a"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}