diff --git a/NEWS.md b/NEWS.md index ca2fd3f..b47509a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -5,6 +5,7 @@ This reflects the current state of the repository. Changes from the preceding ve - Added Zenodo DOI and full workshop citation to README and homepage of workshop - Clarified GitHub 'by itself' versus 'with an IDE' and made minor edits to both original topics in service of making this distinction clear - Tweaked sidebar to make a new 'background' section to house the workflows module and some of the Git-specific background that previously was the start of what is now called the 'GitHub by itself' module +- Overhauled all IDE-related tutorials to use new, more clear images and explanatory text for both RStudio and Positron ## Version 1.3 diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json index cee8102..d7fb413 100644 --- a/_freeze/index/execute-results/html.json +++ b/_freeze/index/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "34057b3efdeb32051e063b60fbe52d7a", + "hash": "c45c3aad4238eb66602604674cf2641c", "result": { "engine": "knitr", - "markdown": "---\ntitle: \"Overview\"\n---\n\n### Welcome!\n\n\"Logo\n\nThis workshop provides an overview of what \"version control\" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using GitHub either by itself or with Git via RStudio**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement! \n\n### Citing These Materials\n\nIf you'd like to cite these materials, please use the following citation:\n\n> Lyon, N.J., Chen, A., and Brun, J. (2025). Collaborative Coding with GitHub (v1.3). Zenodo. [https://doi.org/10.5281/zenodo.16966957](https://doi.org/10.5281/zenodo.16966957)\n\n## Workshop Preparation\n\nTo maximize the value of this workshop to you, **we recommend that you take the following steps before the day of the workshop**. You may have already completed some or all of these steps but please read through and confirm that you've done all of the steps that are relevant to you to ensure that all participants arrive with a common foundation of installed programs. If anything is unclear, feel free to reach out to us; our contact information can be found in the \"SciComp Team\" dropdown menu in the \"People\" page.\n\n:::{.callout-note}\n#### Institution-Owned Computers\n\nIf your institution has a dedicated IT team that has sole power to install software on your computer, you will need to contact them before the workshop to do the installation bits of the prep steps we outline below.\n:::\n\nThere are a couple of distinct use-cases you might have for GitHub that will affect what preparation you need to do before this workshop. Consider the tabs below and follow all of the numbered steps in the choice that best fits your needs.\n\n:::{.panel-tabset}\n### GitHub By Itself\n\n#### 1. Create a GitHub Account\n\nStart by creating an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools. \n\nDr. Jennifer Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.\n\n\n#### 2. Celebrate!\n\nAfter following all the previous preparation steps, your setup should now be complete.\n\n\n### GitHub with RStudio\n\n:::{.callout-note}\n#### Running Code in Following Steps\n\nThe below preparation steps includes some code for making sure everything is installed as it should be. All code is either R code ({{< fa brands r-project >}}) or is command line code ({{< fa terminal >}}). **In either case, you'll run all provided code in RStudio**. {{< fa brands r-project >}} R code should be run in the \"Console\" tab of RStudio while {{< fa terminal >}} command line code should be run in the \"Terminal\" tab of RStudio.\n\nIf you get errors with the provided code, _double check that you are running it in the right place!_\n:::\n\n#### 1. Create a GitHub Account\n\nStart by creating an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools. \n\nDr. Jennifer Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.\n\n\n#### 2. Install R\n\nNow you should [install R](https://www.r-project.org/) on your computer. If you already have R, check that you have at least version 4.0.0 by running the following {{< fa brands r-project >}} R code:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Run me in RStudio's \"Console\"\nversion$version.string\n```\n:::\n\n\nIf your version starts with a 3 (e.g., the above code returns \"R version 3...\"), please update R to make sure all packages behave as expected.\n\n\n#### 3. Install RStudio\n\nOnce you have R (ver. ≥4.0), [install RStudio](https://posit.co/download/rstudio-desktop/). If you already have RStudio installed, you may want to make sure that you're using a recent version to take advantage of some quality of life improvements that are broadly useful.\n\n\n#### 4. Install Git\n\nYou can now install Git! Git is the software that actually does the behind-the-scenes version control operations we'll cover in this workshop. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan's excellent \"[Happy Git and GitHub for the useR](https://happygitwithr.com/)\" ebook.\n\n:::{.panel-tabset}\n#### {{< fa brands apple >}} Mac\n\nRun the following {{< fa terminal >}} command line code.\n\n```\nxcode-select --install\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#macos).\n\n#### {{< fa brands windows >}} Windows\n\n[Install Git for Windows](https://gitforwindows.org/) (a.k.a. \"Git Bash\"). When asked about \"Adjusting your PATH environment\", **select \"Git from the command line and also from 3rd-party software\"**.\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#install-git-windows).\n\n#### {{< fa brands linux >}} Linux\n\nInstall Git via your distro's package manager (in the {{< fa terminal >}} Terminal).\n\nIf you use Ubuntu or Debian Linux that {{< fa terminal >}} code is as follows:\n\n```\nsudo apt-get install git\n```\n\nIf instead you use Fedora or RedHat Linux the {{< fa terminal >}} code is instead:\n\n```\nsudo yum install git\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#linux).\n\n:::\n\n\n#### 5. Check that Git's Installation Worked\n\nRegardless of your operating system, once you've installed Git, check that worked with the following {{< fa terminal >}} command line code. All operating systems should be able to run this code.\n\n```\nwhich git\n```\n\n:::{.panel-tabset}\n#### Confirm Connection in RStudio\n\nRStudio should also be able to detect Git so let's check from that side too. In RStudio click through the following menus: \"Tools\" {{< fa arrow-right >}} \"Global Options\" {{< fa arrow-right >}} \"Git / SVN\" (cardboard box icon in left sidebar). **If you see a file path under \"Git executable\" then you are good to go!**\n\nIf Git was _not_ detected, this may be caused by having your RStudio session open while you installed Git for the first time. **In that case, please close and restart RStudio before checking again.**\n\n:::\n\n\n#### 6. Connect Git and GitHub\n\nThe last step to take before you're all set for the workshop is to get these components talking to one another! You set a password for your GitHub which is used for logging in to GitHub but to actually put your code changes from your computer up to GitHub you'll need to _authenticate_ yourself. There are two paths for authentication:\n\n1. Personal Access Token (PAT)\n2. Secure Shell (SSH) \n\nWhat's the difference? Essentially, authenticating via token makes many things \"just work\" while authenticating via SSH will work for some things but in other contexts you would _also_ need to do token-based authentication. For a more complete discussion of the benefits and drawbacks of each, see Dr. Bryan's \"[HTTPS versus SSH](https://happygitwithr.com/https-pat#https-vs-ssh)\" page.\n\nFollow the steps of your chosen authentication method in the tabs below.\n\n::::{.panel-tabset}\n#### Personal Access Token with RStudio\n\n**All of the code chunks for authenticating with a token are {{< fa brands r-project >}} R code that should be run in the \"Console\" pane of RStudio.** You may also create a script and run the code from there if you so desire but you'll likely only need this code once so the script's value would be short-lived.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install the `usethis` and `gitcreds` packages\ninstall.packages(c(\"usethis\", \"gitcreds\"))\n\n# Create a token (Note this will open a GitHub browser tab)\n## See steps 6-10 in GitHub's PAT tutorial (link below)\nusethis::create_github_token() # <1>\n```\n:::\n\n1. Leave parentheses empty\n\n_Copy your token at the end of the above step._ Once you leave the page where your token is displayed you'll never get to see it again! So if you close that page without copying it you'll need to make a new one in order to continue.\n\nOnce you've copied your token, run the code below to save your credentials in RStudio.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Now, give your token to RStudio\n## After you run this line follow the prompts in the \"Console\" tab of RStudio\ngitcreds::gitcreds_set() # <2>\n```\n:::\n\n2. Leave parentheses empty here as well!\n\nThis line of code will prompt you to paste your token in the \"Console\" tab. After you do so (and hit \"Enter\"), your token will be safely stored in RStudio! \n\n##### Further Information\n\nYou may also find [GitHub's PAT tutorial](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (this is the link referenced in the first token-authentication code chunk!) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful.\n\n#### SSH\n\n**All of the code chunks for authenticating with SSH are {{< fa terminal >}} command line code that should be agnostic to your programming language.**\n\nFirst, we need to check whether you already have SSH keys created on your computer. If you get a message saying that nothing exists or the path doesn't exist, you do not (yet) have SSH keys.\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nls -al ~/.ssh/\n```\n:::\n\n\nIf you do need to create an SSH key pair you can do so via the command line. When you create a key pair you'll need to include a descriptive comment to help 'future you' if you ever have multiple key pairs in your life. We recommend \"lter\" plus your GitHub username to keep things simple.\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nssh-keygen -t ed25519 -C \"lter-github\"\n```\n:::\n\n\n:::{.callout-tip}\n#### Older Computer?\n\nIf you get a warning/error because your system is too old to support the Ed25519 algorithm (that's the variant recommended by GitHub) you can instead use:\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nssh-keygen -t rsa -b 4096 -C \"lter-github\"\n```\n:::\n\n:::\n\nAccept the prompt to save the key in the default location by hitting Enter. You will be prompted to enter a passphrase that will be required to access your SSH key later on. This step is technically optional but is considered a best practice. If SSH keys are totally new to you, we recommend skipping the passphrase step.\n\nOnce you've generated the key pair, follow [GitHub's instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent) on adding that key pair to your computer's ssh-agent (roughly equivalent to a password manager but just for SSH key pairs).\n\nFinally, you need to share the public key with your GitHub self. Once again we'll refer you to [the phenomenal materials](https://happygitwithr.com/ssh-keys#provide-public-key-to-github) generated by Dr. Bryan on this topic. \n\n##### Further Information\n\nYou may also find [GitHub's SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) or the [Happy Git with R SSH tutorial](https://happygitwithr.com/ssh-keys) helpful.\n\n::::\n\n\n#### 7. Celebrate!\n\nAfter following all the previous preparation steps, your setup should now be complete.\n\n\n:::\n\n## GitHub + Science Publications\n\nThe reproducibility and collaborative benefits of GitHub for working scientists is well appreciated and increasingly well published upon. See below for brief synopses of papers published in this realm that we think may resonate with your team's disciplinary backgrounds and motivations.\n\nIn the ecology and evolutionary biology sphere, Pereira Braga et al. published \"[Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.14108)\" in _Methods in Ecology & Evolution_. This paper is a phenomenal resource for ecologists and evolutionary biologists who are considering the value of GitHub to them in and outside of a working group context. The authors identify 12 uses of GitHub for the EEB community and arrange them by technical difficulty (ranging from beginner to advanced) and degree of collaboration (low to high). We have embedded this paper's second figure in this website below as it is a neat summarization of many of their central points. That said, we definitely recommend reading (and citing!) [Pereira Braga et al. 2023](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.14108) for more detail than we've included in this blurb.\n\nIf you are concerned about the technical side of GitHub for yourself and/or your lab group, we recommend focusing on the lower technical difficulty benefits of GitHub (see the **blue** bars). We also think that some of the intermediate technical difficulty uses (**orange** bars) may be relevant to working group priorities and goals.\n\n

\n\"Figure\n

\n", + "markdown": "---\ntitle: \"Overview\"\n---\n\n### Welcome!\n\n\"Logo\n\nThis workshop provides an overview of what \"version control\" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using GitHub either through a browser or through software installed on your computer.** We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement! \n\n### Citing These Materials\n\nIf you'd like to cite these materials, please use the following citation:\n\n> Lyon, N.J., Chen, A., and Brun, J. (2025). Collaborative Coding with GitHub (v1.3). Zenodo. [https://doi.org/10.5281/zenodo.16966957](https://doi.org/10.5281/zenodo.16966957)\n\n## Workshop Preparation\n\nTo maximize the value of this workshop to you, **we recommend that you take the following steps before the day of the workshop**. You may have already completed some or all of these steps but please read through and confirm that you've done all of the steps that are relevant to you to ensure that all participants arrive with a common foundation of installed programs. If anything is unclear, feel free to reach out to us; our contact information can be found in the \"SciComp Team\" dropdown menu in the \"People\" page.\n\n:::{.callout-note}\n#### Institution-Owned Computers\n\nIf your institution has a dedicated IT team that has sole power to install software on your computer, you will need to contact them before the workshop to do the installation bits of the prep steps we outline below.\n:::\n\nThere are a couple of distinct use-cases you might have for GitHub that will affect what preparation you need to do before this workshop. Consider the tabs below and follow all of the numbered steps in the choice that best fits your needs.\n\n::::{.panel-tabset}\n### GitHub By Itself\n\n#### 1. Create a GitHub Account\n\nStart by creating an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools. \n\nDr. Jennifer Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.\n\n\n#### 2. Celebrate!\n\nAfter following all the previous preparation steps, your setup should now be complete.\n\n\n### GitHub with RStudio\n\n:::{.callout-note}\n#### Running Code in Following Steps\n\nThe below preparation steps includes some code for making sure everything is installed as it should be. All code is either R code ({{< fa brands r-project >}}) or is command line code ({{< fa terminal >}}). **In either case, you'll run all provided code in RStudio**. {{< fa brands r-project >}} R code should be run in the \"Console\" tab of RStudio while {{< fa terminal >}} command line code should be run in the \"Terminal\" tab of RStudio.\n\nIf you get errors with the provided code, _double check that you are running it in the right place!_\n:::\n\n#### 1. Create a GitHub Account\n\nStart by creating an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools. \n\nDr. Jennifer Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.\n\n\n#### 2. Install R\n\nNow you should [install R](https://www.r-project.org/) on your computer. If you already have R, check that you have at least version 4.0.0 by looking at the \"Console\" of your IDE of choice.\n\nIf your version starts with a \"3\", please update R to make sure all packages behave as expected.\n\n\n#### 3. Install RStudio\n\nOnce you have R (ver. ≥4.0), [install RStudio](https://posit.co/download/rstudio-desktop/). If you already have RStudio installed, you may want to make sure that you're using a recent version to take advantage of some quality of life improvements that are broadly useful.\n\n\n#### 4. Install Git\n\nYou can now install Git! Git is the software that actually does the behind-the-scenes version control operations we'll cover in this workshop. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan's excellent \"[Happy Git and GitHub for the useR](https://happygitwithr.com/)\" ebook.\n\n:::{.panel-tabset}\n#### {{< fa brands apple >}} Mac\n\nRun the following {{< fa terminal >}} command line code.\n\n```\nxcode-select --install\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#macos).\n\n#### {{< fa brands windows >}} Windows\n\n[Install Git for Windows](https://gitforwindows.org/) (a.k.a. \"Git Bash\"). When asked about \"Adjusting your PATH environment\", **select \"Git from the command line and also from 3rd-party software\"**.\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#install-git-windows).\n\n#### {{< fa brands linux >}} Linux\n\nInstall Git via your distro's package manager (in the {{< fa terminal >}} Terminal).\n\nIf you use Ubuntu or Debian Linux that {{< fa terminal >}} code is as follows:\n\n```\nsudo apt-get install git\n```\n\nIf instead you use Fedora or RedHat Linux the {{< fa terminal >}} code is instead:\n\n```\nsudo yum install git\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#linux).\n\n:::\n\n\n#### 5. Check that Git's Installation Worked\n\nRegardless of your operating system, once you've installed Git, check that worked with the following {{< fa terminal >}} command line code. All operating systems should be able to run this code.\n\n```\nwhich git\n```\n\nRStudio should also be able to detect Git so let's check from that side too. In RStudio click through the following menus: \"Tools\" {{< fa arrow-right >}} \"Global Options\" {{< fa arrow-right >}} \"Git / SVN\" (cardboard box icon in left sidebar). **If you see a file path under \"Git executable\" then you are good to go!**\n\nIf Git was _not_ detected, this may be caused by having your RStudio session open while you installed Git for the first time. **In that case, please close and restart RStudio before checking again.**\n\n\n#### 6. Connect RStudio/Git and GitHub\n\nThe last step to take before you're all set for the workshop is to get these components talking to one another! You set a password for your GitHub which is used for logging in to GitHub but to actually put your code changes from your computer up to GitHub you'll need to _authenticate_ yourself. There are two paths for authentication:\n\n1. Personal Access Token (PAT)\n2. Secure Shell (SSH) \n\nWhat's the difference? Essentially, authenticating via token makes many things \"just work\" while authenticating via SSH will work for some things but in other contexts you would _also_ need to do token-based authentication. For a more complete discussion of the benefits and drawbacks of each, see Dr. Bryan's \"[HTTPS versus SSH](https://happygitwithr.com/https-pat#https-vs-ssh)\" page.\n\nFollow the steps of your chosen authentication method in the tabs below.\n\n::::{.panel-tabset}\n#### Personal Access Token with RStudio\n\n**All of the code chunks for authenticating with a token are {{< fa brands r-project >}} R code that should be run in the \"Console\" pane of RStudio.** You may also create a script and run the code from there if you so desire but you'll likely only need this code once so the script's value would be short-lived.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install the `usethis` and `gitcreds` packages\ninstall.packages(c(\"usethis\", \"gitcreds\"))\n\n# Create a token (Note this will open a GitHub browser tab)\n## See steps 6-10 in GitHub's PAT tutorial (link below)\nusethis::create_github_token() # <1>\n```\n:::\n\n1. Leave parentheses empty\n\n_Copy your token at the end of the above step._ Once you leave the page where your token is displayed you'll never get to see it again! So if you close that page without copying it you'll need to make a new one in order to continue.\n\nOnce you've copied your token, run the code below to save your credentials in RStudio.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Now, give your token to RStudio\n## After you run this line follow the prompts in the \"Console\" tab of RStudio\ngitcreds::gitcreds_set() # <2>\n```\n:::\n\n2. Leave parentheses empty here as well!\n\nThis line of code will prompt you to paste your token in the \"Console\" tab. After you do so (and hit \"Enter\"), your token will be safely stored in RStudio! \n\n##### Further Information\n\nYou may also find [GitHub's PAT tutorial](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (this is the link referenced in the first token-authentication code chunk!) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful.\n\n#### SSH\n\n**All of the code chunks for authenticating with SSH are {{< fa terminal >}} command line code that should be agnostic to your programming language.**\n\nFirst, we need to check whether you already have SSH keys created on your computer. If you get a message saying that nothing exists or the path doesn't exist, you do not (yet) have SSH keys.\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nls -al ~/.ssh/\n```\n:::\n\n\nIf you do need to create an SSH key pair you can do so via the command line. When you create a key pair you'll need to include a descriptive comment to help 'future you' if you ever have multiple key pairs in your life. We recommend \"lter\" plus your GitHub username to keep things simple.\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nssh-keygen -t ed25519 -C \"lter-github\"\n```\n:::\n\n\n:::{.callout-tip}\n#### Older Computer?\n\nIf you get a warning/error because your system is too old to support the Ed25519 algorithm (that's the variant recommended by GitHub) you can instead use:\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nssh-keygen -t rsa -b 4096 -C \"lter-github\"\n```\n:::\n\n:::\n\nAccept the prompt to save the key in the default location by hitting Enter. You will be prompted to enter a passphrase that will be required to access your SSH key later on. This step is technically optional but is considered a best practice. If SSH keys are totally new to you, we recommend skipping the passphrase step.\n\nOnce you've generated the key pair, follow [GitHub's instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent) on adding that key pair to your computer's ssh-agent (roughly equivalent to a password manager but just for SSH key pairs).\n\nFinally, you need to share the public key with your GitHub self. Once again we'll refer you to [the phenomenal materials](https://happygitwithr.com/ssh-keys#provide-public-key-to-github) generated by Dr. Bryan on this topic. \n\n##### Further Information\n\nYou may also find [GitHub's SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) or the [Happy Git with R SSH tutorial](https://happygitwithr.com/ssh-keys) helpful.\n\n::::\n\n\n#### 7. Celebrate!\n\nAfter following all the previous preparation steps, your setup should now be complete.\n\n\n### GitHub with Positron\n\n:::{.callout-note}\n#### Positron vs. Visual Studio Code\n\n[Visual Studio Code](https://code.visualstudio.com/) (a.k.a. VS Code) is an IDE favored by many software developers. Positron itself is actually a \"fork\" of VS Code's software! However, Positron offers some additional functionalities to support R users and--given that most working group members are primarily R coders if they code--Positron is what we will be using in this workshop.\n\nHowever, if you are a VS Code user, much of the Positron content will actually work for you with some (or potentially _no_) adjustment.\n:::\n\n#### 1. Create a GitHub Account\n\nStart by creating an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools. \n\nDr. Jennifer Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.\n\n\n#### 2. Install R\n\nNow you should [install R](https://www.r-project.org/) on your computer. If you already have R, check that you have at least version 4.0.0 by looking at the \"Console\" of your IDE of choice.\n\nIf your version starts with a \"3\", please update R to make sure all packages behave as expected.\n\n \n#### 3. Install Positron\n\nOnce you have R (ver. ≥4.0), [install Positron](https://positron.posit.co/). If you already have Positron installed, you may want to make sure that you're using a recent version to take advantage of the features available in the most recent version.\n\n\n#### 4. Install Git\n\nYou can now install Git! Git is the software that actually does the behind-the-scenes version control operations we'll cover in this workshop. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan's excellent \"[Happy Git and GitHub for the useR](https://happygitwithr.com/)\" ebook.\n\n:::{.panel-tabset}\n#### {{< fa brands apple >}} Mac\n\nRun the following {{< fa terminal >}} command line code.\n\n```\nxcode-select --install\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#macos).\n\n#### {{< fa brands windows >}} Windows\n\n[Install Git for Windows](https://gitforwindows.org/) (a.k.a. \"Git Bash\"). When asked about \"Adjusting your PATH environment\", **select \"Git from the command line and also from 3rd-party software\"**.\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#install-git-windows).\n\n#### {{< fa brands linux >}} Linux\n\nInstall Git via your distro's package manager (in the {{< fa terminal >}} Terminal).\n\nIf you use Ubuntu or Debian Linux that {{< fa terminal >}} code is as follows:\n\n```\nsudo apt-get install git\n```\n\nIf instead you use Fedora or RedHat Linux the {{< fa terminal >}} code is instead:\n\n```\nsudo yum install git\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#linux).\n\n:::\n\n\n#### 5. Connect Positron/Git and GitHub\n\nThe last step to take before you’re all set for the workshop is to get these components talking to one another! One reason to use Positron instead of RStudio is because of how much simpler this step is for Positron. Instead of needing to write code, we can do a little authentication dance with buttons in the browser and afterwards, everything will 'just work.'\n\nTo begin, open Positron. You should have a screen that looks something like the below screen capture. Note that you might be in \"light mode\" depending on your computer settings but that should not affect which buttons to click or where they can be found.\n\n

