intro.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Introduction\n",
        "\n",
        "There is a a lot of git stuff out there and most of it is not intended for scientists (one of the best science focused git tutorials for R is [HappygitwithR](https://happygitwithr.com/)). Our goal to amalgamate the most common Git commands and strategies into a workflow that is helpful for ADF&G fisheries analysis.\n",
        "\n",
        "## What does Git do?\n",
        "\n",
        "Git offers a way to track changes in your analysis without requiring the analyst to create different versions of the same file. To use git an analyst **init**ializes their working directory (hopefully an R project). Files involved in the analysis (data, scripts, functions, model code) are **add**ed so that git knows to track changes associated with each file. When the analyst makes a **commit**, a snapshot of all tracked files at that specific point in time are recorded along with a message describing the commit and an automatically assigned a unique identifier. The analyst can also **tag** important commits. Because you can **checkout** prior commits this system allows for traditional file versioning with a structured system while ensuring the all commits are documented and the most important commits are easily identifiable.\n",
        "\n",
        "The collection of all the commits, messages, tags and identifiers associated with a projects is called a **repository**. When a repository is created on your computer or private/company network it is **local**. An analyst can **push** a local repository to a **remote** repository (stored on the cloud). Alternatively, the analyst can **pull** a remote repository to their computer or private/company network to either create or update a local repository. Because multiple local repositories can push and pull to the same remote repository Git allows collaboration between analysts while maintaining the documentation and unique identifiers associated with each commit. Github is the most popular hosting service facilitating these collaborative features of git.\n",
        "\n",
        "## How do I interact with Git?\n",
        "\n",
        "One problem with widespread adoption of Git at ADF&G is that there is no accepted standard for how to interact with Git. The options are a GUI (graphical user interface) or a command line interface (terminal). Herein, we will focus on how to use Git while interacting through the terminal. We make this choice for 3 reasons. First, because the terminal is a command line interface it is easy to demonstrate the exact steps that were taken to achieve each outcome. This presentation is more concrete than a parade of screenshots. A second issue is that there are a lot of GUIs out there. I will include an appendix which shows how to do the most common Git functions in RStudio. While not a particuarly good Git GUI the RStudio interface is sufficient for most tasks and readily available for most readers of this book. If you have a GUI you highly recommend we welcome your input. Please fork the repository associated with this book, add an appendix with instructions for your prefered GUI and submit a pull request... instructions on how to do so are included in the chapter on collaboration. A final reason to use command line in the context of this book is that the terminal commands are commonly described in Stack Overflow if you Google how to accomplish a task in Git. Rest assured, I don't use the terminal to interact with Git the majority of the time[^intro-1] and I don't recommend you do either. But I do think you will end up there eventually, that the terminal has pedagogical advantages and that if you can use the terminal the GUI's are easier to understand.\n",
        "\n",
        "[^intro-1]: I generally use the RStudio GUI first, the terminal when the RStudio GUI is not sufficient and Git Kraken when I have a lot of branches to visualize/review.\n",
        "\n",
        "In order to use the terminal effectively it helps to make one change to the Rstudio defaults by executing the following point and click commands: *Tools\\>Terminal\\>Terminal Options...\\>(change initial directory to 'project directory')*. This change will ensure your terminal opens in the correct directory and save some unnecessary terminal prompts.\n",
        "\n",
        "## Conventions used in this book\n",
        "\n",
        "Throughout this document you will find code blocks which show the command line prompt, the command given, and the result received for each action demonstrated. Code blocks are identifiable by a grey bar along the left hand margin. In the terminal, each command line prompt (\\$) is proceeded by the username, shell type, and directory location. In the terminal session below we can see that the username was amreimer\\@DFGSXQDSF206801, the shell type was MING64 and the directory location was S:/RTS/Reimer/Research_Best_Practices/git_practice.\n",
        "\n",
        "\n",
        "```{default, engine: knitr}\n",
        "#| engine: knitr\n",
        "amreimer@DFGSXQDSF206801 MINGW64 /s/RTS/Reimer/Research_Best_Practices/git_practice\n",
        "$\n",
        "```\n",
        "\n",
        "\n",
        "When point and click sequences are referenced in this text button names will be shown in *italic*, button names in series will be separated by and the greater than symbol (\\>) and any actions required will be described in (*italics* *enclosed in parenthesis*). For an example see the last paragraph of the preceding section.\n",
        "\n",
        "When git commands are referenced in the text they will be displayed as an `inline code block`. R objects and Git branches are also referenced as `inline code blocks`."
      ],
      "id": "65fa3edd"
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}