\n\"Screen\n

\n\nFrom there, go to the left sidebar and click the branch icon ( {{< fa code-branch >}} ). It should be the third option from the top. Once you are there, **click \"Clone Repository\".**\n\n

\n\"Screen\n

\n\nThis should automatically open the search bar in the top middle of Positron and present you with a single option titled \"Clone from GitHub\". **Click that option.**\n\n

\n\"Screen\n

\n\nOnce you've clicked that option, you should be presented with the following pop up where Positron is telling you that Positron's GitHub extension wants to talk to the online version of GitHub. **Click \"Allow\".**\n\n

\n\"Screen\n

\n\nPositron will now allow provide you with a code of random letters/numbers that you'll need to share with GitHub. Helpfully, a new pop-up will appear where one of the options is \"Copy & Continue to Github\"; **click that option.**\n\n

\n\"Screen\n

\n\nOnce you click \"Copy & Continue to Github\" button, you should automatically be sent to your default web browser application and be prompted to choose which GitHub account to use. Most users will have only one option so go ahead and **click \"Continue\" next to that profile.**\n\n

\n\"Screen\n

\n\nYou'll next need to put in the code that you got from Positron. You should be able to simply paste it in because you just copied it! **_After you've entered the code_, click \"Continue\".**\n\n

\n\"Screen\n

\n\nGitHub will now provide you with a list of the permissions that Positron is asking for and ask you to approve them. These permissions are required for you to work with Positron so feel free to read through them but ultimately you must scroll down and **click \"Authorize\".**\n\nIf you are a member of any GitHub organizations, they will be listed below the list of requested permissions but you should just ignore those and scroll past them.\n\n

\n\"First\n\"Second\n

\n\n:::{.callout-note}\n#### GitHub Login Prompt\n\nIf you have not recently logged in to GitHub, you will be sent to the standard GitHub login page. If you are sent there, log in as normal (i.e., either by using your username/password or with the 2FA option provided by the GitHub Mobile app).\n:::\n\nOnce you've worked through the above step, you should get a confirmation page from GitHub that looks like the following screen capture.\n\n

\n\"Screen\n

\n\nYou will know that you've followed these steps correctly if, when you return to Positron, the search bar in the top middle (that said \"Clone from GitHub\" before) now has a list of repositories to which you have access.\n\n

\n\"Screen\n

\n\n\n#### 6. Celebrate!\n\nAfter following all the previous preparation steps, your setup should now be complete.\n\n\n::::\n\n## GitHub + Science Publications\n\nThe reproducibility and collaborative benefits of GitHub for working scientists is well appreciated and increasingly well published upon. See below for brief synopses of papers published in this realm that we think may resonate with your team's disciplinary backgrounds and motivations.\n\nIn the ecology and evolutionary biology sphere, Pereira Braga et al. published \"[Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.14108)\" in _Methods in Ecology & Evolution_. This paper is a phenomenal resource for ecologists and evolutionary biologists who are considering the value of GitHub to them in and outside of a working group context. The authors identify 12 uses of GitHub for the EEB community and arrange them by technical difficulty (ranging from beginner to advanced) and degree of collaboration (low to high). We have embedded this paper's second figure in this website below as it is a neat summarization of many of their central points. That said, we definitely recommend reading (and citing!) [Pereira Braga et al. 2023](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.14108) for more detail than we've included in this blurb.\n\nIf you are concerned about the technical side of GitHub for yourself and/or your lab group, we recommend focusing on the lower technical difficulty benefits of GitHub (see the **blue** bars). We also think that some of the intermediate technical difficulty uses (**orange** bars) may be relevant to working group priorities and goals.\n\n

\n\"Figure\n

\n", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/_freeze/prep-steps/connect_git-github/execute-results/html.json b/_freeze/prep-steps/connect_git-github_rstudio/execute-results/html.json similarity index 100% rename from _freeze/prep-steps/connect_git-github/execute-results/html.json rename to _freeze/prep-steps/connect_git-github_rstudio/execute-results/html.json diff --git a/_freeze/prep-steps/install_r/execute-results/html.json b/_freeze/prep-steps/install_r/execute-results/html.json deleted file mode 100644 index ecc422b..0000000 --- a/_freeze/prep-steps/install_r/execute-results/html.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "hash": "bda4e5977ee4b3aa942b7fdbd5575fca", - "result": { - "engine": "knitr", - "markdown": "Now you should [install R](https://www.r-project.org/) on your computer. If you already have R, check that you have at least version 4.0.0 by running the following {{< fa brands r-project >}} R code:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Run me in RStudio's \"Console\"\nversion$version.string\n```\n:::\n\n\nIf your version starts with a 3 (e.g., the above code returns \"R version 3...\"), please update R to make sure all packages behave as expected.\n", - "supporting": [], - "filters": [ - "rmarkdown/pagebreak.lua" - ], - "includes": {}, - "engineDependencies": {}, - "preserve": {}, - "postProcess": true - } -} \ No newline at end of file diff --git a/_quarto.yml b/_quarto.yml index 869420f..a85cfce 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -28,15 +28,15 @@ website: - section: "Using GitHub..." contents: - text: "With a Browser" - href: github.qmd + href: browser.qmd - text: "With an IDE" - href: rstudio.qmd + href: ide.qmd - section: "Advanced Topics" contents: - conflicts.qmd - branches.qmd - forks.qmd - - git_ignore.qmd + - git-ignore.qmd - section: "Project Management" contents: - issues.qmd diff --git a/branches.qmd b/branches.qmd index 506d84d..4cbb1ff 100644 --- a/branches.qmd +++ b/branches.qmd @@ -12,7 +12,7 @@ By the end of this module, you will be able to: ## What is a Branch? -A **branch** is essentially a working environment in your Git repository that is separate from your main working area. This can be incredibly useful when you have a task to work on but you don't want to risk damaging the version of your code that already works. Note that "branch" can be either a noun or a verb as with many of the Git vocabulary words discussed earlier (e.g., "commit", "push", etc.). +A **"branch"** is essentially a working environment in your Git repository that is separate from your main working area. This can be incredibly useful when you have a task to work on but you don't want to risk damaging the version of your code that already works. Note that "branch" can be either a noun or a verb as with many of the Git vocabulary words discussed earlier (e.g., "commit", "push", etc.). Branches are typically created with **the intent to put the work in the branch back into the main branch when you are done with it.** Implicit in that rationale is the fact that most branches are created with a specific task/sub-task in mind and known to be temporary from the outset. @@ -20,13 +20,13 @@ As an example, imagine that you want to put a better engine in your car but you Even if you think you've never worked with Git branches you actually have! All Git repositories actually start in a branch named "main" so even if you've never intentionally created a branch, you've been working in your "main" branch all along. -## Brief Overview of Branch Workflow +## Branch Workflow Overview Before diving into the specifics of how to use branches while working with Git, let's take a look at a general overview of that process. As with many other Git operations, the first thing to do is **pull** from GitHub to your local repository to ensure that you're working with the most up-to-date version of everything in the repo (see **Step 1** below). -Once that is done, you can create a branch on your local machine (automatically shifting your RStudio project into that new branch). Doing this on your machine also updates GitHub to show that there are multiple branches (see **Step 2** below). +Once that is done, you can create a branch on your local machine. This will automatically shift your IDE into that new branch. Doing this on your machine also updates GitHub to show that there are multiple branches (see **Step 2** below). Once you have created a branch you can work in it locally (and via GitHub directly) as you would normally. You can **edit** your files locally, **commit** those changes, **pull** from GitHub (within the branch), and **push** to GitHub (see **Steps 3-4** below). @@ -41,142 +41,241 @@ However, deletion of the branch either locally or via GitHub **must** come *afte As you can see from the above text and the below diagram, branches have a few more moving parts than the Git and GitHub operations we've discussed so far. That said, they can be a powerful tool in service of collaborative work because you can have multiple branches active at the same all working on separate tasks. This approach can be an easy (or at least eas*ier*) workflow for working together while avoiding conflicts (again, see "Appendix A: Conflicts").

-Graphic demonstrating the process of using brances on a Git/GitHub repository. Essentially you pull the latest changes before making a branch, then make the branch and work in it. Once you're happy with your progress, you can submit a pull request to merge your work back into the 'main' branch and then you delete your branch +Graphic demonstrating the process of using brances on a Git/GitHub repository. Essentially you pull the latest changes before making a branch, then make the branch and work in it. Once you're happy with your progress, you can submit a pull request to merge your work back into the 'main' branch and then you delete your branch

Now we've gone over this big picture overview, let's walk step-by-step through creating, working in and ultimately merging branches! ## Create a Branch -Before you create a branch, **pull** from GitHub as a precaution so that you are certain your local repository has the most up-to-date content. +**_Before_ you create a branch, pull from/sync with GitHub** as a precaution so that you are certain your local repository has the most up-to-date content. Failing to do so is a recipe for a brutal merge conflict when you are finished with your banch and want to merge it back into the main flow of your repository. -That done, click the **purple** button in the Git tab of RStudio that shows two rectangles connected by a diamond at right-angles from one another. +:::{.panel-tabset} + +### In RStudio + +To create a branch, click the **purple** button in the "Git" tab of RStudio that shows two rectangles connected by a diamond at right-angles from one another.

-Screenshot of the set of buttons in RStudio's Git pane +Screen capture of RStudio

-In the resulting dialogue box, give your new branch an informative name. In this example we haven't given our new branch a great name but in a "real" repository you will greatly appreciate having concise but descriptive branch names. - -Once you're happy with the name, click "**Create**" (you can ignore the other options and buttons on this dialogue box). +In the resulting dialogue box, **give your new branch an informative name.** In this example we haven't given our new branch a great name but in a "real" repository you will greatly appreciate having concise but descriptive branch names. Once you're happy with the name, **click the "Create" button** (you can ignore the other options and buttons on this dialogue box).

-Screenshot of the menu that opens when you click the purple 'create branch' button in RStudio. Includes a text field for the branch name as well as a some other checkboxes/options (that can be safely left at their default settings in many cases) +Screenshot of the menu that opens when you click the purple 'create branch' button in RStudio. Includes a text field for the branch name as well as a some other checkboxes/options (that can be safely left at their default settings in many cases)

This will create a confirmation message that is superficially similar to the format of messages returned by other Git actions.

-Screenshot of the text returned when you create a branch in RStudio +Screenshot of the text returned when you create a branch in RStudio

-You will also notice that in your Git tab where previously it said "main" it now shows whatever name you chose for your branch. +You may also notice that in your Git tab where previously it said "main" it now shows whatever name you chose for your branch. + +### In Positron + +To begin, **go to the "source control" section of Positron.**

-Screenshot of RStudio's Git pane where it can be seen that the branch name has changed to the new branch created earlier +Screen capture of Positron

+To create a branch, **hover over the "Changes" dropdown menu and click `...`** to expand the set of Git operations that are visible. From there, **scroll down to "Branch" and click it.** Finally, **click "Create Branch...".** + +

+Screenshot of the dropdown menu in Positron for creating a new branch +

+ +In the resulting field (top middle of Positron), **give your new branch an informative name.** In this example we haven't given our new branch a great name but in a "real" repository you will greatly appreciate having concise but descriptive branch names. Once you're happy with the name, **hit the Enter key on your computer.** + +

+Screenshot of the field in Positron where you type new branch names +

+ +Now that you've made your new branch locally, you need to send it up to GitHub. Positron calls this "Publishing" but this isn't conceptually different from any other sync/push--essentially you're just letting GitHub know that you have a branch locally that it doesn't have a record of yet. To publish the branch, **click the "Publish Branch" button.** + +

+Screenshot of the Positron 'source control' pane where the 'Publish Branch' button is active +

+ +You'll know that this worked when you look at the branch diagram in the bottom left corner of Positron's source control menu. Note how the second commit from the top has the "origin/main" label while the top-most one has the label that matches whatever you named your new branch. + +

+Screenshot of the Positron 'source control' pane after a new branch has been published +

+ +::: + ## Work in the Branch -You can now work in a branch *in the same way* that you work with GitHub via RStudio when you are not using branches. +You can now work in a branch *in the same way* that you work with GitHub via your IDE of choice when you are not using branches. 1. Make **edits** 2. **Commit** changes locally 3. **Pull** from GitHub to reduce the chances of a conflict 4. **Push** your committed changes to GitHub -The reason you use the same workflow is--as previously stated--even if you don't typically use branches, all work in Git is functionally done in the "main" branch of your repository. +The reason you use the same workflow is--as previously stated--even if you don't typically use branches, all work in Git is functionally done in the "main" branch of your repository so your work in this new branch should use the same order of operations as work done in the "main" branch. -For a more in-depth review of the RStudio-GitHub workflow, see Chapter 3: Using GitHub via Rstudio +## Merging Branches -## Closing a Branch +When you are done with your work in the branch, you will want to merge your new branch with the "main" branch of the repository. This branch merging is most easily done via GitHub so the following instructions are agnostic to IDE and purposefully exclude the repository name from the screen capture area. To start, **push/sync your final commit(s) from your local branch with GitHub.** -Once you've completely finished working in your branch, **push** your work (if your local files are ahead of the GitHub versions) and go to your repository's GitHub page. +### Open & Merge a Pull Request -On that page GitHub will helpfully have created a button at the top of the screen notifying you that your branch had recent pushes and will offer a green button to "Compare & pull request". +After you push/sync your changes, GitHub should recognize this and automatically create a button at the top of your repository's home page for you to start the process of creating a "pull request." Pull requests are how you merge branches on GitHub and the entire process is conducted entirely in the browser so we'll leave our IDEs until the pull request is completed. -Click that button. +To start the branch merging process, **click the "Compare & pull request" button**

-Screenshot of a repository in GitHub where the 'compare and pull request' button is being offered because GitHub detected a push in the branch +Screenshot of a repository in GitHub where the 'compare and pull request' button is being offered because GitHub detected a push in the branch

You will then be prompted to write a title and message for your pull request to give some broader context for what the branch does. This is especially valuable if you are not the one reviewing pull requests as this can help someone quickly familiarize themselves with what you have done. -Once you're satisfied with your title and message, click the green "Create pull request" button. +Once you're satisfied with your title and message, **click the "Create pull request" button.**

-Screenshot of GitHub when you open a pull request and are prompted to give it a title and description +Screenshot of GitHub when you open a pull request and are prompted to give it a title and description

-That done, GitHub will send you to a page that looks very much like a Github issue (see the chapter on issues). At the top is whatever title and message you just wrote when opening the pull request following by a list of all of the commits in that branch. +That done, GitHub will send you to a page that looks very much like a Github issue (see the module on issues for more detail). At the top is whatever title and message you just wrote when opening the pull request following by a list of all of the commits in that branch. -Those commits are "live" and function as hyperlinks in case you want to view how your code is preserved in GitHub. +Those commits are hyperlinks in case you want to view the specific differences to files edited in this branch. -Note also that if you realize you forgot to do something in your branch (or if someone asks you change something) you can return to RStudio and commit/pull/push and it will automatically update on the pull request. Pull requests are for merging a whole branch, not for merging just a part of the work in the branch. +Note also that if you realize you forgot to do something in your branch (or if someone asks you change something) you can return to your IDE and commit/pull/push and it will automatically update on the pull request. Pull requests are for merging a whole branch, not for merging just a part of the work in the branch. -You or your team can post messages on a pull request as needed (see the text box at the bottom of the below picture). +You or your team can also post messages on a pull request as needed (see the text box at the bottom of the below picture). -If you are ready to merge a pull request from your branch into the "main" branch click the intuitively-named green "Merge pull request" button. +If you are ready to merge a pull request from your branch into the "main" branch **click the "Merge pull request" button.**

-Screenshot of an open pull request on GitHub +Screenshot of an open pull request on GitHub

GitHub will open another text box where you can add a commit message to your acceptance of the pull request. If whoever opened the pull request was sufficiently detailed in their opening comment(s) this may not need to be terribly detailed but it can't hurt! -Once your message is written, click the green "Confirm merge" button. +Once your message is written, **click the "Confirm merge" button.**

-Screenshot of the menu that opens on GitHub when you click 'merge pull request' where you are prompted to add an optional description before clicking 'confirm merge' +Screenshot of the menu that opens on GitHub when you click 'merge pull request' where you are prompted to add an optional description before clicking 'confirm merge'

-The green 'open' buttons will change to purple and will use the "merge" icon of two streams combining. As with GitHub issues you can continue to post comments on a merged pull request if you feel it will be valuable for posterity to do so. +Your pull request has now been merged! Now we need to do some minor housekeeping in GitHub that--fortunately--GitHub makes really accessible. -GitHub will also handily create a "Delete branch" button at the bottom of the pull request's timeline. We recommend that you click it given that your branch's purpose is served and having irrelevant branches clutters your GitHub and may even cause problems if you have two similarly-named branches where one has been merged and the other has not. +### GitHub Branch Housekeeping + +Branches are meant to be short-lived and deleted once the specific purpose for which they were created has been accomplished. So, once the pull request is merged, we should **click the "Delete branch" button.** This will ensure that the number of active branches remains manageable and also will let you re-use branch names later on if you deem that necessary.

-Screenshot of a closed pull request on GitHub with a 'delete branch' button provided +Screenshot of a closed pull request on GitHub with a 'delete branch' button provided

-After you click "Delete branch" it will be replaced by a "Restore branch" button so you could always reclaim it if need be. +After you click "Delete branch" it will be replaced by a "Restore branch" button so you could always reclaim it if the deletion was premature.

-Screenshot of a pull request on GitHub after the 'delete branch' button has been clicked and replaced by a 'restore branch' button +Screenshot of a pull request on GitHub after the 'delete branch' button has been clicked and replaced by a 'restore branch' button

-Finally, return to the "Code" tab of your GitHub repository and you can see that the changes we implemented in the branch are now part of the repository's "main" branch. The branch name is displayed just above the last commit message and the first file in the repository but below the different tab names. +Finally, if we return to the home page of the repository, we can see that the most recent commit is whatever we put in the pull request text field right before we merged it.

-Screenshot of the GitHub repository after the pull request was merged showing that the most recent commit was the merging of the PR +Screenshot of a the home page of a GitHub repository where the most recent commit matches the pull request commit message from an earlier screen capture

-## Update Local Repository +### Update your Local Clone + +Now that the branches have been merged on GitHub, we need to make sure our local clone gets those updates from GitHub. This is particularly important if our IDE is still in the branch we created earlier because--now that we've deleted the branch's counterpart in Github--we'll get an error if we attempt to push from that branch. -Now that GitHub has been told to integrate your branch content with the "main" branch, you need to let RStudio know that integration has taken place! +::::{.panel-tabset} +### In RStudio -First, click the name of the branch to see all the branch names in your repository and select the "main" branch to flip your local repository over to that branch. +#### Get Updates + +First, in the top right corner of RStudio, **click the active branch name and switch to back to the "main" branch.** Note that you may want to close your open files before doing this, particularly if some files were created in the branch because they wouldn't yet exist in the "main" branch locally (you merged on GitHub with the pull request but haven't pulled those updates locally).

-Screenshot of RStudio after the branch name was clicked (in the Git pane) showing that the new branch and the 'main' branch are options +Screenshot of the Git branch dropdown menu in RStudio

-Notice though that our script went back to the pre-merge version but don't panic! +This should create a message that looks like the following image. You should **ignore the part of the message telling you that your are up to date**; you are not up to date with GitHub yet. The message is referring to the status of your local clone's version of the "main" branch. -In order to update your local version of the repository all that you need to do is click the **pull** button. This brings the content you just merged via GitHub (see above) into your local repository. +

+Screenshot of the Git message in RStudio when switching branches +

+ +Now that you're back in the "main" branch, **pull the latest changes from GitHub.** You should receive all of the commits that you just merged via pull request earlier. This will create a message that is something like the following image--though of course it will list all changed files so it may be a longer message than what is pictured below if you edited more files.

-Screenshot of RStudio after showing the original (pre-pull request) version of the script +Screenshot of the Git message in RStudio when switching branches

-You will get a success message indicating the changes to each file in the same way any other **pull** would. You can notice between this picture and the previous that the code automatically changes when the **pull** is complete. +#### Branch Housekeeping + +Now that our "main" branch is updated, we need to do the same sort of branch housekeeping that we did in GitHub after merging the pull request. In RStudio's {{< fa terminal >}} "Terminal" pane, **delete the finished branch with the following command line code.** _Remember to replace "BRANCH_NAME" with whatever you named your branch!_ + +``` +git branch -d BRANCH_NAME +``` + +Once you've deleted that branch, you'll need to "prune" your branches. The previous code deleted the local version of your branch but your IDE still 'thinks' that GitHub has an equivalent of the branch. To reduce the potential for confusion, **prune your local clone with the following command line code.** Just like branch deletion, this should code should be run in RStudio's {{< fa terminal >}} "Terminal" pane. + +``` +git remote update origin --prune +``` + +You can confirm that these two lines of code worked as expected by clicking the "main" branch name in RStudio's Git pane. The resulting dropdown of local and remote branches should only list the "main" branch under each sub-heading. + +

+Screenshot of the Git branch dropdown menu in RStudio +

+ +### In Positron + +First, in the "source control" part of Positron, **hover over the "Changes" menu and click `...`** to expand the set of Git operations that are visible. In the resulting dropdown, **scroll down and click "Checkout to...".** Note that you may want to close your open files before doing this, particularly if some files were created in the branch because they wouldn't yet exist in the "main" branch locally (you merged on GitHub with the pull request but haven't pulled those updates locally). + +

+Screenshot of the Git operations dropdown menu in Positron with the 'checkout to...' menu highlighted +

+ +This should open up a list of the available branches in the top middle of Positron. **Find the "main" branch in the list of available branches and click it.** + +

+Screenshot of the Git operations dropdown menu in Positron +

+ +Now that you're back in the "main" branch, **pull the latest changes from GitHub.** You should receive all of the commits that you just merged via pull request earlier. + +

+Screenshot of the Git operations dropdown menu in Positron with the 'pull' menu highlighted +

+ +You will know this was successful when you **look at the branch diagram at the bottom of the "source control" menu** and see that the line for your experimental branch now re-connects to the leftmost branch's line.

-Screenshot of the message in RStudio when you pull after merging a pull request on GitHub +Screenshot of the branch diagram in Positron's source control menu

-Now that you merged your branch with the main branch on GitHub and pulled that merged content down to your local version you have successfully start-to-finish used branches in your workflow. +#### Branch Housekeeping -Many branches can exist at the same time and sometimes it helpful to create a branch starting from another branch, but these special cases obey the same basic structure described above and are outside the scope of this primer. +Now that our "main" branch is updated, we need to do the same sort of branch housekeeping that we did in GitHub after merging the pull request. In Positron's {{< fa terminal >}} "Terminal" pane, **delete the finished branch with the following command line code.** _Remember to replace "BRANCH_NAME" with whatever you named your branch!_ + +``` +git branch -d BRANCH_NAME +``` + +Once you've deleted that branch, you'll need to "prune" your branches. The previous code deleted the local version of your branch but your IDE still 'thinks' that GitHub has an equivalent of the branch. To reduce the potential for confusion, **prune your local clone with the following command line code.** Just like branch deletion, this should code should be run in Positron's {{< fa terminal >}} "Terminal" pane. + +``` +git remote update origin --prune +``` + +You can confirm that these two lines of code worked as expected by clicking the "Checkout to..." button in the dropdown menu of Git operations. The resulting list of branches should only list the "main" branch under each sub-heading. + +

+Screenshot of the Git branch dropdown menu in Positron +

-That said, we recommend branches as one way to avoid conflicts when you and your collaborators want to work simultaneously in the same repository on different scripts! +:::: diff --git a/github.qmd b/browser.qmd similarity index 53% rename from github.qmd rename to browser.qmd index 081b820..c30b430 100644 --- a/github.qmd +++ b/browser.qmd @@ -14,20 +14,26 @@ By the end of this module, you will be able to: Let's navigate over to [GitHub](https://github.com/) and explore some of its features. Here is what the home screen looks like as of February 2022. +:::{.callout-note} +### GitHub Button Color + +Depending on your GitHub settings, key buttons will either be **green** or **blue.** _This has no functional effect_ but is mentioned here just to note that some of the screen captures in this workshop will show green buttons while others have blue buttons. +::: +

-Screenshot of the GitHub landing page when you go to 'github.com' and are not signed in +Screenshot of the GitHub landing page when you go to 'github.com' and are not signed in

Log in with your GitHub account that you should have created prior to this workshop.

-Screenshot of the pop-up that appears when you click 'sign in' on GitHub +Screenshot of the pop-up that appears when you click 'sign in' on GitHub

Once you've logged in, you should see something like this:

-Screenshot of GitHub home page after you've signed in +Screenshot of GitHub home page after you've signed in

This landing page has a nice summary of your recent repositories and activity on the left panel. Click on your icon at the top left corner and navigate to your profile. @@ -36,29 +42,28 @@ This landing page has a nice summary of your recent repositories and activity on Your profile page shows the organizations that you're a part of, as well as a more detailed view of your GitHub contributions/activities over time. There are also tabs at the top that lead you to your repositories, projects, packages, and starred repositories. -

-Screenshot of the landing page on a particular GitHub profile +Screenshot of the landing page on a particular GitHub profile

If you would like, you can change your GitHub theme to dark mode by clicking on your icon at the top left corner and going to **Settings** then **Appearances**. For the purposes of this workshop, the rest of the screenshots for the GitHub website will be in dark mode to differentiate it from RStudio.

-Screenshot of the 'appearance' section of a GitHub user's settings area +Screenshot of the 'appearance' section of a GitHub user's settings area

If there is anything else you would like to change about your account, the user settings page should have it. ## Looking at a GitHub Repository -To check the repositories that you've created, click on the **Repositories** tab. Note that the top left corner has a green button that will allow you to create new repositories. We will come back to that later. +To check the repositories that you've created, click on the **Repositories** tab. Note that the top left corner has a green button that will allow you to create new repositories. We will come back to that later. ### Repository Content & Structure Let's take a closer look at what the ucsb-ds-capstone-2021.github.io repository contains.

-Screenshot of the 'repositories' tab of a user on GitHub +Screenshot of the 'repositories' tab of a user on GitHub

This screen shows the copy of a repository stored on GitHub, @@ -66,19 +71,19 @@ with its list of files, some information on who made the most recent changes.

-Screenshot of the landing page for a particular repository. A blue rectangle surrounds the information about the most recent commit, a green box surrounds the 'last modified' date for all files in the repository (on the right side of the page), and a red box surrounds the the file and folder names (left side of the page) +Screenshot of the landing page for a particular repository. A blue rectangle surrounds the information about the most recent commit, a green box surrounds the 'last modified' date for all files in the repository (on the right side of the page), and a red box surrounds the the file and folder names (left side of the page)

If we look at the blue rectangle, we can see that there have been 151 commits made to this repository. By clicking on them, we can see the history of changes made to all of the files. Looks like 3 users were making changes in April.

-Screenshot of the commit history of a single repository. Shows a list of commits in reverse chronological order (i.e., most recent on top) along with their dates and their respective commit messages +Screenshot of the commit history of a single repository. Shows a list of commits in reverse chronological order (i.e., most recent on top) along with their dates and their respective commit messages

And finally, if we examine one of the changes made on April 25, we can see exactly what was changed in each file:

-Screenshot of the changes made to a single file in one commit. Added lines are in green while deleting lines are in red +Screenshot of the changes made to a single file in one commit. Added lines are in green while deleting lines are in red

The red lines have been deleted while the green lines are new additions. Tracking these changes, and seeing how they relate to released versions of software and files is exactly what Git and GitHub are good for. We will show how they can really be effective for tracking versions of scientific code, figures, and manuscripts to accomplish a reproducible workflow. @@ -88,65 +93,68 @@ The red lines have been deleted while the green lines are new additions. Trackin It is possible to edit and add files entirely on the GitHub website, by navigating to the specific file or repository. To edit an existing file, simply navigate to the file you want to edit (in GitHub), and click the pencil icon above and to the right of the file's contents.

-Screenshot of a file being viewed in GitHub with a yellow circle around the pencil icon on the top right corner of the file. The pencil has a hovering message above it labeled 'edit this file' +Screenshot of a file being viewed in GitHub with a yellow circle around the pencil icon on the top right corner of the file. The pencil has a hovering message above it labeled 'edit this file'

To add a file, go to the home page of the repository and click the "Add file" dropdown (just to the left of the blue "Code" button) and choose the option that fits your needs. Note that you can only make new files in the 'top level' of the repository or in an existing folder so if you need to make a new folder, you'll need to embrace using GitHub with an IDE (Integrated Development Environment).

-Screenshot of a GitHub repository landing page where the 'add file' button has been clicked and a yellow circle surrounds the 'create new file' and 'upload files' buttons in the sub-menu that action created +Screenshot of a GitHub repository landing page where the 'add file' button has been clicked and a yellow circle surrounds the 'create new file' and 'upload files' buttons in the sub-menu that action created

## Creating a Repository on GitHub You can start the process of making a repository in GitHub. In fact, even if you plan on using GitHub via an IDE (e.g., RStudio, Visual Studio Code, Positron), **we recommend starting the repository in GitHub before continuing to work in your IDE of choice.** -In order to create a new repository, navigate to your profile page and click on the **Repositories** tab. Once you are there, click the **New** button in the upper right corner. +In order to create a new repository, navigate to your profile page and click on the **"Repositories"** tab. Once you are there, click the **"New"** button in the upper right corner.

-Screenshot of the 'repositories' landing page of a particular GitHub user +Screenshot of the 'repositories' landing page of a particular GitHub user

You will now be prompted to do some setup tasks before the repository can be created. First, choose a descriptive name for your new repository, here we named it `git-practice` but generally you'll want a name that is short while still being descriptive so you can identify its purpose at a glance. Also, it is good practice to avoid uppercase letters and use `-` or `_` instead of spaces. -Once you've named your repository, write a 1-sentence description about the repository content. Choose **Public**–this will prevent some easily avoidable access issues down the line. +Once you've named your repository, write a 1-sentence description about the repository content. **Choose Public**–this will prevent some easily avoidable access issues down the line. -Finally, check the box next to "**Add a README file**". This will create a nice file in the top-level of the repository that you can use for high-level documentation. That is extremely useful as a home for any explanation that the repository needs in order to be intelligible to 'future you' or your collaborators. +Finally, **click the toggle next to "Add README"**. This will create a nice file in the top-level of the repository that you can use for high-level documentation. That is extremely useful as a home for any explanation that the repository needs in order to be intelligible to 'future you' or your collaborators. Note that you may want to also add a `.gitignore` using the GitHub template for the code language that you plan to use (see the dropdown menu). This file is described in greater detail elsewhere in this workshop but essentially it is a list of files and folders that you _don't_ want Git to track or that you don't want to upload to GitHub. The coding language templates mostly start by excluding machine-readable files that you don't care about but that your IDE needs to function. +Once you're happy with the details of your new repository, **click "Create repository".** +

-Screenshot of the page on GitHub that appears when you click 'new repository'. Contains empty dialogue fields for the repository name and description as well as options for public versus private repositories among other initialization options +Screenshot of the page on GitHub that appears when you click 'new repository'. Contains empty dialogue fields for the repository name and description as well as options for public versus private repositories among other initialization options +Screenshot of the page on GitHub that appears when you click 'new repository'. Contains empty dialogue fields for the repository name and description as well as options for public versus private repositories among other initialization options

Yay! We've just created a new repository! Here is what the landing page should look like:

-Screenshot of a new repository containing only a README file +Screenshot of a new repository containing only a README file

-This repository is currently public, so it's visible to anyone, but since we are working in groups, we will need to give access to your group members. Click on the **Settings** tab for your repository and go to **Collaborators**. +This repository is currently public, so it's visible to anyone, but since we are working in groups, we will need to give access to your group members. Click on the **"Settings"** tab for your repository and go to **"Collaborators"** in the left sidebar (second from the top).

-Screenshot of the 'settings' pane of the new repository shown in the prior image +Screenshot of the 'settings' pane of the new repository shown in the prior image

-Click on **Add people**. Now let's get the usernames of all of your group members and add them as collaborators to your repository. +**Click on "Add people"** to empower your collaborators to edit things on this GitHub repository. That the repository is "public" only means that anyone with the link can _see_ what's in it; the repository owner must specifically grant edit access to the GitHub profiles that should have it. -

-Screenshot of the dialogue box prompting the viewer to enter names or emails of people to add as collaborators -

+In the resulting pop-up box (see below), type in each collaborator's GitHub username and select them when they appear in the list.

-Screenshot of the confirmation message to add a collaborator once they've been selected based on their username or email +Screenshot of the dialogue box prompting the viewer to enter names or emails of people to add as collaborators

+:::{.callout-note} +### Importance of GitHub Profile Picture + +This is why it's important to add a distinctive image to your GitHub profile! It helps whoever is adding collaborators to a given repository know that they're adding the right people. +::: + Great! Now everyone in the group should receive an invite to access that repository. The invite expires in 24 hours so be sure to send the invite during normal working hours and consider also emailing your team members to let them know they have a time-sensitive invite in whichever email inbox is tied to their GitHub account. ### Practice: Create Your Own Repository -:::callout-note -## Practice - -Now that we've walked through how to create a repository on GitHub let's try to make our own! Click over to GitHub and create your own repository (with a README.md). We'll split into breakout groups to try this out and please let us know if any questions come up. -::: +Now that we've walked through how to create a repository on GitHub let's try to make our own! Click over to GitHub and create your own repository (with a README!). We'll split into breakout groups to try this out and please let us know if any questions come up. diff --git a/conflicts.qmd b/conflicts.qmd index 54501d9..b45f4ed 100644 --- a/conflicts.qmd +++ b/conflicts.qmd @@ -10,132 +10,135 @@ By the end of this module, you will be able to: - Explain how to avoid merge conflicts - Summarize what to do if a merge conflict occurs -## What is a Merge Conflict? +## Merge Conflict Definition -Merge conflicts are a normal part of the Git workflow so don't get discouraged when you run into them! They occur when Git cannot figure out how to automatically merge new changes together. This can happen when you and your collaborators change the same lines in the same file without first pulling the changes that the other party has made. +Merge conflicts (a.k.a. "conflicts") are a normal part of the Git workflow so _don't get discouraged when you run into them!_ **They occur when Git cannot figure out how to automatically merge new changes together.** The most common cause of a merge conflict is when you and a collaborator both edit the same lines in the same file and one of you pushes without first pulling the most recent version from GitHub. -## Brief Overview of Merge Conflict Workflow +For a visual demonstration of this, see the graphic below. Note that though this has visual similarity to the workflow diagrams that can be found throughout this website we do not recommend intentionally causing a merge conflict {{< fa face-laugh-wink >}} -So the basic steps to resolving a merge conflict using RStudio are as follows: - -1. When a conflict happens, your local file will automatically be modified to include both possible lines (wrapped in some formatting characters described in greater detail below) - -2. Edit the lines in your file(s) that caused the merge conflict to your desired status +

+Graphic of three vertical rectangles, the left and right ones labeled 'you' and 'other' while the center has a happy cloud emoji. Both side rectangles pull a given file from Github then edit that file in different ways. The first person is able to successfully push without issue but the second person to push gets a conflict +

-3. **Commit** those changes +## General Conflict Resolution Strategy -4. **Push** your changes to GitHub +If you encounter a conflict, Git will combine your local version of the conflicted file with its equivalent in GitHub. In order to resolve the conflict, you'll need to manually tweak the local file(s) to decide what the script should look like then commit/push that file as normal. We can see those steps visually in the following workflow diagram:

-Graphic indicating the process of resolving a conflict when one occurs. After the initial conflict (caused when pushing a file from your machine differs from the GitHub version of that file), the combined file is auto-generated on your machine and you must then resolve the changes manually. These changes can then be committed and pushed up to GitHub +Graphic indicating the process of resolving a conflict when one occurs. After the initial conflict (caused when pushing a file from your machine differs from the GitHub version of that file), the combined file is auto-generated on your machine and you must then resolve the changes manually. These changes can then be committed and pushed up to GitHub

-## How Merge Conflicts Happen +## Fixing Conflicts + +In order to make this discussion more grounded, we will demonstrate how a conflict can be repaired after one has been encountered. For context, the conflict shown below was caused by editing a file on GitHub (`lyon-script.r`), then editing the same line of that same file locally in our IDE and pushing _without_ pulling first. **If we had pulled before committing our local change, there would be no conflict!** -Below is a common scenario that can lead to merge conflicts and then the steps to address a conflict when it occurs. +::::{.panel-tabset} +### In RStudio -Let's say we have a repository that we've shared with a collaborator. Currently there's a `README.md` and only one script, `test-script.R`, in it. +After we attempt to push our local commit in RStudio, we get an intimidating dialog that looks like the following image. If we look at the lines of that message that start with `hint: ` you can see that RStudio is warning us about why the push failed and how to go about fixing it in reasonably human-readable terms.

-Screenshot of a simple GitHub repository containing only a single script and a README +Screen capture of RStudio message warning about a merge conflict

-`test-script.R` contains one line. Suppose we want to work on this script and add more lines to it. +Let's follow RStudio's advice and **pull the latest changes from GitHub.** This will cause another scary dialog about how the 'automatic merge' failed but this means we are on the road to a resolution.

-Screenshot of a script with a single comment line +Screen capture of RStudio message warning about post-merge conflict auto-merge failure

-Let's go commit our edits. The green lines highlight the fact that we've added two new lines to our script, lines 2 and 3. We type out our commit message, and click **Commit**. +If we look at the offending file, we'll see a horrible-looking chimera file of the version we had locally versus what it looked like on GitHub before we attempted to push. You will see that Git inserted a line of `<<<<`, `====`, and `>>>>` to encapsulate the version of the original lines we had locally versus what was on GitHub respectively.

-Screenshot of a staged file with a commit message where a vector of bird names is being added +Screen capture of RStudio where a conflicted file has been auto-merged by GitHub

-Great! The message "Your branch is ahead of 'origin/main' by 1 commit" lets us know that everything is proceeding smoothly. Suppose that we decided to take a break and stepped away from our computer. +:::{.callout-note} +#### Finding Conflicts in Long Scripts -

-Screenshot of RStudio after a successful commit -

+These weird special lines can make finding merge conflicts in longs scripts _much_ easier! Simply use your IDE's search function to look for four `<<<<` next to one another as it is unlikely such a line would normally be included in your code. +::: + +Once Git has combined the two versions of the file, **it is up to us to read through the script and edit it so that it looks right to us.** At a minimum, this involves deleting the weird lines (in the screen capture below they are liens 1, 5, and 8) but in more difficult cases you may need to consider which version of the line is the one you want to retain. -Then, unbeknownst to us, our collaborator made their edits to the same script and committed and pushed their changes to the GitHub repository. At the moment, here is what the shared repository looks like. +In this case, we can retain both lines of code without damaging either so let's just delete the special character lines.

-Screenshot of the earlier GitHub repository where someone has made edits to the script +Screen capture of a script in RStudio where the merge conflict lines have been removed

-When we get back to our computer, we're ready to **push** our changes to GitHub, but an error shows up. Basically, it is telling us that our GitHub repository contains changes that we do not have on our local computer. To remedy this, the message suggests that we pull the changes from GitHub to our machine to catch our local machine back up. +Once you are confident you've fixed the conflict, **commit the changes you made to resolve the conflict.** This is done in the same way that you'd normally make a commit.

-Screenshot of the message you get when a push is rejected because of a conflict +Screen capture of a commit in RStudio with the message 'fixing conflict'

-After clicking **Pull**, we get a new error message: "Merge conflict in test-script.R". +Before you push, **take note that the Git pane is telling you that you are two commits ahead of 'origin/main'.** This is because both your original commit and your second commit (fixing the conflict) have yet to be pushed back up to GitHub--your first push failed because of the merge conflict. Once you've noted that, **push your changes.**

-Screenshot of the message you get when you pull after getting a conflict and Git (through RStudio) warns you that it created an automatic merge +Screen capture of a script in RStudio where the merge conflict lines have been removed

-Looking closer, the merge conflict prompted a new version of `test-script.R` to pop up. This version contains our edits and our collaborator's edits, along with the delimiter lines that start with `<<<<<<<`, `=======`, and `>>>>>>>`. Git is urging us to manually fix the conflicted lines before continuing. +Your RStudio should now look how it did before you got the conflict and you can continue working normally--hopefully having learned a lesson in proactive communication with your collaborators. -

-Screenshot of a script where there was a conflict now having rows of symbols separating the two versions of the conflicting line +

+Screen capture of RStudio with an open script

-Our file now has an **U** icon, which stands for an unresolved merge conflict. - -

-Screenshot of Rstudio's Git pane where the script with conflict now has two orange 'U' icons (for 'unresolved') -

+### In Positron -In general terms the steps that come before a merge conflict are displayed in the visual below. Note that though this has visual similarity to the workflow diagrams throughout this bookdown we do not recommend intentionally causing a merge conflict :) +After we attempt to sync our local commit in Positron, we get an intimidating warning about a merge conflict (see pop-up in the bottom right) and our script header is filled with gross special chacters in red text. -

-Graphic of three vertical rectangles, the left and right ones labeled 'you' and 'other' while the center has a happy cloud emoji. Both side rectangles pull a given file from Github then edit that file in different ways. The first person is able to successfully push without issue but the second person to push gets a conflict +

+Screen capture of Positron message warning about a merge conflict

-## Resolving Merge Conflicts +Because Positron's default Git interaction is "sync" (a combination of a push and a pull) the local version of our script and the version on GitHub have already been auto-merged by Git. This means we are on the road to a resolution. -So how do we resolve this merge conflict? We need to edit the script so that it looks like how we want it. We can either pick our lines to keep, our collaborator's lines, some combination, or something new altogether. Be sure to communicate with your collaborator to discuss exactly how it should be fixed. After merging the changes wherever appropriate, delete the delimiter lines. +If we look at the offending file, we'll see a horrible-looking chimera file of the version we had locally versus what it looked like on GitHub before we attempted to push. You will see that Git inserted a line of `<<<<`, `====`, and `>>>>` to encapsulate the version of the original lines we had locally versus what was on GitHub respectively. -

-Screenshot of the script where the special characters have been removed and the conflict has been resolved -

+:::{.callout-note} +#### Finding Conflicts in Long Scripts -Then stage, commit the changes, and push them to GitHub! +These weird special lines can make finding merge conflicts in longs scripts _much_ easier! Simply use your IDE's search function to look for four `<<<<` next to one another as it is unlikely such a line would normally be included in your code. +::: -

-Screenshot of RStudio where the once-conflicted script is being staged and committed with issues resolved -

+Once Git has combined the two versions of the file, **it is up to us to read through the script and edit it so that it looks right to us.** At a minimum, this involves deleting the weird lines (in the screen capture below they are liens 1, 5, and 8) but in more difficult cases you may need to consider which version of the line is the one you want to retain. + +Positron also helpfully provides buttons over each merge that allow us to quickly choose which version of the code we want but we could also edit the script manually. -Perfect! We've fixed the merge conflict! +In this case, we can retain both lines of code without damaging either so let's just delete the special character lines. -

-Screenshot of the success message from RStudio when a push works as desired +

+Screen capture of a script in Positron without merge conflict lines

-Let's check back on the shared repository. The latest commit shows that we've successfully pushed our changes to GitHub. +Once you are confident you've fixed the conflict, **commit the changes you made to resolve the conflict.** This is done in the same way that you'd normally make a commit. Note you will likely want to **replace the default merge conflict commit message with something that is more human-readable.**

-Screenshot of a GitHub repository with the the repaired file included +Screen capture of a commit in Positron with the message 'fixing conflict'

+Before you sync, **take note that the "Sync Changes" button is telling you that you have two changes to contribute.** This is because both your original commit and your second commit (fixing the conflict) have yet to be pushed back up to GitHub--your first push failed because of the merge conflict. Once you've noted that, **sync your changes.** +

-Screenshot of the repaired file in Github showing the latest changes +Screen capture of a script in Positron where the merge conflict lines have been removed

-Navigating to the commit history, we see that first we committed our changes, then our collaborator committed and pushed their changes, causing a merge conflict since we were editing the same lines in the same file. To resolve this, we edited those lines directly in our RStudio and committed and pushed our changes once more. Finally, the merge conflict is resolved and all the necessary changes are merged. +Your Positron should now look how it did before you got the conflict and you can continue working normally--hopefully having learned a lesson in proactive communication with your collaborators.

-Screenshot of the commit history of the GitHub repository showing where the conflict appears in the history +Screen capture of Positron with an open script

-## Tips on Avoiding Merge Conflicts +:::: + +## Avoiding Conflicts Merge conflicts aren't exactly fun, so here are some tips to avoid them: - **Communicate with your team members _often_** to avoid working on the same files at the same time! Let each other know who is working on what -- Commit frequently and in small chunks -- Try **pulling** before committing +- **Pull** early and often +- **Push your commits frequently** (always pulling before pushing!) diff --git a/forks.qmd b/forks.qmd index 691e895..7c3363a 100644 --- a/forks.qmd +++ b/forks.qmd @@ -58,11 +58,9 @@ In the top right of the repository's GitHub page there is a "Fork" button (betwe Screenshot of the top of a GitHub repository including the 'fork' button in the top right (in-line with the name of the repository)

-This redirects you to a page that is very similar to the page for creating a new repository *de novo* (see Chapter 3: Using GitHub). +This redirects you to a page that is very similar to the page for creating a new repository _de novo_. -Here you can select who you want to own the repository from a dropdown including any organizations you are a member of and your username if you want to personally own the fork. - -You can also change the repository name (though the default is to retain the same name) and add a description of your purpose for the fork. +Here you can select who you want to own the repository from a dropdown including any organizations you are a member of and your username if you want to personally own the fork. You can also change the repository name (though the default is to retain the same name) and add a description of your purpose for the fork. You may notice that in this page you do not have the option to specify public versus private or any of the 'initialize' steps (e.g., README, gitignore, or licence). Forks will inherit these settings from the repository they are forked from so they do not need to specified here. diff --git a/git-ignore.qmd b/git-ignore.qmd new file mode 100644 index 0000000..9323f85 --- /dev/null +++ b/git-ignore.qmd @@ -0,0 +1,174 @@ +--- +title: "The .gitignore" +--- + +## Module Learning Objectives + +By the end of this module, you will be able to: + +- Create a ".gitignore" in a repository using a GitHub template +- Explain the purpose of a ".gitignore" in collaborative projects +- Evaluate the content you think might warrant adding to the ".gitignore" + +## Overview + +A ".gitignore" is a file you can use to tell Git what _not_ to track. **Any file/folder whose name is in the ".gitignore" will not be tracked by Git.** This is useful if you want to include data in your local version of your repository but don't want to risk sharing that data by committing it to a public GitHub repository. This file exists at the top level of every repository and can be customized however is most useful to you and your collaborators. + +## Creating a ".gitignore" + +When you first create a repository you will have the opportunity to select a template ".gitignore" based on the coding language you plan on using. During the process of creating a repository, you can choose one of the templates curated by GitHub for a variety of coding languages. These templates exclude some typical machine-readable files that--while necessary for standard IDEs/background tasks--are not meaningful to track with version control. + +To add a ".gitignore" during the repository creation phase, simply **click the dropdown menu and start typing the name of your coding language.** Unfortunately for R users, typing just "R" returns all templates that _contain_ the letter 'r' so you will need to scroll a bit to find the option that is actually for the R language. **Once you find the template you want, click it** and the template dropdown should change from ".gitignore template: None" to ".gitignore template: \". + +

+Screenshot of the page on GitHub that appears when you click 'new repository'. Contains empty dialogue fields for the repository name and description as well as options for public versus private repositories among other initialization options +Screenshot of the page on GitHub that appears when you click 'new repository'. Contains empty dialogue fields for the repository name and description as well as options for public versus private repositories among other initialization options +

+ +If you create a repository without choosing a ".gitignore" template, don't worry: you can always create one later! If you want to create a ".gitignore" in an extant repository that lacks one, run the relevant command line code for your computer's operating system in your IDE's {{}} "Terminal" pane. + +:::{.panel-tabset} +#### {{< fa brands apple >}} Mac / {{< fa brands linux >}} Linux + +``` +touch .gitignore +``` + +#### {{< fa brands windows >}} Windows + +``` +copy NUL .gitignore +``` + +If `copy NUL` does not work, try `touch` instead. + +::: + +## Using a ".gitignore" + +A classic use-case for a ".gitignore"--as previously mentioned--is to ignore any data files that you have in your working directory but that you don't want Git to track of GitHub to store. In general, **script inputs and outputs _should not_ be tracked by Git or put in GitHub.** Versioning of tabular data doesn't really work very well and it'll clutter your GitHub repository with data files that you already have access to elsewhere. + +Additionally, storing script inputs/outputs both on GitHub and elsewhere (e.g., Google Drive, Dropbox) undermines the "single source of truth" and dramatically increases the risk that you accidentally work with a superseded input file and get incorrect results. + +Taken together, **the following demonstration of how to use a ".gitignore" will focus on ignoring a new data file in the working directory.** This file is informatively named "data.csv". + +::::{.panel-tabset} +### In RStudio + +To begin, we can **check the Git pane of RStudio to confirm that Git does see "data.csv"** even though Git is not tracking it currently. + +

+Screen capture of RStudio where the Git pane shows an untracked file named 'data.csv' +

+ +With that confirmed, **click over to the "Files" pane.** Because the ".gitignore" file starts with a period, it is likely invisible to your standard file explorer program but RStudio's "Files" pane does see it and easily lets you interact with it. + +

+Screen capture of RStudio with the 'Files' pane open +

+ +In the "Files" pane, **click the ".gitignore" to open it**. If you scroll through you can see that the template from GitHub includes a number of files, many of which you may never have seen (again, often because they start with a period and are thus not easily visible). + +

+Screen capture of RStudio with the R template '.gitignore' from GitHub open +

+ +While currently we only have "data.csv" in our working directory, we can safely assume that we don't want _any_ CSVs to be tracked by Git. So, rather than entering "data.csv" into the ".gitignore", let's **add a wildcard for _all_ CSVs by entering "\*.csv" at the bottom of the ".gitignore".** Note that in the below screen shot, we haven't saved our edits to the ".gitignore" so the "Git" pane still (1) shows "data.csv" and (2) _does not_ show any modifications to the ".gitignore". + +:::{.callout-note} +#### Comments in the ".gitignore" + +You can enter comments in the ".gitignore" in the same way you would in R/Python code: by adding a `#` to the start of the line. This can be helpful if you want to add small documentation of what is being ignored or why it is being ignored. +::: + +

+Screen capture of RStudio with the R template '.gitignore' from GitHub open and edited but with unsaved changes +

+ +Once you **save the edits to the ".gitignore"**, you'll notice that the Git pane automatically updates to (1) no longer show "data.csv" and (2) show that the ".gitignore" has been modified since the last commit. You can then **commit and push your edits to the ".gitignore" in the same way you would edits to any other file.** + +

+Screen capture of RStudio where the Git pane shows un-committed edits to the '.gitignore' +

+ +### In Positron + +To begin, we can **check the "source control" pane of Positron to confirm that Git does see "data.csv"** even though Git is not tracking it currently. + +

+Screen capture of Positron where the source control pane shows an untracked file named 'data.csv' +

+ +With that confirmed, **click over to the "Explorer" pane.** Because the ".gitignore" file starts with a period, it is likely invisible to your standard file explorer program but Positron's "Explorer" pane does see it and easily lets you interact with it. + +

+Screen capture of Positron with the 'Explorer' pane open +

+ +In the "Explorer" pane, **click the ".gitignore" to open it**. If you scroll through you can see that the template from GitHub includes a number of files, many of which you may never have seen (again, often because they start with a period and are thus not easily visible). + +

+Screen capture of Positron with the R template '.gitignore' from GitHub open +

+ +While currently we only have "data.csv" in our working directory, we can safely assume that we don't want _any_ CSVs to be tracked by Git. So, rather than entering "data.csv" into the ".gitignore", let's **add a wildcard for _all_ CSVs by entering "\*.csv" at the bottom of the ".gitignore".** Note that in the below screen shot, we haven't saved our edits to the ".gitignore" so the "source control" pane still (1) shows "data.csv" and (2) _does not_ show any modifications to the ".gitignore". + +:::{.callout-note} +#### Comments in the ".gitignore" + +You can enter comments in the ".gitignore" in the same way you would in R/Python code: by adding a `#` to the start of the line. This can be helpful if you want to add small documentation of what is being ignored or why it is being ignored. +::: + +

+Screen capture of Positron with the R template '.gitignore' from GitHub open and edited but with unsaved changes +

+ +Once you **save the edits to the ".gitignore"**, you'll notice that the source control pane automatically updates to (1) no longer show "data.csv" and (2) show that the ".gitignore" has been modified since the last commit. You can then **commit and push your edits to the ".gitignore" in the same way you would edits to any other file.** + +

+Screen capture of Positron where the Git pane shows un-committed edits to the '.gitignore' +

+ +:::: + +## Ignoring Previously Tracked Content + +Imagine a situation where you commit a file that you don't want Git to track and push that commit before realizing your mistake. Now that file is tracked by Git and every time you alter that file, it will show up in your IDE's version control pane. If you add the file to your ".gitignore" now, you won't be able to delete it because Git will stop tracking new changes (even deletions). + +To resolve this, do the following: + +1. Delete the offending file(s) + - If you don't want to actually delete them, just move the file(s) out of the folder tracked by Git and move them back after step 3 +2. Commit the deletion +3. Add the file(s) to the ".gitignore" +4. Commit the change to the ".gitignore" +5. **push/sync** your changes with GitHub + +## LTER SciComp Recommendations + +There are many different opinions on what should go into a ".gitignore" but see below for some recommendations of things to ignore from the makers of this workshop. Feel free to disregard any that you don't feel apply to your needs. + +### Start with the GitHub Template + +**When you create a repository, use GitHub to add the template ".gitignore" for your chosen programming language.** There are a lot of small files that typical users don't care about that your project will accumulate over its lifecycle. If you don't flag these in the ".gitignore" it can become difficult to sort through your repository. + +### Ignore Script Inputs and Outputs + +**Version control is only meant to track code files so everything else should be ignored.** You should store your inputs somewhere that your collaborators can access them and--at the end of your project--archive them in a FAIR (Findable, Accessible, Interoperable, and Reusable) repository. Anyone wanting access to script outputs should be able to use those inputs to run the code themselves and generate them. Alternately, you may also want to upload script outputs to some static platform (e.g., Google Drive, Dropbox) so non-coders can easily access them there. In either case, **Git should not be used to track/store anything other than code files.** + +One way of doing this fairly efficiently is to create dedicated folders for storing inputs or outputs (e.g., "data/", "graphs/", "results/") and then add those folder names to the ".gitignore". You could also ignore certain file types--as demonstrated above--if your inputs/outputs belong to a relatively small set of file types. + +### Ignore the ".DS_Store" File + +**If you are a {{< fa brands apple >}} Mac user, you should ignore the ".DS_Store" file.** Macs create a "Desktop Services Store" file (or ".DS_Store" for short) every time you open a folder. This file is invisible in your file manager but _can_ be committed. This file has no practical value in your project and a separate one exists in every subfolder so tracking them can quickly clutter a repository if you use subfolders. + +### Ignore the R Project File + +**If you are an RStudio user, you should ignore the ".Rproj" file.** This opinion is a relatively contentious one as RStudio users are deeply divided on whether to ignore this file or commit it. We recommend ignoring it for two reasons: + +1. **If you commit your .Rproj file and someone later deletes it, the next time you pull, Git will delete your .Rproj file and cause RStudio to unexpectedly quit**--costing you all of your uncommitted edits. You will then need to create a new .Rproj in the desired folder and re-connect it to Git/GitHub. +2. **All group members may have different names for their .Rproj files which means you could have as many of these files in your GitHub repository as there are collaborators.** This is cumbersome to sort through and attempts to fix this _post hoc_ run the risk outlined in the first point. + +If these risks are not sufficient to sway you, consider that the .Rproj file serves almost no purpose in the first place. In theory, the .Rproj file can be used to define some RStudio settings for anyone who uses that .Rproj but few R users actually use it for this purpose and instead mostly use it as a shortcut to open the relevant project in RStudio. + +Ultimately, this is up to you and your team to decide! Hopefully the rationale we provided above helps inform this decision and we are happy to discuss this more if you have follow up questions. diff --git a/git_ignore.qmd b/git_ignore.qmd deleted file mode 100644 index c4af782..0000000 --- a/git_ignore.qmd +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: "The `.gitignore`" ---- - -## Module Learning Objectives - -By the end of this module, you will be able to: - -- Create a `.gitignore` in a repository using a GitHub template -- Explain the purpose of a `.gitignore` in collaborative projects -- Evaluate the content you think might warrant adding to the `.gitignore` - -## Overview - -The purpose of the `.gitignore` is evident in its name: anything included in it is *ignored by Git*. This can be useful if you want to include data in your local version of your repository but don't want to risk sharing that data by committing it to a GitHub repository you plan to make public at some point. This file exists at the top level of every repository and can be customized however is most useful to you and your collaborators. - -## Creating a `.gitignore` - -When you first create a repository you will have the opportunity to select a template `.gitignore` based on the coding language you plan on using. In the "New Repository" process, scroll down to just below where you can choose to add a README. - -

-Screenshot of the bottom part of the interface on GitHub that appears when you are creating a repository. The 'add .gitignore' dropdown menu is centered in the screenshot -

- -Underneath the title "Add .gitignore" there is a dropdown menu for various templates that starts at "None". If you click this dropdown menu you can type in keywords that will help you identify the template that you want to use. - -

-Screenshot of the dropdown menu in the gitignore template part of making a new repository where 'R' has been entered and is about to be chosen from the list of available templates -

- -Unfortunately for R users, typing just "R" returns all templates that contain the letter 'r' so you will need to scroll a bit to find the option that is actually for the R Statistical Environment. Once you find the option you want, click it and the template dropdown should change from ".gitignore template: None" to ".gitignore template: \". - -

-Screenshot of GitHub after the 'R' template has been chosen for the gitignore from the available options -

- -If you create a repository without choosing a `.gitignore` template, don't worry! You can always create one later! When cloning a repository using RStudio, a `.gitignore` file will be automatically created when setting up the RStudio project on your local computer. If you clone via the command line `touch .gitignore` would create the necessary file. - -## Interacting with the `.gitignore` - -Once you have the one, you can open the `.gitignore` by clicking it from the "Files" pane of RStudio. - -

-Screenshot of the 'files' pane in RStudio which includes the .Rproj file, the README, and the gitignore -

- -After you click it you'll be looking at a file that looks very similar to any other file in RStudio. - -

-Screenshot of the gitignore open in RStudio looking similar to any other file in RStudio -

- -Now let's add something to it! As you can see from the Git pane of the above image (top right), after cloning our new repository, the only file Git is flagging as untracked is the .Rproj file created whenever you make a new RStudio project. - -If we add `*.Rproj` to our `.gitignore`, the Git pane will show that the only change is that lines have been added to the `.gitignore`. The .Rproj file with the double yellow question marks next to it is gone! - -

-Screenshot of RStudio demonstrating that when a file name or extension is added to the gitignore and that change is saved then the file in question disappears from RStudio's Git pane -

- -Once you've edited the `.gitignore` it is generally a good practice to push those changes as soon as possible. If you flag a certain file (or folder) to be ignored while someone else is depending on it, if you wait to push the change you can risk a serious conflict. Or, they might commit a file you want ignored which is frustrating to remove (see "Exceptions to the `.gitignore`" below). - -

-Screenshot of RStudio's commit window where the change to the gitignore is being committed -

- -Only the commit is pictured above, but pushing & pulling works in the same way here as it does elsewhere. - -## Our Recommendations - -There are many different opinions on what should go into a `.gitignore` but we have a few suggestions that might prove helpful (or are at least worth considering). - -1. **Use the GitHub `.gitignore` template for your chosen programming environment** - - - There are a lot of small files that typical users don't care about that your project will accumulate over its lifecycle. If you don't flag these in the `.gitignore` it can become difficult to sort through your repository - -2. **Add `.DS_Store`** - - - Macs create a "Desktop Services Store" file (or ".DS_Store" for short) every time you open a folder. This file is invisible in your file manager but _can_ be committed. This file has no practical value in your project and a separate one exists in every subfolder so tracking them can quickly clutter a repository if you use subfolders - -3. **Other Considerations** - - - Some people recommend adding everything your script creates to the `.gitignore`. The theory being that if someone wants to see those outputs, they would only need to run your script(s) in order to create their own versions - - Another way of thinking about this is to create a dedicated folder to store products in (e.g., "data", "exports", etc.) and then add that folder to the `.gitignore`. This means you don't need to worry about adding specific files to the `.gitignore` so long as all the files live in a folder you've already designated as something for Git to not track - -4. Do you have another idea for what you typically add to a `.gitignore`? - - - Please share it with us by [posting an Issue](https://github.com/lter/workshop-github/issues); we'd love to hear from you! - -### Should You Ignore the .Rproj File? - -If you are an RStudio user, you *could* choose to add the R project file to your `.gitignore`. However, this is a somewhat thorny decision with strong arguments on both sides. We'll try to summarize some of the big considerations below to help inform your decision. - -#### Option A: **Commit** the .Rproj - -There are (in our opinion) three strong arguments for committing the .Rproj: - -1. Ease of Access - - - For non-R users, it can be really helpful to have just one file that they need to double click in order to open and interact with the whole R project. By committing the .Rproj, you make the post-clone start up instructions much simpler (i.e., "click the file ending in '.Rproj' and you're good to go") - -2. Facilitate Cloning Outside of RStudio - - - While our workshop has exclusively covered cloning a repo through RStudio, it is absolutely possible to clone without using RStudio. If someone goes this route, and the .Rproj is not already included in the repo, they will be left without one. So, after the clone they would then have an extra step to create their own .Rproj if they wanted to use RStudio to interact with the code - - Note that if everyone on your team is cloning via RStudio, this is not really an issue because cloning via RStudio *creates* a new .Rproj if one does not already exist - -3. Enforce Project Settings - - - Fundamentally, the .Rproj is a list of settings that you're using for a specific project in RStudio. If you wanted to create some defaults of those settings for anyone who cloned your repository, you could commit your .Rproj with your preferred settings - - That said, any member of your team who changed those settings would have the option to commit the corresponding change to the .Rproj file and the next time you **pull** you would have their settings instead - -#### Option B: Ignore the .Rproj - -We feel there are some serious reasons for ignoring the .Rproj as well: - -1. Risk of Deletion - - - Say you decide to commit your .Rproj, what happens if someone deletes it and **pushes** that deletion? This can happen if team members clone their version of the repo with a different name resulting in two local .Rproj files where one is redundant from that team member's perspective - - If a .Rproj is committed and then subsequently deleted, everyone who **pulls** that change will delete their local project. This results in an instant error that can be difficult to recognize if you don't know beforehand about this risk. The only fix is for all affected users to re-clone the repository - - So, if you add the .Rproj to the `.gitignore` preemptively, you can avoid the risk of this happening at some later stage; you could also add it as "`*.Rproj`" so regardless of the name of the file it will be ignored if the file type is .Rproj - -2. Loss of Flexibility - - - When you commit your .Rproj you are "locking in" the name of your project. If your preliminary data exploration and analyses bring new hypotheses and goals to light you may want to change your project name to better match this new framing. If you had previously committed your .Rproj, it can be a hassle to change its name and **push** this change - - Alternatively, you may want to change your GitHub repository name after publication to share keywords with your final manuscript title or the journal name to make the repository more easily searchable by your readers. Technically you could change the GitHub repository name without changing the corresponding .Rproj filename but there will be some disonance there if your readers clone your code - -3. Preserve Team Members' Local Filing Decisions - - - Most working group members are involved in a staggering variety of pursuits in addition to their role in a synthesis working group. People tend to have their own filing systems in their computers to help them quickly and easily navigate among their different projects - - If you **commit** the .Rproj, you force everyone who clones your repository to use your naming convention which can be a hurdle (albeit likely a minor one) as they juggle their responsibilities - -#### Decision - -Ultimately, this is up to you and your team to decide! Hopefully our outlined reasons for and against adding the .Rproj to the `.gitignore` help inform this decision and we are happy to discuss this more if you have follow up questions! - -## Ignoring Previously Tracked Content - -Imagine a situation where you commit a data file to your GitHub repository and push that commit. Now your data file is tracked by Git and every time you alter that file RStudio's "Git" pane will notify you that the file changed by placing the blue "M" next to the file's name. Let's say that eventually you decide that you want to (1) remove the file from your GitHub repository and (2) stop Git from tracking *future* changes to the file. If this is the case, you'll need to do the following: - -1. Either (A) delete the file or (B) move it out of the repository's folder - - - Either option will register as "deleting" the file from Git's perspective - -2. **Commit** the deletion - -3. **Push** that change - -4. Add the name of that file to your `.gitignore` - -Once you've done these steps, even if you put the file back in your repository, Git won't track its addition or any changes to it over time. diff --git a/ide.qmd b/ide.qmd new file mode 100644 index 0000000..6702f78 --- /dev/null +++ b/ide.qmd @@ -0,0 +1,341 @@ +--- +title: "Using GitHub with an IDE" +--- + +## Module Learning Objectives + +By the end of this module, you will be able to: + +- Describe the IDE-to-GitHub order of operations +- Define fundamental Git vocabulary +- Create a local version-controlled repository that is connected to GitHub + +## Overview of Git Workflow + +Before we get into using Git and GitHub through an IDE (Integrated Development Environment), it will be helpful to review the major steps of including version control as you work on code. Also, note that "IDE" is the technical term for a piece of software that is used to create software; RStudio, Visual Studio Code, and Positron are all examples of IDEs with which you may already be familiar. + +Beginning on your local computer, you make **changes** to a file in a folder that you have previously marked for version control tracking (i.e., a **working directory**). Once those changes are made you can **stage changes** within your local computer. After staging, it is best to retrieve the latest file versions from the cloud. You likely will already be up-to-date but this preemptive step can save you a lot of heartache down the line. Once you've confirmed that you have the latest file versions, you can shift the revised file(s) to the cloud where any GitHub users with access to your project can access the most recent file and look at the history of all previous changes. + +:::{.callout-note} +#### "Pull & Push" vs. "Sync" + +Some IDEs (e.g., Positron, VS Code) combine a pull and a push into a single operation called a "sync". These IDEs also support pulling and pushing separately so you may want to do those operations separately until you are completely comfortable with the necessary order of operations. +::: + +

+Graphic of a white rectangle on top of a blue square. The white rectangle has a happy cloud image and is labeled 'GitHub' while the blue square has an emoji-style laptop. Numbered steps start at the bottom left and work towards the top right as follows: '1-make changes', '2-stage changes', '3-retrieve latest from GitHub', and '4-put in GitHub' +

+ +## Git Vocabulary + +Finally, it will be helpful to introduce four key pieces of vocabulary before we dive into the interactive component of this workshop. + +- **Clone** = copy the entire contents of a GitHub repository to your local computer (done once per computer) + +- **Commit** = move a changed local file to your local staging area (step 2 of the above diagram) + +- **Pull** = get file(s) *from* the cloud *to* your local computer -- opposite of a "push" (step 3) + +- **Push** = move file(s) *to* the cloud *from* your local computer -- opposite of a "pull" (step 4) + +

+Graphics demonstrating a clone (copy entire folder from GitHub to a copmputer), a commit (putting local changes into the staging area), a pull (overwriting local copies with GitHub versions of the same), and a push (overwriting GitHub versions of files with the committed local versions) +

+ +## Cloning a Repository + +Regardless of which IDE you are using, the first step of using using Git with that IDE is to clone the repository from GitHub. To clone a repository, follow the steps under the relevant tab for your IDE. + +:::{.panel-tabset} +### In RStudio + +Navigate to the GitHub homepage of the repository that you'd like to clone. + +

+Screen capture of the home page of a GitHub repository named 'git-practice' +

+ +Once you are there, **click the "Code"** button then, in the resulting dropdown menu, **copy the link under the "HTTPS" tab.** + +

+Screen capture of the menu that appears in a GitHub repository when someone clicks the 'code' button +

+ +Now, **switch over to RStudio.** In the top right corner of RStudio, **click the dropdown menu with a glass box containing a capital "R".** This button may have the name of the current RStudio project (i.e., the working directory) if you have previously used RStudio but may otherwise be just the glass box icon with "Project: (None)". + +

+Screenshot of RStudio when no project or scripts are open +

+ +Once you have clicked that button in order to open its dropdown menu, **click "New Project..."** + +

+Screenshot of the menu that appears when someone clicks 'Project: (None)' in RStudio and hovers over the 'New Project...' button +

+ +In the resulting pop-up window, **select "Version Control".** + +

+Screenshot of a menu with three options: 'new directory', 'existing directory', and 'version control' +

+ +In the next page of the pop-up menu, **select "Git".** + +

+Screenshot of a menu with two options: 'git' and 'subversion' +

+ +In the final page of the pop-up window, you can now specify details about the repository that you want to clone. Most critically, **paste in the link you copied from the "Code" dropdown menu in GitHub in the "Repository URL" field.** You can also choose the local name of the folder for this clone and where on your computer you want to create the clone; the example below just clones into the "Documents" folder but you may want to place the clone elsewhere depending on how you organize your files. + +Once you have pasted in the relevant link and are happy with the local name and where the clone will be made, **click "Create Project".** + +

+Screenshot of a menu with three open text fields, one for the 'repository URL', one for 'project directory name' and one for 'create project as subdirectory of' +

+ +Now we have finished cloning the repository via RStudio! Notice that we are now working in the "git-practice_rstudio" project (see the name next to project name in the top right corner) and that a number of files are visible in the "Files" pane in the top right quadrant (including the "README.md" and ".gitignore" files found in our GitHub repository). + +

+Screen capture of the RStudio home page after cloning has been completed +

+ +### In Positron + +Navigate to the GitHub homepage of the repository that you'd like to clone. Once you are there, simply **copy the URL in your browser's navbar** (should start with "github.com/..."). + +

+Screen capture of the home page of a GitHub repository named 'git-practice' +

+ +Now, **switch over to Positron.** In the top right corner, **click the dropdown menu with a folder icon.** This button may have the name of the folder Positron is currently focused on (i.e., the working directory) if you have previously used Positron but may otherwise be just a folder icon without text. + +

+Screen capture of the home page of Positron +

+ +In the resulting dropdown menu, **select "New Folder from Git..."**. + +

+Screen capture of the Positron with the folder dropdown menu in the top right corner expanded to reveal recent folders +

+ +This will open a pop-up window where you can **paste in the GitHub repository link that you copied earlier.** You can also choose where on your computer you want to create the clone; the example below just clones into the "Documents" folder but you may want to place the clone elsewhere depending on how you organize your files. + +Once you have pasted in the repository link and chosen where to download its files, **click "OK".** + +

+Screen capture of the Positron pop-up menu where a GitHub repository's details may be entered in order to clone it locally +

+ +Now we have finished cloning the repository via Positron! Notice that we are now working in the "git-practice_positron" folder (see the name next to folder icon in the top right corner) and that a number of files are visible in the files pane in the left sidebar (including the "README.md" and ".gitignore" files found in our GitHub repository). + +

+Screen capture of the Positron home page after cloning has been completed +

+ +::: + +## Workflow Refresher + +The typical workflow with Git goes like this: + +**Step 1**: You modify files in your working directory and save them as usual. + +**Step 2**: You **stage** files to mark your intention to "commit" them and then **commit** that version of those files. Committing files permanently stores them as snapshots to your Git directory. + +:::{.panel-tabset} +### RStudio Commits + +In RStudio, staging is done by checking the box next to a file in the "Git" tab + +### Positron Commits + +In Positron, staging is done by clicking the plus sign next to a file in the "Source Control" menu in the left sidebar + +::: + +**Step 3**: You **pull** the most recent changes to make sure you've been editing the latest versions. + +**Step 4**: You **push** your the version of your files that you committed to GitHub. + +Here is the infographic from the start of this chapter again, which shows the same workflow: + +

+Graphic of a white rectangle on top of a blue square. The white rectangle has a happy cloud image and is labeled 'GitHub' while the blue square has an emoji-style laptop. Numbered steps start at the bottom left and work towards the top right as follows: '1-make changes', '2-stage changes', '3-retrieve latest from GitHub', and '4-put in GitHub' +

+ +## Stage versus Commit + +The functional difference between "staging" a file and "committing" one can be a little tough to grasp at first so let's explore that briefly here. We can make an analogy with taking a family picture, where each family member would represent a file. + +- **Staging** files is like deciding which family member(s) are going to be in your next picture +- **Committing** is like taking the picture + +This 2-step process enables you to flexibly group files into a specific commit. Those groupings can be helpful to you later if you're trying to find what you changed for a specific task (because those changes likely are all in the same commit). + +## Creating a New File + +Let's try out a simple Git workflow by first creating a new file. This is **Step 1** of the process. To begin, open your IDE and get to the clone you just made in the previous steps. Once you are there, make a new R script and name it after yourself (e.g., `lyon-script.r`). + +::::{.panel-tabset} +### In RStudio + +Once you have a new file in your cloned folder (i.e., the folder on your computer that you've told Git to track). If you **click the "Git" tab**--usually found in the top right quadrant of RStudio-you should see two files listed: your ".Rproj" file and the new script you created. + +Both files have double yellow `?` icons indicating that they are in the tracked folder but are not currently tracked themselves. Let's get ready to commit our new script by **clicking either of the two left-most buttons in the Git tab** (they both open the same window). + +The reason that neither the "README.md" nor the ".gitignore" appear in this tab is that the Git tab will only show files whose status has _changed_ since the last commit. Those two files are the same as when we cloned them so they won't appear here. + +

+Screenshot of RStudio with an open script and several uncommitted changes identified in the 'Git' pane. Lack of commit is identified by double yellow squares containing a question mark +

+ +Note that there are other color-coded icons that can appear next to files in your working directory. These icons are shorthand for the Git status for any file whose status has changed since the last commit that you made. See below for a set of some of the more common icons along with their meaning. + +

+A legend of five icons RStudio uses to indicate Git status of a file. Yellow question mark = untracked (file not tracked by Git). Green 'A' = added (file marked to start tracking). Blue 'M' = modified (tracked file with changes). Red 'D' = deleted (tracked file that was deleted). Purple 'R' = renamed (tracked file that was renamed) +

+ +#### Commit the File + +By clicking one of the buttons in the previous step, we've opened the window where we can commit our new script. **To actually make the commit, we need to do three things:** + +1. **"Stage" the new file by checking the box next to it** + - Note that when you do this, the two yellow `?` will become a green `A` to indicate we're adding the file to Git tracking +2. **Write a commit message about what this commit entails** + - Think about what information will be useful to 'future you' or your collaborators 6+ months from now +3. **Click the "Commit" button** + +

+Screenshot of the 'diff' button--circled in red--in the 'Git' pane of RStudio +

+ +After you click the "Commit" button, you should get a message that looks something like the following screen shot. You can now **close both this new message as well as the pop-up window and return to 'normal' RStudio.** + +

+Screenshot of the commit menu of RStudio where one file has been staged and an informative commit message has been entered +

+ +**If the above steps went well, you should see something like the following image.** The important bits are twofold: (1) your script is _no longer listed in the Git tab_ and (2) there is a message saying "Your branch is ahead of 'origin/main' by 1 commit". + +

+Screenshot of the success message after a commit has been made +

+ +We can leave aside what "origin/main" specifically means for now but we did just make one commit so we can surmise that our local clone should have one more commit than what GitHub knows about (at this point). + +#### Get the Latest Updates + +Before we can send our one commit up to GitHub, let's make sure that we have all the changes that GitHub has by "pulling" the repository. To do this, **click the blue _downward-facing_ arrow button in the Git pane.** Because we are working alone in this tutorial, there should be no changes so you should get the following message. + +

+Screenshot of the message returned when you pull from a repository where you are already up-to-date +

+ +Note that when you are collaborating with a large team, **you will want to pull early and often** so that you avoid the risk of working on an outdated version of a file. You may also want to pull _before_ making a commit to further reduce the risk of errors. + +#### Send Your Commit to GitHub + +Now that we have made our commit and confirmed there are no changes in the GitHub repository that we don't already have, we can "push" our changes back to GitHub. To do this, **click the green _upward-facing_ arrow button in the Git pane.** You should get a message that is something like the following image. + +

+Screenshot of the message returned when you push a commit to a repository successfully +

+ +If we return to the GitHub home page for our repository, we can now see our script is there and the commit message is the same as the message we typed in RStudio! + +

+Screenshot of a GitHub repository home page +

+ +:::callout-note +#### If RStudio ever asks for a "password"... + +If your personal access token (PAT) was not set up correctly with RStudio or if it expired, then RStudio will ask for your GitHub username and password in a pop-up when you try to push. **Please be aware that when they ask for a "password", they actually meant your token!** Enter your token in the field and you should be able to push now. Make sure to run `gitcreds::gitcreds_set()` to set a valid token afterwards so you don't have to enter it manually every time! +::: + +### In Positron + +Once you have a new file in your cloned folder (i.e., the folder on your computer that you've told Git to track). Positron should display the Git status of the file next to the file's name. In this case, because this a new file that isn't yet tracked by Git, there should be a `U` indicating that it is "untracked." + +Let's get ready to commit our new script by **clicking the "Source Control" piece of the left sidebar.** That button should have a red "1" next ot it and its icon looks like this: {{< fa code-branch >}} + +

+Screenshot of Positron with an open script untracked by Git with one uncommitted change. Lack of commit is identified by red number '1' in the leftsidebar +

+ +Once you are in the source control menu, you should see a list of the files with changes--currently only the new file that you just made. + +

+Screenshot of the source control pane of Positron showing one file with changes +

+ +The reason that neither the "README.md" nor the ".gitignore" appear in this menu is that the source control menu will only show files whose status has _changed_ since the last commit. Those two files are the same as when we cloned them so they won't appear here. + +#### Commit the File + +We are now in the right place for us to commit our new script. **To actually make the commit, we need to do three things:** + +1. **"Stage" the new file by click the plus sign next to it** + - Note that when you do this, the `U` will become an `A` to indicate we're adding the file to Git tracking +2. **Write a commit message about what this commit entails** + - Think about what information will be useful to 'future you' or your collaborators 6+ months from now +3. **Click the "Commit" button** + +

+Screenshot of the commit menu of Positron where one file has been staged and an informative commit message has been entered +

+ +**If the above steps went well, you should see something like the following image.** The important bits are twofold: (1) your script is _no longer listed_ and (2) in the menu at the bottom of this sidebar the label with a cloud (titled "origin/main") is beneath a label with the commit message that you just wrote. + +Additionally, the "Commit" button should now be a "Sync Changes" button. + +

+Screenshot of the source control pane in Positron where the 'sync changes' button is active +

+ +We can leave aside what "origin/main" specifically means for now but we did just make one commit so we can surmise that our local clone should have one more commit than what GitHub knows about (at this point). + +#### Other Git Actions + +If you've previously used other IDEs, you may notice that Positron's single centralized button (while making normal use _dramatically_ simpler) does hide other Git actions you may want to do. For example, if you edit several files, commit the changes to one, and want to sync just that commit, the "Sync" button is absent because the "Commit" button takes precedence. + +In order to see a full list of Git options, hover your mouse over the "changes" panel (just above the commit message field) and click the ellipses (`...`) that will appear when you are hovering there. + +You should now see a full list of the normal suite of Git actions that you can perform through Positron. If you want to sync, see the first option under the heading "Pull, Push" (about two thirds of the way down the dropdown menu). + +

+Screen capture of Positron source control pane with dropdown menu of Git actions open and visible +

+ +For our purposes here, the sync button is sufficient but you may want these other tools in the future. + +#### Syncing the Clone and GitHub + +Once you're ready to sync changes between your clone and the GitHub repository it is in contact with, you can **click the "Sync Changes" button.** + +If this is the first time you are doing this, you may get a warning like the following screenshot. If you get that message, **click "OK, Don't Show Again".** + +

+Screen capture of Positron warning about what 'sync changes' will do +

+ +You will know that the sync worked because the "Sync Changes" button will revert to a "Commit" button. In our case, because that was the only file with any changes, it means there is nothing in that list and the "Commit" button is grayed out and inactive Additionally, the purple and blue labels in the bottom of the left sidebar will both be on the topmost commit message. + +

+Screen capture of Positron source control pane when there are no new changes to be committed or synced +

+ +If we return to the GitHub home page for our repository, we can now see our script is there and the commit message is the same as the message we typed in Positron! + +

+Screenshot of a GitHub repository home page +

+ +:::: + +## Rinse and Repeat + +Great! Now that your script has been added to the group repository, you should try to repeat the same workflow over again just to get a feel for how it works. Go back to your IDE and edit your own script. Save those edits, add your edited file to the staging area, write a commit message, then commit your changes. After committing, make sure to pull first then push after! When you pull, you might notice that scripts from your group members/collaborators will show up in your working directory. + +Make sure to work on your own script. If you and another group member work on the same script at the same time, this may lead to merge conflicts with Git. If two people were to work on the same script, they may be making different edits on the same lines, and Git would not know which edits to keep. To avoid merge conflicts, be mindful of what files you are working on and always communicate this to your group members! diff --git a/images/branches/branches-1-new-branch-button.png b/images/branches/branches-1-new-branch-button.png deleted file mode 100644 index a8877ca..0000000 Binary files a/images/branches/branches-1-new-branch-button.png and /dev/null differ diff --git a/images/branches/branches-10-successful-merge.png b/images/branches/branches-10-successful-merge.png deleted file mode 100644 index afabaf6..0000000 Binary files a/images/branches/branches-10-successful-merge.png and /dev/null differ diff --git a/images/branches/branches-11-deleted-branch.png b/images/branches/branches-11-deleted-branch.png deleted file mode 100644 index 9ed5693..0000000 Binary files a/images/branches/branches-11-deleted-branch.png and /dev/null differ diff --git a/images/branches/branches-12-github-repo-post-merge.png b/images/branches/branches-12-github-repo-post-merge.png deleted file mode 100644 index 5f019c2..0000000 Binary files a/images/branches/branches-12-github-repo-post-merge.png and /dev/null differ diff --git a/images/branches/branches-13-local-repo.png b/images/branches/branches-13-local-repo.png deleted file mode 100644 index 50d07c3..0000000 Binary files a/images/branches/branches-13-local-repo.png and /dev/null differ diff --git a/images/branches/branches-14-switch-local-to-main.png b/images/branches/branches-14-switch-local-to-main.png deleted file mode 100644 index eda89a5..0000000 Binary files a/images/branches/branches-14-switch-local-to-main.png and /dev/null differ diff --git a/images/branches/branches-15-notice-outdated-script.png b/images/branches/branches-15-notice-outdated-script.png deleted file mode 100644 index 1691588..0000000 Binary files a/images/branches/branches-15-notice-outdated-script.png and /dev/null differ diff --git a/images/branches/branches-16-pull-merged-repo.png b/images/branches/branches-16-pull-merged-repo.png deleted file mode 100644 index 2a88e1f..0000000 Binary files a/images/branches/branches-16-pull-merged-repo.png and /dev/null differ diff --git a/images/branches/branches-2-name-new-branch.png b/images/branches/branches-2-name-new-branch.png deleted file mode 100644 index 7d2bf2c..0000000 Binary files a/images/branches/branches-2-name-new-branch.png and /dev/null differ diff --git a/images/branches/branches-2b-success-dialogue.png b/images/branches/branches-2b-success-dialogue.png deleted file mode 100644 index 9a5e516..0000000 Binary files a/images/branches/branches-2b-success-dialogue.png and /dev/null differ diff --git a/images/branches/branches-2c-new-branch.png b/images/branches/branches-2c-new-branch.png deleted file mode 100644 index 59a4cb3..0000000 Binary files a/images/branches/branches-2c-new-branch.png and /dev/null differ diff --git a/images/branches/branches-3-normal-commit.png b/images/branches/branches-3-normal-commit.png deleted file mode 100644 index 387d001..0000000 Binary files a/images/branches/branches-3-normal-commit.png and /dev/null differ diff --git a/images/branches/branches-4-normal-pull.png b/images/branches/branches-4-normal-pull.png deleted file mode 100644 index 614e24a..0000000 Binary files a/images/branches/branches-4-normal-pull.png and /dev/null differ diff --git a/images/branches/branches-5-normal-push.png b/images/branches/branches-5-normal-push.png deleted file mode 100644 index 51a076d..0000000 Binary files a/images/branches/branches-5-normal-push.png and /dev/null differ diff --git a/images/branches/branches-6-pull-request-start.png b/images/branches/branches-6-pull-request-start.png deleted file mode 100644 index 31b508c..0000000 Binary files a/images/branches/branches-6-pull-request-start.png and /dev/null differ diff --git a/images/branches/branches-7-pull-request-msg.png b/images/branches/branches-7-pull-request-msg.png deleted file mode 100644 index 3b3e035..0000000 Binary files a/images/branches/branches-7-pull-request-msg.png and /dev/null differ diff --git a/images/branches/branches-8-active-pull-request.png b/images/branches/branches-8-active-pull-request.png deleted file mode 100644 index f053742..0000000 Binary files a/images/branches/branches-8-active-pull-request.png and /dev/null differ diff --git a/images/branches/branches-9-pull-request-accept-msg.png b/images/branches/branches-9-pull-request-accept-msg.png deleted file mode 100644 index a9b70c0..0000000 Binary files a/images/branches/branches-9-pull-request-accept-msg.png and /dev/null differ diff --git a/images/branches/github-01_pr-button.png b/images/branches/github-01_pr-button.png new file mode 100644 index 0000000..f823b4e Binary files /dev/null and b/images/branches/github-01_pr-button.png differ diff --git a/images/branches/github-02_pr-details.png b/images/branches/github-02_pr-details.png new file mode 100644 index 0000000..f5fc373 Binary files /dev/null and b/images/branches/github-02_pr-details.png differ diff --git a/images/branches/github-03_pr-open.png b/images/branches/github-03_pr-open.png new file mode 100644 index 0000000..ce19103 Binary files /dev/null and b/images/branches/github-03_pr-open.png differ diff --git a/images/branches/github-04_pr-merge-message.png b/images/branches/github-04_pr-merge-message.png new file mode 100644 index 0000000..4b9799d Binary files /dev/null and b/images/branches/github-04_pr-merge-message.png differ diff --git a/images/branches/github-05_pr-merged.png b/images/branches/github-05_pr-merged.png new file mode 100644 index 0000000..4a7cb72 Binary files /dev/null and b/images/branches/github-05_pr-merged.png differ diff --git a/images/branches/github-06_pr-delete-branch.png b/images/branches/github-06_pr-delete-branch.png new file mode 100644 index 0000000..e89376c Binary files /dev/null and b/images/branches/github-06_pr-delete-branch.png differ diff --git a/images/branches/github-07_repo-home.png b/images/branches/github-07_repo-home.png new file mode 100644 index 0000000..5aff439 Binary files /dev/null and b/images/branches/github-07_repo-home.png differ diff --git a/images/branches/positron-01_start.png b/images/branches/positron-01_start.png new file mode 100644 index 0000000..3d1eb48 Binary files /dev/null and b/images/branches/positron-01_start.png differ diff --git a/images/branches/positron-02_new-branch.png b/images/branches/positron-02_new-branch.png new file mode 100644 index 0000000..392b9dc Binary files /dev/null and b/images/branches/positron-02_new-branch.png differ diff --git a/images/branches/positron-03_branch-details.png b/images/branches/positron-03_branch-details.png new file mode 100644 index 0000000..1445e77 Binary files /dev/null and b/images/branches/positron-03_branch-details.png differ diff --git a/images/branches/positron-04_publish-branch.png b/images/branches/positron-04_publish-branch.png new file mode 100644 index 0000000..eb456ca Binary files /dev/null and b/images/branches/positron-04_publish-branch.png differ diff --git a/images/branches/positron-05_published.png b/images/branches/positron-05_published.png new file mode 100644 index 0000000..99e7c5e Binary files /dev/null and b/images/branches/positron-05_published.png differ diff --git a/images/branches/post-branch_positron-01_switch.png b/images/branches/post-branch_positron-01_switch.png new file mode 100644 index 0000000..612eafb Binary files /dev/null and b/images/branches/post-branch_positron-01_switch.png differ diff --git a/images/branches/post-branch_positron-02_switch-dest.png b/images/branches/post-branch_positron-02_switch-dest.png new file mode 100644 index 0000000..51c3071 Binary files /dev/null and b/images/branches/post-branch_positron-02_switch-dest.png differ diff --git a/images/branches/post-branch_positron-03_pull.png b/images/branches/post-branch_positron-03_pull.png new file mode 100644 index 0000000..81ba0d4 Binary files /dev/null and b/images/branches/post-branch_positron-03_pull.png differ diff --git a/images/branches/post-branch_positron-04_success.png b/images/branches/post-branch_positron-04_success.png new file mode 100644 index 0000000..349e0cb Binary files /dev/null and b/images/branches/post-branch_positron-04_success.png differ diff --git a/images/branches/post-branch_positron-05_confirm-prune.png b/images/branches/post-branch_positron-05_confirm-prune.png new file mode 100644 index 0000000..2da4ea6 Binary files /dev/null and b/images/branches/post-branch_positron-05_confirm-prune.png differ diff --git a/images/branches/post-branch_rstudio-01_switch.png b/images/branches/post-branch_rstudio-01_switch.png new file mode 100644 index 0000000..b1c4140 Binary files /dev/null and b/images/branches/post-branch_rstudio-01_switch.png differ diff --git a/images/branches/post-branch_rstudio-02_switch-message.png b/images/branches/post-branch_rstudio-02_switch-message.png new file mode 100644 index 0000000..9cce47d Binary files /dev/null and b/images/branches/post-branch_rstudio-02_switch-message.png differ diff --git a/images/branches/post-branch_rstudio-03_pull-main.png b/images/branches/post-branch_rstudio-03_pull-main.png new file mode 100644 index 0000000..a37a6a3 Binary files /dev/null and b/images/branches/post-branch_rstudio-03_pull-main.png differ diff --git a/images/branches/post-branch_rstudio-06_confirm-prune.png b/images/branches/post-branch_rstudio-06_confirm-prune.png new file mode 100644 index 0000000..d3a52e1 Binary files /dev/null and b/images/branches/post-branch_rstudio-06_confirm-prune.png differ diff --git a/images/branches/rstudio-01_start.png b/images/branches/rstudio-01_start.png new file mode 100644 index 0000000..61ba816 Binary files /dev/null and b/images/branches/rstudio-01_start.png differ diff --git a/images/branches/rstudio-02_branch-details.png b/images/branches/rstudio-02_branch-details.png new file mode 100644 index 0000000..ec00f99 Binary files /dev/null and b/images/branches/rstudio-02_branch-details.png differ diff --git a/images/branches/rstudio-03_branch-message.png b/images/branches/rstudio-03_branch-message.png new file mode 100644 index 0000000..f0f70df Binary files /dev/null and b/images/branches/rstudio-03_branch-message.png differ diff --git a/images/github/github-1-website.png b/images/browser/browser-01_github-home.png similarity index 100% rename from images/github/github-1-website.png rename to images/browser/browser-01_github-home.png diff --git a/images/github/github-2-login.png b/images/browser/browser-02_github-login.png similarity index 100% rename from images/github/github-2-login.png rename to images/browser/browser-02_github-login.png diff --git a/images/github/github-3-signed-in.png b/images/browser/browser-03_github-signed-in.png similarity index 100% rename from images/github/github-3-signed-in.png rename to images/browser/browser-03_github-signed-in.png diff --git a/images/github/github-4-profile-light.png b/images/browser/browser-04_profile-light.png similarity index 100% rename from images/github/github-4-profile-light.png rename to images/browser/browser-04_profile-light.png diff --git a/images/github/github-5-dark-mode.png b/images/browser/browser-05_appearance-setting.png similarity index 100% rename from images/github/github-5-dark-mode.png rename to images/browser/browser-05_appearance-setting.png diff --git a/images/github/github-6-my-repos.png b/images/browser/browser-06_repos.png similarity index 100% rename from images/github/github-6-my-repos.png rename to images/browser/browser-06_repos.png diff --git a/images/github/github-7-example-repo.png b/images/browser/browser-07_repo-structure.png similarity index 100% rename from images/github/github-7-example-repo.png rename to images/browser/browser-07_repo-structure.png diff --git a/images/github/github-8-commit-history.png b/images/browser/browser-08_repo-history.png similarity index 100% rename from images/github/github-8-commit-history.png rename to images/browser/browser-08_repo-history.png diff --git a/images/github/github-9-specific-changes.png b/images/browser/browser-09_commit-diff.png similarity index 100% rename from images/github/github-9-specific-changes.png rename to images/browser/browser-09_commit-diff.png diff --git a/images/github/github-10-edit-file.png b/images/browser/browser-10_edit-file.png similarity index 100% rename from images/github/github-10-edit-file.png rename to images/browser/browser-10_edit-file.png diff --git a/images/github/github-11-add-file.png b/images/browser/browser-11_add-file.png similarity index 100% rename from images/github/github-11-add-file.png rename to images/browser/browser-11_add-file.png diff --git a/images/browser/new-repo-01_profile.png b/images/browser/new-repo-01_profile.png new file mode 100644 index 0000000..bc41cce Binary files /dev/null and b/images/browser/new-repo-01_profile.png differ diff --git a/images/browser/new-repo-02_repo-details-1.png b/images/browser/new-repo-02_repo-details-1.png new file mode 100644 index 0000000..aa47132 Binary files /dev/null and b/images/browser/new-repo-02_repo-details-1.png differ diff --git a/images/browser/new-repo-02b_repo-details-2.png b/images/browser/new-repo-02b_repo-details-2.png new file mode 100644 index 0000000..22c7dec Binary files /dev/null and b/images/browser/new-repo-02b_repo-details-2.png differ diff --git a/images/browser/new-repo-03_home.png b/images/browser/new-repo-03_home.png new file mode 100644 index 0000000..2019a69 Binary files /dev/null and b/images/browser/new-repo-03_home.png differ diff --git a/images/browser/new-repo-04_collab-settings.png b/images/browser/new-repo-04_collab-settings.png new file mode 100644 index 0000000..ae8666c Binary files /dev/null and b/images/browser/new-repo-04_collab-settings.png differ diff --git a/images/browser/new-repo-05_collab-search.png b/images/browser/new-repo-05_collab-search.png new file mode 100644 index 0000000..7440e59 Binary files /dev/null and b/images/browser/new-repo-05_collab-search.png differ diff --git a/images/clone/positron-01_repo-home.png b/images/clone/positron-01_repo-home.png new file mode 100644 index 0000000..b88eb53 Binary files /dev/null and b/images/clone/positron-01_repo-home.png differ diff --git a/images/clone/positron-02_start.png b/images/clone/positron-02_start.png new file mode 100644 index 0000000..ae37b50 Binary files /dev/null and b/images/clone/positron-02_start.png differ diff --git a/images/clone/positron-03_new-folder.png b/images/clone/positron-03_new-folder.png new file mode 100644 index 0000000..971c774 Binary files /dev/null and b/images/clone/positron-03_new-folder.png differ diff --git a/images/clone/positron-04_repo-details.png b/images/clone/positron-04_repo-details.png new file mode 100644 index 0000000..0010a62 Binary files /dev/null and b/images/clone/positron-04_repo-details.png differ diff --git a/images/clone/positron-05_cloned.png b/images/clone/positron-05_cloned.png new file mode 100644 index 0000000..ec850b6 Binary files /dev/null and b/images/clone/positron-05_cloned.png differ diff --git a/images/clone/rstudio-01_repo-home.png b/images/clone/rstudio-01_repo-home.png new file mode 100644 index 0000000..50a8c19 Binary files /dev/null and b/images/clone/rstudio-01_repo-home.png differ diff --git a/images/clone/rstudio-02_repo-code-tab.png b/images/clone/rstudio-02_repo-code-tab.png new file mode 100644 index 0000000..844da19 Binary files /dev/null and b/images/clone/rstudio-02_repo-code-tab.png differ diff --git a/images/clone/rstudio-03_start.png b/images/clone/rstudio-03_start.png new file mode 100644 index 0000000..8c522a2 Binary files /dev/null and b/images/clone/rstudio-03_start.png differ diff --git a/images/clone/rstudio-04_new-proj.png b/images/clone/rstudio-04_new-proj.png new file mode 100644 index 0000000..eb3cad1 Binary files /dev/null and b/images/clone/rstudio-04_new-proj.png differ diff --git a/images/clone/rstudio-05_version-control.png b/images/clone/rstudio-05_version-control.png new file mode 100644 index 0000000..6d62b3d Binary files /dev/null and b/images/clone/rstudio-05_version-control.png differ diff --git a/images/clone/rstudio-06_git.png b/images/clone/rstudio-06_git.png new file mode 100644 index 0000000..0ec1fa8 Binary files /dev/null and b/images/clone/rstudio-06_git.png differ diff --git a/images/clone/rstudio-07_repo-details.png b/images/clone/rstudio-07_repo-details.png new file mode 100644 index 0000000..3e11280 Binary files /dev/null and b/images/clone/rstudio-07_repo-details.png differ diff --git a/images/clone/rstudio-08_cloned.png b/images/clone/rstudio-08_cloned.png new file mode 100644 index 0000000..2ca58a1 Binary files /dev/null and b/images/clone/rstudio-08_cloned.png differ diff --git a/images/commit/positron-01_new-file.png b/images/commit/positron-01_new-file.png new file mode 100644 index 0000000..42748e0 Binary files /dev/null and b/images/commit/positron-01_new-file.png differ diff --git a/images/commit/positron-02_diff.png b/images/commit/positron-02_diff.png new file mode 100644 index 0000000..77291d2 Binary files /dev/null and b/images/commit/positron-02_diff.png differ diff --git a/images/commit/positron-03_commit.png b/images/commit/positron-03_commit.png new file mode 100644 index 0000000..aaf2cd1 Binary files /dev/null and b/images/commit/positron-03_commit.png differ diff --git a/images/commit/positron-03b_other-git-actions.png b/images/commit/positron-03b_other-git-actions.png new file mode 100644 index 0000000..a63412b Binary files /dev/null and b/images/commit/positron-03b_other-git-actions.png differ diff --git a/images/commit/positron-04_ahead-of-origin.png b/images/commit/positron-04_ahead-of-origin.png new file mode 100644 index 0000000..cbf589f Binary files /dev/null and b/images/commit/positron-04_ahead-of-origin.png differ diff --git a/images/commit/positron-05_sync-alert.png b/images/commit/positron-05_sync-alert.png new file mode 100644 index 0000000..d27712a Binary files /dev/null and b/images/commit/positron-05_sync-alert.png differ diff --git a/images/commit/positron-06_sync.png b/images/commit/positron-06_sync.png new file mode 100644 index 0000000..6671d43 Binary files /dev/null and b/images/commit/positron-06_sync.png differ diff --git a/images/commit/positron-07_updated-repo.png b/images/commit/positron-07_updated-repo.png new file mode 100644 index 0000000..40ce696 Binary files /dev/null and b/images/commit/positron-07_updated-repo.png differ diff --git a/images/commit/rstudio-01_new-file.png b/images/commit/rstudio-01_new-file.png new file mode 100644 index 0000000..aefcfee Binary files /dev/null and b/images/commit/rstudio-01_new-file.png differ diff --git a/images/commit/rstudio-02_diff.png b/images/commit/rstudio-02_diff.png new file mode 100644 index 0000000..7e66355 Binary files /dev/null and b/images/commit/rstudio-02_diff.png differ diff --git a/images/commit/rstudio-03_commit.png b/images/commit/rstudio-03_commit.png new file mode 100644 index 0000000..8e55835 Binary files /dev/null and b/images/commit/rstudio-03_commit.png differ diff --git a/images/commit/rstudio-04_ahead-of-origin.png b/images/commit/rstudio-04_ahead-of-origin.png new file mode 100644 index 0000000..1d71ab1 Binary files /dev/null and b/images/commit/rstudio-04_ahead-of-origin.png differ diff --git a/images/commit/rstudio-05_pull.png b/images/commit/rstudio-05_pull.png new file mode 100644 index 0000000..849fd0f Binary files /dev/null and b/images/commit/rstudio-05_pull.png differ diff --git a/images/commit/rstudio-06_push.png b/images/commit/rstudio-06_push.png new file mode 100644 index 0000000..ab6c9e6 Binary files /dev/null and b/images/commit/rstudio-06_push.png differ diff --git a/images/commit/rstudio-07_updated-repo.png b/images/commit/rstudio-07_updated-repo.png new file mode 100644 index 0000000..fa456cb Binary files /dev/null and b/images/commit/rstudio-07_updated-repo.png differ diff --git a/images/conflicts/conflicts-1-example-repo.png b/images/conflicts/conflicts-1-example-repo.png deleted file mode 100644 index 40de50d..0000000 Binary files a/images/conflicts/conflicts-1-example-repo.png and /dev/null differ diff --git a/images/conflicts/conflicts-10-resolved.png b/images/conflicts/conflicts-10-resolved.png deleted file mode 100644 index 7c3b893..0000000 Binary files a/images/conflicts/conflicts-10-resolved.png and /dev/null differ diff --git a/images/conflicts/conflicts-11-commit-resolved.png b/images/conflicts/conflicts-11-commit-resolved.png deleted file mode 100644 index d5f4d6a..0000000 Binary files a/images/conflicts/conflicts-11-commit-resolved.png and /dev/null differ diff --git a/images/conflicts/conflicts-12-push-resolved.png b/images/conflicts/conflicts-12-push-resolved.png deleted file mode 100644 index 46bc6eb..0000000 Binary files a/images/conflicts/conflicts-12-push-resolved.png and /dev/null differ diff --git a/images/conflicts/conflicts-13-merged.png b/images/conflicts/conflicts-13-merged.png deleted file mode 100644 index e7bca04..0000000 Binary files a/images/conflicts/conflicts-13-merged.png and /dev/null differ diff --git a/images/conflicts/conflicts-14-checking-merged.png b/images/conflicts/conflicts-14-checking-merged.png deleted file mode 100644 index 2cc0d5f..0000000 Binary files a/images/conflicts/conflicts-14-checking-merged.png and /dev/null differ diff --git a/images/conflicts/conflicts-15-commit-history.png b/images/conflicts/conflicts-15-commit-history.png deleted file mode 100644 index 0c61fc4..0000000 Binary files a/images/conflicts/conflicts-15-commit-history.png and /dev/null differ diff --git a/images/conflicts/conflicts-2-test-script.png b/images/conflicts/conflicts-2-test-script.png deleted file mode 100644 index c9766d2..0000000 Binary files a/images/conflicts/conflicts-2-test-script.png and /dev/null differ diff --git a/images/conflicts/conflicts-3-birds.png b/images/conflicts/conflicts-3-birds.png deleted file mode 100644 index b78fc50..0000000 Binary files a/images/conflicts/conflicts-3-birds.png and /dev/null differ diff --git a/images/conflicts/conflicts-4-birds-commit.png b/images/conflicts/conflicts-4-birds-commit.png deleted file mode 100644 index 70b73db..0000000 Binary files a/images/conflicts/conflicts-4-birds-commit.png and /dev/null differ diff --git a/images/conflicts/conflicts-5-flowers.png b/images/conflicts/conflicts-5-flowers.png deleted file mode 100644 index 4a93584..0000000 Binary files a/images/conflicts/conflicts-5-flowers.png and /dev/null differ diff --git a/images/conflicts/conflicts-6-birds-push.png b/images/conflicts/conflicts-6-birds-push.png deleted file mode 100644 index 943ce52..0000000 Binary files a/images/conflicts/conflicts-6-birds-push.png and /dev/null differ diff --git a/images/conflicts/conflicts-7-birds-pull.png b/images/conflicts/conflicts-7-birds-pull.png deleted file mode 100644 index d0c3723..0000000 Binary files a/images/conflicts/conflicts-7-birds-pull.png and /dev/null differ diff --git a/images/conflicts/conflicts-8-conflicted-lines.png b/images/conflicts/conflicts-8-conflicted-lines.png deleted file mode 100644 index 0167560..0000000 Binary files a/images/conflicts/conflicts-8-conflicted-lines.png and /dev/null differ diff --git a/images/conflicts/conflicts-9-unresolved.png b/images/conflicts/conflicts-9-unresolved.png deleted file mode 100644 index 9ffe4ef..0000000 Binary files a/images/conflicts/conflicts-9-unresolved.png and /dev/null differ diff --git a/images/conflicts/positron-01_conflict.png b/images/conflicts/positron-01_conflict.png new file mode 100644 index 0000000..26f5af7 Binary files /dev/null and b/images/conflicts/positron-01_conflict.png differ diff --git a/images/conflicts/positron-02_repair-script.png b/images/conflicts/positron-02_repair-script.png new file mode 100644 index 0000000..3d27b4a Binary files /dev/null and b/images/conflicts/positron-02_repair-script.png differ diff --git a/images/conflicts/positron-03_commit-repairs.png b/images/conflicts/positron-03_commit-repairs.png new file mode 100644 index 0000000..6890fd8 Binary files /dev/null and b/images/conflicts/positron-03_commit-repairs.png differ diff --git a/images/conflicts/positron-04_sync.png b/images/conflicts/positron-04_sync.png new file mode 100644 index 0000000..e05871f Binary files /dev/null and b/images/conflicts/positron-04_sync.png differ diff --git a/images/conflicts/positron-05_fixed.png b/images/conflicts/positron-05_fixed.png new file mode 100644 index 0000000..0f4f11c Binary files /dev/null and b/images/conflicts/positron-05_fixed.png differ diff --git a/images/conflicts/rstudio-01_conflict.png b/images/conflicts/rstudio-01_conflict.png new file mode 100644 index 0000000..231f333 Binary files /dev/null and b/images/conflicts/rstudio-01_conflict.png differ diff --git a/images/conflicts/rstudio-02_pull-conflict.png b/images/conflicts/rstudio-02_pull-conflict.png new file mode 100644 index 0000000..f12c26d Binary files /dev/null and b/images/conflicts/rstudio-02_pull-conflict.png differ diff --git a/images/conflicts/rstudio-03_auto-merge.png b/images/conflicts/rstudio-03_auto-merge.png new file mode 100644 index 0000000..919c33f Binary files /dev/null and b/images/conflicts/rstudio-03_auto-merge.png differ diff --git a/images/conflicts/rstudio-04_repair-script.png b/images/conflicts/rstudio-04_repair-script.png new file mode 100644 index 0000000..349ab6c Binary files /dev/null and b/images/conflicts/rstudio-04_repair-script.png differ diff --git a/images/conflicts/rstudio-05_commit-repairs.png b/images/conflicts/rstudio-05_commit-repairs.png new file mode 100644 index 0000000..e2f64f6 Binary files /dev/null and b/images/conflicts/rstudio-05_commit-repairs.png differ diff --git a/images/conflicts/rstudio-06_push.png b/images/conflicts/rstudio-06_push.png new file mode 100644 index 0000000..bd37537 Binary files /dev/null and b/images/conflicts/rstudio-06_push.png differ diff --git a/images/conflicts/rstudio-07_fixed.png b/images/conflicts/rstudio-07_fixed.png new file mode 100644 index 0000000..94a4409 Binary files /dev/null and b/images/conflicts/rstudio-07_fixed.png differ diff --git a/images/git_ignore/ignore-1-new-repo-p1.png b/images/git_ignore/ignore-1-new-repo-p1.png deleted file mode 100644 index 17a268a..0000000 Binary files a/images/git_ignore/ignore-1-new-repo-p1.png and /dev/null differ diff --git a/images/git_ignore/ignore-2-new-repo-p2.png b/images/git_ignore/ignore-2-new-repo-p2.png deleted file mode 100644 index 1c0bbbd..0000000 Binary files a/images/git_ignore/ignore-2-new-repo-p2.png and /dev/null differ diff --git a/images/git_ignore/ignore-3-template-search.png b/images/git_ignore/ignore-3-template-search.png deleted file mode 100644 index 3d6556e..0000000 Binary files a/images/git_ignore/ignore-3-template-search.png and /dev/null differ diff --git a/images/git_ignore/ignore-4-template-pick.png b/images/git_ignore/ignore-4-template-pick.png deleted file mode 100644 index 65c1075..0000000 Binary files a/images/git_ignore/ignore-4-template-pick.png and /dev/null differ diff --git a/images/git_ignore/ignore-5-rstudio-files.png b/images/git_ignore/ignore-5-rstudio-files.png deleted file mode 100644 index 96e38d1..0000000 Binary files a/images/git_ignore/ignore-5-rstudio-files.png and /dev/null differ diff --git a/images/git_ignore/ignore-6-viewing.png b/images/git_ignore/ignore-6-viewing.png deleted file mode 100644 index 2958065..0000000 Binary files a/images/git_ignore/ignore-6-viewing.png and /dev/null differ diff --git a/images/git_ignore/ignore-7-editing.png b/images/git_ignore/ignore-7-editing.png deleted file mode 100644 index a56ba34..0000000 Binary files a/images/git_ignore/ignore-7-editing.png and /dev/null differ diff --git a/images/git_ignore/ignore-8-commit.png b/images/git_ignore/ignore-8-commit.png deleted file mode 100644 index fd37534..0000000 Binary files a/images/git_ignore/ignore-8-commit.png and /dev/null differ diff --git a/images/github/rstudio-1-github-profile.png b/images/github/rstudio-1-github-profile.png deleted file mode 100644 index b3abbf6..0000000 Binary files a/images/github/rstudio-1-github-profile.png and /dev/null differ diff --git a/images/github/rstudio-3-new-repo-edits.png b/images/github/rstudio-3-new-repo-edits.png deleted file mode 100644 index e6a50a7..0000000 Binary files a/images/github/rstudio-3-new-repo-edits.png and /dev/null differ diff --git a/images/github/rstudio-5-new-repo-code-tab.png b/images/github/rstudio-5-new-repo-code-tab.png deleted file mode 100644 index bb76dc5..0000000 Binary files a/images/github/rstudio-5-new-repo-code-tab.png and /dev/null differ diff --git a/images/github/rstudio-5b-collabs-2-settings-collabs.png b/images/github/rstudio-5b-collabs-2-settings-collabs.png deleted file mode 100644 index 3a141c6..0000000 Binary files a/images/github/rstudio-5b-collabs-2-settings-collabs.png and /dev/null differ diff --git a/images/github/rstudio-5b-collabs-3-search-for-users.png b/images/github/rstudio-5b-collabs-3-search-for-users.png deleted file mode 100644 index ed9eb13..0000000 Binary files a/images/github/rstudio-5b-collabs-3-search-for-users.png and /dev/null differ diff --git a/images/github/rstudio-5b-collabs-4-added-new-user.png b/images/github/rstudio-5b-collabs-4-added-new-user.png deleted file mode 100644 index 79d52e7..0000000 Binary files a/images/github/rstudio-5b-collabs-4-added-new-user.png and /dev/null differ diff --git a/images/branches/git-branch-workflow.png b/images/graphics/git-branch-workflow.png similarity index 100% rename from images/branches/git-branch-workflow.png rename to images/graphics/git-branch-workflow.png diff --git a/images/conflicts/git-conflict-cause.png b/images/graphics/git-conflict-cause.png similarity index 100% rename from images/conflicts/git-conflict-cause.png rename to images/graphics/git-conflict-cause.png diff --git a/images/conflicts/git-conflict-workflow.png b/images/graphics/git-conflict-workflow.png similarity index 100% rename from images/conflicts/git-conflict-workflow.png rename to images/graphics/git-conflict-workflow.png diff --git a/images/rstudio/git-vocabulary.png b/images/graphics/git-vocabulary.png similarity index 100% rename from images/rstudio/git-vocabulary.png rename to images/graphics/git-vocabulary.png diff --git a/images/rstudio/git-workflow.png b/images/graphics/git-workflow.png similarity index 100% rename from images/rstudio/git-workflow.png rename to images/graphics/git-workflow.png diff --git a/images/rstudio/rstudio-icons.png b/images/graphics/rstudio-icons.png similarity index 100% rename from images/rstudio/rstudio-icons.png rename to images/graphics/rstudio-icons.png diff --git a/images/ignore/positron-01_untracked-csv.png b/images/ignore/positron-01_untracked-csv.png new file mode 100644 index 0000000..b6be202 Binary files /dev/null and b/images/ignore/positron-01_untracked-csv.png differ diff --git a/images/ignore/positron-02_files.png b/images/ignore/positron-02_files.png new file mode 100644 index 0000000..b68a911 Binary files /dev/null and b/images/ignore/positron-02_files.png differ diff --git a/images/ignore/positron-03_ignore-open.png b/images/ignore/positron-03_ignore-open.png new file mode 100644 index 0000000..bbe23fc Binary files /dev/null and b/images/ignore/positron-03_ignore-open.png differ diff --git a/images/ignore/positron-04_ignore-unsaved.png b/images/ignore/positron-04_ignore-unsaved.png new file mode 100644 index 0000000..58e674b Binary files /dev/null and b/images/ignore/positron-04_ignore-unsaved.png differ diff --git a/images/ignore/positron-05_ignore-saved.png b/images/ignore/positron-05_ignore-saved.png new file mode 100644 index 0000000..2894d2a Binary files /dev/null and b/images/ignore/positron-05_ignore-saved.png differ diff --git a/images/ignore/rstudio-01_untracked-csv.png b/images/ignore/rstudio-01_untracked-csv.png new file mode 100644 index 0000000..3eb04cf Binary files /dev/null and b/images/ignore/rstudio-01_untracked-csv.png differ diff --git a/images/ignore/rstudio-02_files.png b/images/ignore/rstudio-02_files.png new file mode 100644 index 0000000..bc3c30b Binary files /dev/null and b/images/ignore/rstudio-02_files.png differ diff --git a/images/ignore/rstudio-03_ignore-open.png b/images/ignore/rstudio-03_ignore-open.png new file mode 100644 index 0000000..bc6d44e Binary files /dev/null and b/images/ignore/rstudio-03_ignore-open.png differ diff --git a/images/ignore/rstudio-04_ignore-unsaved.png b/images/ignore/rstudio-04_ignore-unsaved.png new file mode 100644 index 0000000..7de36fe Binary files /dev/null and b/images/ignore/rstudio-04_ignore-unsaved.png differ diff --git a/images/ignore/rstudio-05_ignore-saved.png b/images/ignore/rstudio-05_ignore-saved.png new file mode 100644 index 0000000..c34928f Binary files /dev/null and b/images/ignore/rstudio-05_ignore-saved.png differ diff --git a/images/rstudio/rstudio-10-clone.png b/images/rstudio/rstudio-10-clone.png deleted file mode 100644 index 8c7025e..0000000 Binary files a/images/rstudio/rstudio-10-clone.png and /dev/null differ diff --git a/images/rstudio/rstudio-11-clone-repo-details.png b/images/rstudio/rstudio-11-clone-repo-details.png deleted file mode 100644 index c92c2d7..0000000 Binary files a/images/rstudio/rstudio-11-clone-repo-details.png and /dev/null differ diff --git a/images/rstudio/rstudio-12-finished-cloning.png b/images/rstudio/rstudio-12-finished-cloning.png deleted file mode 100644 index b37942f..0000000 Binary files a/images/rstudio/rstudio-12-finished-cloning.png and /dev/null differ diff --git a/images/rstudio/rstudio-12b-workflow.png b/images/rstudio/rstudio-12b-workflow.png deleted file mode 100644 index 31e2d18..0000000 Binary files a/images/rstudio/rstudio-12b-workflow.png and /dev/null differ diff --git a/images/rstudio/rstudio-13-new-script.png b/images/rstudio/rstudio-13-new-script.png deleted file mode 100644 index 09960b2..0000000 Binary files a/images/rstudio/rstudio-13-new-script.png and /dev/null differ diff --git a/images/rstudio/rstudio-13b-icons.png b/images/rstudio/rstudio-13b-icons.png deleted file mode 100644 index 8f6ff5f..0000000 Binary files a/images/rstudio/rstudio-13b-icons.png and /dev/null differ diff --git a/images/rstudio/rstudio-13c-diff.png b/images/rstudio/rstudio-13c-diff.png deleted file mode 100644 index f382088..0000000 Binary files a/images/rstudio/rstudio-13c-diff.png and /dev/null differ diff --git a/images/rstudio/rstudio-14-commit-message.png b/images/rstudio/rstudio-14-commit-message.png deleted file mode 100644 index 1930317..0000000 Binary files a/images/rstudio/rstudio-14-commit-message.png and /dev/null differ diff --git a/images/rstudio/rstudio-14b-git-add-symbol.png b/images/rstudio/rstudio-14b-git-add-symbol.png deleted file mode 100644 index 553fa06..0000000 Binary files a/images/rstudio/rstudio-14b-git-add-symbol.png and /dev/null differ diff --git a/images/rstudio/rstudio-15-finished-commiting.png b/images/rstudio/rstudio-15-finished-commiting.png deleted file mode 100644 index 197ec34..0000000 Binary files a/images/rstudio/rstudio-15-finished-commiting.png and /dev/null differ diff --git a/images/rstudio/rstudio-15b-pull.png b/images/rstudio/rstudio-15b-pull.png deleted file mode 100644 index ef3055f..0000000 Binary files a/images/rstudio/rstudio-15b-pull.png and /dev/null differ diff --git a/images/rstudio/rstudio-16-pulled.png b/images/rstudio/rstudio-16-pulled.png deleted file mode 100644 index 2f7c8fd..0000000 Binary files a/images/rstudio/rstudio-16-pulled.png and /dev/null differ diff --git a/images/rstudio/rstudio-17-finished-pulling-new-script.png b/images/rstudio/rstudio-17-finished-pulling-new-script.png deleted file mode 100644 index ae3a1a6..0000000 Binary files a/images/rstudio/rstudio-17-finished-pulling-new-script.png and /dev/null differ diff --git a/images/rstudio/rstudio-18-pushed.png b/images/rstudio/rstudio-18-pushed.png deleted file mode 100644 index a517540..0000000 Binary files a/images/rstudio/rstudio-18-pushed.png and /dev/null differ diff --git a/images/rstudio/rstudio-19-updated-repo.png b/images/rstudio/rstudio-19-updated-repo.png deleted file mode 100644 index edd8067..0000000 Binary files a/images/rstudio/rstudio-19-updated-repo.png and /dev/null differ diff --git a/images/rstudio/rstudio-2-new-repo.png b/images/rstudio/rstudio-2-new-repo.png deleted file mode 100644 index 720555b..0000000 Binary files a/images/rstudio/rstudio-2-new-repo.png and /dev/null differ diff --git a/images/rstudio/rstudio-4-new-repo-landing-page.png b/images/rstudio/rstudio-4-new-repo-landing-page.png deleted file mode 100644 index 47fa366..0000000 Binary files a/images/rstudio/rstudio-4-new-repo-landing-page.png and /dev/null differ diff --git a/images/rstudio/rstudio-5b-collabs-1-settings.png b/images/rstudio/rstudio-5b-collabs-1-settings.png deleted file mode 100644 index abd8745..0000000 Binary files a/images/rstudio/rstudio-5b-collabs-1-settings.png and /dev/null differ diff --git a/images/rstudio/rstudio-6-new-repo-link.png b/images/rstudio/rstudio-6-new-repo-link.png deleted file mode 100644 index 0a8d29f..0000000 Binary files a/images/rstudio/rstudio-6-new-repo-link.png and /dev/null differ diff --git a/images/rstudio/rstudio-7-fresh-start.png b/images/rstudio/rstudio-7-fresh-start.png deleted file mode 100644 index e9b80c3..0000000 Binary files a/images/rstudio/rstudio-7-fresh-start.png and /dev/null differ diff --git a/images/rstudio/rstudio-8-new-project.png b/images/rstudio/rstudio-8-new-project.png deleted file mode 100644 index 7bde5fd..0000000 Binary files a/images/rstudio/rstudio-8-new-project.png and /dev/null differ diff --git a/images/rstudio/rstudio-9-version-control.png b/images/rstudio/rstudio-9-version-control.png deleted file mode 100644 index 0462192..0000000 Binary files a/images/rstudio/rstudio-9-version-control.png and /dev/null differ diff --git a/index.qmd b/index.qmd index 99b70a3..69f5627 100644 --- a/index.qmd +++ b/index.qmd @@ -6,7 +6,7 @@ title: "Overview" Logo for GitHub -This workshop provides an overview of what "version control" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using GitHub either by itself or with Git via RStudio**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement! +This workshop provides an overview of what "version control" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using GitHub either through a browser or through software installed on your computer.** We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement! ### Citing These Materials @@ -26,7 +26,7 @@ If your institution has a dedicated IT team that has sole power to install softw There are a couple of distinct use-cases you might have for GitHub that will affect what preparation you need to do before this workshop. Consider the tabs below and follow all of the numbered steps in the choice that best fits your needs. -:::{.panel-tabset} +::::{.panel-tabset} ### GitHub By Itself #### 1. Create a GitHub Account @@ -65,18 +65,52 @@ The below preparation steps includes some code for making sure everything is ins #### 5. Check that Git's Installation Worked -{{< include prep-steps/check_git-installation.qmd >}} +{{< include prep-steps/check_git-install_rstudio.qmd >}} -#### 6. Connect Git and GitHub +#### 6. Connect RStudio/Git and GitHub -{{< include prep-steps/connect_git-github.qmd >}} +{{< include prep-steps/connect_git-github_rstudio.qmd >}} #### 7. Celebrate! {{< include prep-steps/celebrate.qmd >}} +### GitHub with Positron + +:::{.callout-note} +#### Positron vs. Visual Studio Code + +[Visual Studio Code](https://code.visualstudio.com/) (a.k.a. VS Code) is an IDE favored by many software developers. Positron itself is actually a "fork" of VS Code's software! However, Positron offers some additional functionalities to support R users and--given that most working group members are primarily R coders if they code--Positron is what we will be using in this workshop. + +However, if you are a VS Code user, much of the Positron content will actually work for you with some (or potentially _no_) adjustment. ::: +#### 1. Create a GitHub Account + +{{< include prep-steps/create_github-acct.qmd >}} + +#### 2. Install R + +{{< include prep-steps/install_r.qmd >}} + +#### 3. Install Positron + +{{< include prep-steps/install_positron.qmd >}} + +#### 4. Install Git + +{{< include prep-steps/install_git.qmd >}} + +#### 5. Connect Positron/Git and GitHub + +{{< include prep-steps/connect_git-github_positron.qmd >}} + +#### 6. Celebrate! + +{{< include prep-steps/celebrate.qmd >}} + +:::: + ## GitHub + Science Publications The reproducibility and collaborative benefits of GitHub for working scientists is well appreciated and increasingly well published upon. See below for brief synopses of papers published in this realm that we think may resonate with your team's disciplinary backgrounds and motivations. diff --git a/portfolio.qmd b/portfolio.qmd index 33e58df..bd98ebe 100644 --- a/portfolio.qmd +++ b/portfolio.qmd @@ -106,7 +106,7 @@ If you act on the suggestions we've outlined above you will already be well on t Personal websites are a cool way to visually convey everything that goes into a portfolio--your background, work experiences, interests, accomplishments, projects, contact information, etc. With a website, you can be more creative and flexible in how you want to present yourself to others. Plus, non-GitHub users may be more inclined to navigate someone's personal website rather than their GitHub profile. A further benefit of creating a personal website is that you will learn (and demonstrate!) a suite of additional skills that contribute to your portfolio in and of themselves. -Although the topic of creating your own personal website is outside the scope of this workshop, there are tons of resources on how to get started. If you're interested, check out the SciComp team's tutorial on [building a website with Quarto](https://lter.github.io/scicomp/tutorials.html#building-a-website-with-quarto). Also feel free to check out [Sam Csik](https://samanthacsik.github.io/)'s tutorials on how to [create](https://ucsb-meds.github.io/creating-quarto-websites/) and [customize](https://ucsb-meds.github.io/customizing-quarto-websites/#/title-slide) your website using [Quarto](https://quarto.org/). +Although the topic of creating your own personal website is outside the scope of this workshop, there are tons of resources on how to get started. If you're interested, check out the SciComp team's workshop on [building a website with Quarto](https://lter.github.io/workshop-quarto/). Also feel free to check out [Sam Csik](https://samanthacsik.github.io/)'s tutorials on how to [create](https://ucsb-meds.github.io/creating-quarto-websites/) and [customize](https://ucsb-meds.github.io/customizing-quarto-websites/#/title-slide) your website using [Quarto](https://quarto.org/). Since this will be a personal website deployed through [GitHub Pages](https://pages.github.com/), remember to name your Quarto project and GitHub repo: `.github.io`, replacing `` with your actual username. You're only allowed one user website with the github.io suffix. Follow the instructions in the linked tutorials to deploy the website via GitHub when you're done! If all goes well, your website will be live at: https://\.github.io/ diff --git a/prep-steps/check_git-installation.qmd b/prep-steps/check_git-install_rstudio.qmd similarity index 92% rename from prep-steps/check_git-installation.qmd rename to prep-steps/check_git-install_rstudio.qmd index f857462..d2cd84d 100644 --- a/prep-steps/check_git-installation.qmd +++ b/prep-steps/check_git-install_rstudio.qmd @@ -4,11 +4,6 @@ Regardless of your operating system, once you've installed Git, check that worke which git ``` -:::{.panel-tabset} -#### Confirm Connection in RStudio - RStudio should also be able to detect Git so let's check from that side too. In RStudio click through the following menus: "Tools" {{< fa arrow-right >}} "Global Options" {{< fa arrow-right >}} "Git / SVN" (cardboard box icon in left sidebar). **If you see a file path under "Git executable" then you are good to go!** If Git was _not_ detected, this may be caused by having your RStudio session open while you installed Git for the first time. **In that case, please close and restart RStudio before checking again.** - -::: diff --git a/prep-steps/connect_git-github_positron.qmd b/prep-steps/connect_git-github_positron.qmd new file mode 100644 index 0000000..b030a8d --- /dev/null +++ b/prep-steps/connect_git-github_positron.qmd @@ -0,0 +1,70 @@ +The last step to take before you’re all set for the workshop is to get these components talking to one another! One reason to use Positron instead of RStudio is because of how much simpler this step is for Positron. Instead of needing to write code, we can do a little authentication dance with buttons in the browser and afterwards, everything will 'just work.' + +To begin, open Positron. You should have a screen that looks something like the below screen capture. Note that you might be in "light mode" depending on your computer settings but that should not affect which buttons to click or where they can be found. + +

+Screen capture of the default starting page of the Positron app +

+ +From there, go to the left sidebar and click the branch icon ( {{< fa code-branch >}} ). It should be the third option from the top. Once you are there, **click "Clone Repository".** + +

+Screen capture of the left sidebar of Positron inside of the 'source control' option +

+ +This should automatically open the search bar in the top middle of Positron and present you with a single option titled "Clone from GitHub". **Click that option.** + +

+Screen capture of top middle of Positron with highlighted prompt to 'Clone from GitHub' +

+ +Once you've clicked that option, you should be presented with the following pop up where Positron is telling you that Positron's GitHub extension wants to talk to the online version of GitHub. **Click "Allow".** + +

+Screen capture of pop-up window where an extension called 'GitHub' is asking to sign in via GitHub with 'allow' and 'cancel' options +

+ +Positron will now allow provide you with a code of random letters/numbers that you'll need to share with GitHub. Helpfully, a new pop-up will appear where one of the options is "Copy & Continue to Github"; **click that option.** + +

+Screen capture of pop-up window with a red rectangle covering a code and buttons for either copying that code and continuing to GitHub or cancelling +

+ +Once you click "Copy & Continue to Github" button, you should automatically be sent to your default web browser application and be prompted to choose which GitHub account to use. Most users will have only one option so go ahead and **click "Continue" next to that profile.** + +

+Screen capture of GitHub window with a single GitHub user option and a blue 'continue' button to the right of that profile +

+ +You'll next need to put in the code that you got from Positron. You should be able to simply paste it in because you just copied it! **_After you've entered the code_, click "Continue".** + +

+Screen capture of a GitHub window prompting the user to provide an eight-digit code with a blue 'continue' button beneath the empty code field +

+ +GitHub will now provide you with a list of the permissions that Positron is asking for and ask you to approve them. These permissions are required for you to work with Positron so feel free to read through them but ultimately you must scroll down and **click "Authorize".** + +If you are a member of any GitHub organizations, they will be listed below the list of requested permissions but you should just ignore those and scroll past them. + +

+First part of a screenshot of a GitHub webpage asking for confirmation to authorize the Positron application to access a GitHub user's content and account information +Second part of a screenshot of a GitHub webpage asking for confirmation to authorize the Positron application to access a GitHub user's content and account information +

+ +:::{.callout-note} +#### GitHub Login Prompt + +If you have not recently logged in to GitHub, you will be sent to the standard GitHub login page. If you are sent there, log in as normal (i.e., either by using your username/password or with the 2FA option provided by the GitHub Mobile app). +::: + +Once you've worked through the above step, you should get a confirmation page from GitHub that looks like the following screen capture. + +

+Screen capture of a GitHub browser window that says 'congratulations, you are all set!' +

+ +You will know that you've followed these steps correctly if, when you return to Positron, the search bar in the top middle (that said "Clone from GitHub" before) now has a list of repositories to which you have access. + +

+Screen capture of Positron where the search bar in the middle displays a number of GitHub repositories +

diff --git a/prep-steps/connect_git-github.qmd b/prep-steps/connect_git-github_rstudio.qmd similarity index 100% rename from prep-steps/connect_git-github.qmd rename to prep-steps/connect_git-github_rstudio.qmd diff --git a/prep-steps/install_positron.qmd b/prep-steps/install_positron.qmd new file mode 100644 index 0000000..9f819fd --- /dev/null +++ b/prep-steps/install_positron.qmd @@ -0,0 +1 @@ +Once you have R (ver. ≥4.0), [install Positron](https://positron.posit.co/). If you already have Positron installed, you may want to make sure that you're using a recent version to take advantage of the features available in the most recent version. diff --git a/prep-steps/install_r.qmd b/prep-steps/install_r.qmd index 2cd83a2..288a15e 100644 --- a/prep-steps/install_r.qmd +++ b/prep-steps/install_r.qmd @@ -1,10 +1,3 @@ -Now you should [install R](https://www.r-project.org/) on your computer. If you already have R, check that you have at least version 4.0.0 by running the following {{< fa brands r-project >}} R code: +Now you should [install R](https://www.r-project.org/) on your computer. If you already have R, check that you have at least version 4.0.0 by looking at the "Console" of your IDE of choice. -```{r r-ver-check} -#| eval: false - -# Run me in RStudio's "Console" -version$version.string -``` - -If your version starts with a 3 (e.g., the above code returns "R version 3..."), please update R to make sure all packages behave as expected. +If your version starts with a "3", please update R to make sure all packages behave as expected. diff --git a/rstudio.qmd b/rstudio.qmd deleted file mode 100644 index 53acef6..0000000 --- a/rstudio.qmd +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: "Using GitHub with an IDE" ---- - -## Module Learning Objectives - -By the end of this module, you will be able to: - -- Describe the IDE-to-GitHub order of operations -- Define fundamental Git vocabulary -- Create a local version-controlled repository that is connected to GitHub - -## Overview of Git Workflow - -Before we get into using Git and GitHub through an IDE (Integrated Development Environment), it will be helpful to review the major steps of including version control as you work on code. Also, note that "IDE" is the technical term for a piece of software that is used to create software; RStudio, Visual Studio Code, and Positron are all examples of IDEs with which you may already be familiar. - -Beginning on your local computer, you make **changes** to a file in a folder that you have previously marked for version control tracking (i.e., a **working directory**). Once those changes are made you can **stage changes** within your local computer. After staging, it is best to retrieve the latest file versions from the cloud. You likely will already be up-to-date but this preemptive step can save you a lot of heartache down the line. Once you've confirmed that you have the latest file versions, you can shift the revised file(s) to the cloud where any GitHub users with access to your project can access the most recent file and look at the history of all previous changes. - -:::{.callout-note} -#### "Pull & Push" vs. "Sync" - -Some IDEs (e.g., Positron, VS Code) combine pulling and pushing into a single operation called "sync". These IDEs also support pulling and pushing separately so you may want to do those operations separately until you are completely comfortable with the necessary order of operations. -::: - -

-Graphic of a white rectangle on top of a blue square. The white rectangle has a happy cloud image and is labeled 'GitHub' while the blue square has an emoji-style laptop. Numbered steps start at the bottom left and work towards the top right as follows: '1-make changes', '2-stage changes', '3-retrieve latest from GitHub', and '4-put in GitHub' -

- -## Git Vocabulary - -Finally, it will be helpful to introduce four key pieces of vocabulary before we dive into the interactive component of this workshop. - -- **Clone** = copy the entire contents of a GitHub repository to your local computer (done once per computer) - -* **Commit** = move a changed local file to your local staging area (step 2 of the above diagram) - -* **Pull** = get file(s) *from* the cloud *to* your local computer -- opposite of a "push" (step 3) - -* **Push** = move file(s) *to* the cloud *from* your local computer -- opposite of a "pull" (step 4) - -

-Graphics demonstrating a clone (copy entire folder from GitHub to a copmputer), a commit (putting local changes into the staging area), a pull (overwriting local copies with GitHub versions of the same), and a push (overwriting GitHub versions of files with the committed local versions) -

- -## Cloning a Repository - -Now, the first step in using Git with RStudio is cloning the repository from GitHub. Note for clarity that in the screenshots below, **GitHub is in dark mode** while **RStudio is in light mode**. To clone a repository, follow these steps: - -Navigate to the repository on GitHub and click on **Code**. Select "HTTPS" and copy the link. - -

-Screenshot of the menu that appears in a GitHub repository when someone clicks the 'code' button -

- -Now, return to (or open!) RStudio. - -

-Screenshot of RStudio when no project or scripts are open -

- -Go to the **Project** tab on the top right corner and click **New Project...** - -

-Screenshot of the menu that appears when someone clicks 'Project: (None)' in RStudio and hovers over the 'New Project...' button -

- -Select **Version Control**. - -

-Screenshot of a menu with three options: 'new directory', 'existing directory', and 'version control' -

- -Select **Git**. - -

-Screenshot of a menu with two options: 'git' and 'subversion' -

- -Paste the repository URL that you just copied from GitHub. Choose a file path to save your project to. - -

-Screenshot of a menu with three open text fields, one for the 'repository URL', one for 'project directory name' and one for 'create project as subdirectory of' -

- -Now we have finished cloning the repository to our RStudio! Notice that we are working in our `git-practice` project and that our `README.md` file shows up under the list of files, just like in our GitHub repository. - -

-Screenshot of RStudio after a project has been selected. The project name--in the top right corner--is circled in red -

- -## Workflow Refresher - -The typical workflow with Git goes like this: - -**Step 1**: You modify files in your working directory and save them as usual. - -**Step 2**: You **stage** files to mark your intention to "commit" them and then **commit** that version of those files. - - - In RStudio, "staging" is done by checking the box next to a given file in the "Git" tab - - Committing files permanently stores them as snapshots to your Git directory - -**Step 3**: You **pull** the most recent changes to make sure you've been editing the latest versions. - -**Step 4**: You **push** your the version of your files that you committed to GitHub. - -Here is the infographic from the start of this chapter again, which shows the same workflow: - -

-Graphic of a white rectangle on top of a blue square. The white rectangle has a happy cloud image and is labeled 'GitHub' while the blue square has an emoji-style laptop. Numbered steps start at the bottom left and work towards the top right as follows: '1-make changes', '2-stage changes', '3-retrieve latest from GitHub', and '4-put in GitHub' -

- -## Stage versus Commit - -The functional difference between "staging" a file and "committing" one can be a little tough to grasp at first so let's explore that briefly here. We can make an analogy with taking a family picture, where each family member would represent a file. - -- **Staging** files is like deciding which family member(s) are going to be in your next picture -- **Committing** is like taking the picture - -This 2-step process enables you to flexibly group files into a specific commit. Those groupings can be helpful to you later if you're trying to find what you changed for a specific task (because those changes likely are all in the same commit). - -## Creating a New File - -Let's try out a simple Git workflow by first creating a new file. This is **Step 1** of the process. We can add new R scripts and files to our repository through RStudio. Try creating a new script by going to **File** > **New File** > **R Script**. Feel free to type anything you want into this script as an example. Name this script after yourself. In the screenshot below, I have named my script `angel-script.R`. - -Once you are done, navigate to the **Git** tab on the upper left corner. You should see your new script show up there along with a `.gitignore` and `git-practice.Rproj` file. Do not worry about the `.gitignore` file for now, it was created by RStudio to make sure that some temporary files are not tracked by Git. The `git-practice.Rproj` file will save your settings and open tabs when you close the project, and will restore these settings the next time you open it. - -

-Screenshot of RStudio with an open script and several uncommitted changes identified in the 'Git' pane. Lack of commit is identified by double yellow squares containing a question mark -

- -Notice that there are color-coded icons next to the files in the "Git" tab. These icons are shorthand for the status--according to Git--of every* file in your working directory. Not technically "every" file because files that are tracked but haven't been modified are not included. See below for definitions. - -

-A legend of five icons RStudio uses to indicate Git status of a file. Yellow question mark = untracked (file not tracked by Git). Green 'A' = added (file marked to start tracking). Blue 'M' = modified (tracked file with changes). Red 'D' = deleted (tracked file that was deleted). Purple 'R' = renamed (tracked file that was renamed) -

- -In our case, it means that our R script, `.gitignore`, and `git-practice.Rproj` files have never been tracked by Git (since these files were just created). Note also that the `README.md` file is not listed, but it exists (check the Files pane). It is because files that are tracked but have no modifications since the last commit are not listed. - -### Adding our Script to the Next Commit - -Let us look at the diff of our script. Click on the **Diff** tab. - -

-Screenshot of the 'diff' button--circled in red--in the 'git' pane of RStudio -

- -Checking our script, we can see the new lines that we just typed are in green, which indicates that these lines have been added for Git. We would like to save a snapshot of this version of our script. Since we've just done **Step 1**, here are the rest of the steps we will need to do to get our script to show up on our GitHub repository: - -**Step 2**: Add the file to the next commit by checking the box in front of the file name. Note that the two `?` icons will change to a single `A` on the left to show you that this file is now staged to be part of the next commit. - -**Step 3**: In the right pane, type a short but descriptive commit message detailing what you have done so far. Then click on the **Commit** button to save this version of the script in the Git database. - -

-Screenshot of the commit menu of RStudio where one file has been staged and an informative commit message has been entered -

- -If all of the above steps went well, you should see something like this: - -

-Screenshot of the success message after a commit has been made -

- -Notice that Git tells us that `1 file changed` because we've just added a new file to our commit. Now close the window. Before sending our changes back to GitHub, we should make sure that the copy of the repository on RStudio is completely up-to-date with the one on GitHub to avoid any conflicts. - -### Getting the Latest Updates - -There are two Git commands to exchange between a local and remote versions of a repository: - -- Pull: Git will get the latest remote version and try to merge it with your local version - -- Push: Git will send your local version to the remote version of the repository (in our case GitHub) - -**Before sending your local version to the remote**, you should always get the latest remote version first. In other words, you should pull first and push second. This is the way Git protects the remote version against incompatibilities with the local version. You always deal with potential problems on your local machine. Therefore your sequence will always be: - -1. Commit -2. Pull -3. Push - -Of course RStudio has icons for that on top of the "Git" tab, with the blue arrow down being for pull and the green arrow up being for push. Remember the icons are organized in sequence! - -Let us do the pull and push to synchronized the remote repositories. Click on the **Pull** button to pull changes (if any) from the GitHub repository to the copy on RStudio. We have now synchronized the local (our computer) and remote (on GitHub) versions of our repository. You may have noticed that all of our preceding graphics use **blue** for **pull**-related content and **green** for **push**-related information. Hopefully that helps cement the two ideas in your mind! - -

-Screenshot of the blue 'pull' button and green 'push' button in RStudio -

- -In my case, it turns out that a new script, `lyon-script`, was added to the GitHub repository by a collaborator while I was making my own script. Since I have just pulled, `lyon-script` now shows up in my RStudio files. - -

-Screenshot of the message returned when you pull files you didn't have locally from GitHub -

- -

-Screenshot of RStudio with the 'git' pane underlined in red where it says 'your branch is ahead of origin/main by 2 commits' -

- -A new message has popped up for me: "Your branch is ahead of 'origin/main' by two commits". This means that I have two additional commits on my local machine that I never shared back to the remote repository on GitHub. If I look at the content of my repository on GitHub, I will see just the `README.md` and `lyon-script`. My changes are NOT in the cloud yet. You might be seeing a similar message as well. - -### Sending Changes back to GitHub - -So how do we send our changes back to GitHub? Locate the **Push** button on the "Git" tab and click on it. Now your script should show up in the GitHub repository! - -

-Screenshot of the blue 'pull' button and green 'push' button in RStudio -

- -Once you click that button you should get a success screen like the one pictured below. - -

-Screenshot of the message received when a push is performed successfully from RStudio -

- -Navigate back to the GitHub website and find your repository. Check to see if your script has been added correctly. In my case, `angel-script.R` finally shows up in my repository. - -

-Screenshot of a GitHub repository with the commits made in earlier screenshots shown in its history -

- -:::callout-note -## If RStudio ever asks for a "password"... - -If your personal access token (PAT) was not set up correctly with RStudio or if it expired, then RStudio will ask for your GitHub username and password in a pop-up when you try to push. **Please be aware that when they ask for a "password", they actually meant your token!** Enter your token in the field and you should be able to push now. Make sure to run `gitcreds::gitcreds_set()` to set a valid token afterwards so you don't have to enter it manually every time! -::: - -### Rinse and Repeat - -Great! Now that your script has been added to the group repository, you should try to repeat the same workflow over again just to get a feel for how it works. Go back to RStudio and edit your own script. Save those edits, add your edited file to the staging area, write a commit message, then commit your changes. After committing, make sure to pull first then push after! When you pull, you might notice that scripts from your group members/collaborators will show up in your RStudio files. - -Make sure to work on your own script. If you and another group member work on the same script at the same time, this may lead to merge conflicts with Git. If two people were to work on the same script, they may be making different edits on the same lines, and Git would not know which edits to keep. To avoid merge conflicts, be mindful of what files you are working on and always communicate this to your group members!