diff --git a/episodes/01-basics.md b/episodes/01-basics.md index 91d67a467d..6633f92053 100644 --- a/episodes/01-basics.md +++ b/episodes/01-basics.md @@ -38,20 +38,20 @@ think of it as a recording of your progress: you can rewind to start at the base document and play back each change you made, eventually arriving at your more recent version. -![](fig/play-changes.svg){alt='Changes Are Saved Sequentially'} +![](fig/play-changes.svg){alt='A diagram demonstrating how a single document grows as the result of sequential changes'} Once you think of changes as separate from the document itself, you can then think about "playing back" different sets of changes on the base document, ultimately resulting in different versions of that document. For example, two users can make independent sets of changes on the same document. -![](fig/versions.svg){alt='Different Versions Can be Saved'} +![](fig/versions.svg){alt='A diagram with one source document that has been modified in two different ways to produce two different versions of the document'} Unless multiple users make changes to the same section of the document - a [conflict](../learners/reference.md#conflict) - you can incorporate two sets of changes into the same base document. -![](fig/merge.svg){alt='Multiple Versions Can be Merged'} +![](fig/merge.svg){alt='A diagram that shows the merging of two different document versions into one document that contains all of the changes from both versions'} A version control system is a tool that keeps track of these changes for us, effectively creating different versions of our files. It allows us to decide @@ -125,5 +125,3 @@ the same files concurrently. - Version control also allows many people to work in parallel. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/03-create.md b/episodes/03-create.md index 2dfb60f72e..b1ccb578cd 100644 --- a/episodes/03-create.md +++ b/episodes/03-create.md @@ -23,7 +23,7 @@ we can start using it. We will continue with the story of Wolfman and Dracula who are investigating if it is possible to send a planetary lander to Mars. -![](fig/motivatingexample.png){alt='motivatingexample'} +![](fig/motivatingexample.png){alt='The main elements of the story: Dracula, Wolfman, the Mummy, Mars, Pluto and The Moon'} [Werewolf vs dracula](https://www.deviantart.com/b-maze/art/Werewolf-vs-Dracula-124893530) by [b-maze](https://www.deviantart.com/b-maze) / [Deviant Art](https://www.deviantart.com/). [Mars](https://en.wikipedia.org/wiki/File:OSIRIS_Mars_true_color.jpg) by European Space Agency / @@ -213,5 +213,3 @@ Therefore, always check your current directory using the command `pwd`. - Git stores all of its repository data in the `.git` directory. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/04-changes.md b/episodes/04-changes.md index 3c06e65016..337dea69b1 100644 --- a/episodes/04-changes.md +++ b/episodes/04-changes.md @@ -334,7 +334,7 @@ than you would like! :::::::::::::::::::::::::::::::::::::::::::::::::: -![](fig/git-staging-area.svg){alt='The Git Staging Area'} +![](fig/git-staging-area.svg){alt='A diagram showing how "git add" registers changes in the staging area, while "git commit" moves changes from the staging area to the repository'} Let's watch as our changes to a file move from our editor to the staging area @@ -587,7 +587,7 @@ we first need to add the changed files to the staging area (`git add`) and then commit the staged changes to the repository (`git commit`): -![](fig/git-committing.svg){alt='The Git Commit Workflow'} +![](fig/git-committing.svg){alt='A diagram showing two documents being separately staged using git add, before being combined into one commit using git commit'} ::::::::::::::::::::::::::::::::::::::: challenge @@ -791,5 +791,3 @@ $ git diff me.txt - Write a commit message that accurately describes your changes. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/05-history.md b/episodes/05-history.md index fcfbd1364f..c6bae293f6 100644 --- a/episodes/05-history.md +++ b/episodes/05-history.md @@ -295,12 +295,12 @@ the commit in which we made the change we're trying to discard. In the example below, we want to retrieve the state from before the most recent commit (`HEAD~1`), which is commit `f22b25e`: -![](fig/git-checkout.svg){alt='Git Checkout'} +![](fig/git-checkout.svg){alt='A diagram showing how git checkout HEAD~1 can be used to restore the previous version of two files'} So, to put it all together, here's how Git works in cartoon form: -![https://figshare.com/articles/How_Git_works_a_cartoon/1328266](fig/git_staging.svg) +![https://figshare.com/articles/How_Git_works_a_cartoon/1328266](fig/git_staging.svg){alt='A diagram showing the entire git workflow: local changes are staged using git add, applied to the local repository using git commit, and can be restored from the repository using git checkout'} ::::::::::::::::::::::::::::::::::::::::: callout @@ -621,5 +621,3 @@ $ git log --patch HEAD~9 *.txt - `git checkout` recovers old versions of files. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/07-github.md b/episodes/07-github.md index eb72876696..41824ae72f 100644 --- a/episodes/07-github.md +++ b/episodes/07-github.md @@ -36,7 +36,7 @@ world. To this end we are going to create a *remote* repository that will be lin Log in to [GitHub](https://github.com), then click on the icon in the top right corner to create a new repository called `planets`: -![](fig/github-create-repo-01.png){alt='Creating a Repository on GitHub (Step 1)'} +![](fig/github-create-repo-01.png){alt='The first step in creating a repository on GitHub: clicking the "create new" button'} Name your repository "planets" and then click "Create Repository". @@ -45,12 +45,12 @@ Note: Since this repository will be connected to a local repository, it needs to .gitignore" and "Add a license." See the "GitHub License and README files" exercise below for a full explanation of why the repository needs to be empty. -![](fig/github-create-repo-02.png){alt='Creating a Repository on GitHub (Step 2)'} +![](fig/github-create-repo-02.png){alt='The second step in creating a repository on GitHub: filling out the new repository form to provide the repository name, and specify that neither a readme nor a license should be created'} As soon as the repository is created, GitHub displays a page with a URL and some information on how to configure your local repository: -![](fig/github-create-repo-03.png){alt='Creating a Repository on GitHub (Step 3)'} +![](fig/github-create-repo-03.png){alt='The summary page displayed by GitHub after a new repository has been created. It contains instructions for configuring the new GitHub repository as a git remote'} This effectively does the following on GitHub's servers: @@ -64,11 +64,11 @@ If you remember back to the earlier [episode](04-changes.md) where we added and committed our earlier work on `mars.txt`, we had a diagram of the local repository which looked like this: -![](fig/git-staging-area.svg){alt='The Local Repository with Git Staging Area'} +![](fig/git-staging-area.svg){alt='A diagram showing how "git add" registers changes in the staging area, while "git commit" moves changes from the staging area to the repository'} Now that we have two repositories, we need a diagram like this: -![](fig/git-freshly-made-github-repo.svg){alt='Freshly-Made GitHub Repository'} +![](fig/git-freshly-made-github-repo.svg) {alt='A diagram illustrating how the GitHub "planets" repository is also a git repository like our local repository, but that it is currently empty'} Note that our local repository still contains our earlier work on `mars.txt`, but the remote repository on GitHub appears empty as it doesn't contain any files yet. @@ -80,7 +80,7 @@ GitHub repository a [remote](../learners/reference.md#remote) for the local repo The home page of the repository on GitHub includes the URL string we need to identify it: -![](fig/github-find-repo-string.png){alt='Where to Find Repository URL on GitHub'} +![](fig/github-find-repo-string.png){alt='Clicking the "Copy to Clipboard" button on GitHub to obtain the repository's URL'} Click on the 'SSH' link to change the [protocol](../learners/reference.md#protocol) from HTTPS to SSH. @@ -95,7 +95,7 @@ minimum level for GitHub. :::::::::::::::::::::::::::::::::::::::::::::::::: -![](fig/github-change-repo-string.png){alt='Changing the Repository URL on GitHub'} +![](fig/github-change-repo-string.png){alt='A screenshot showing that clicking on "SSH" will make GitHub provide the SSH URL for a repository instead of the HTTPS URL'} Copy that URL from the browser, go into the local `planets` repository, and run this command: @@ -364,7 +364,7 @@ to make Git default to using the terminal for usernames and passwords. Our local and remote repositories are now in this state: -![](fig/github-repo-after-first-push.svg){alt='GitHub Repository After First Push'} +![](fig/github-repo-after-first-push.svg){alt='A diagram showing how "git push origin" will push changes from the local repository to the remote, making the remote repository an exact copy of the local repository.'} ::::::::::::::::::::::::::::::::::::::::: callout @@ -551,5 +551,3 @@ create mode 100644 README.md - `git pull` copies changes from a remote repository to a local repository. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/08-collab.md b/episodes/08-collab.md index c67f9f098f..efaeb0eec2 100644 --- a/episodes/08-collab.md +++ b/episodes/08-collab.md @@ -39,7 +39,7 @@ The Owner needs to give the Collaborator access. In your repository page on GitH button on the right, select "Collaborators", click "Add people", and then enter your partner's username. -![](fig/github-add-collaborators.png){alt='screenshot of repository page with Settings then Collaborators selected, showing how to add Collaborators in a GitHub repository'} +![](fig/github-add-collaborators.png){alt='A screenshot of the GitHub Collaborators settings page, which is accessed by clicking "Settings" then "Collaborators"'} To accept access to the Owner's repo, the Collaborator needs to go to [https://github.com/notifications](https://github.com/notifications) @@ -65,7 +65,7 @@ If you choose to clone without the clone path you will clone inside your own planets folder! Make sure to navigate to the `Desktop` folder first. -![](fig/github-collaboration.svg){alt='After Creating Clone of Repository'} +![](fig/github-collaboration.svg){alt='A diagram showing that "git clone" can create a copy of a remote GitHub repository, allowing a second person to create their own local repository that they can make changes to.'} The Collaborator can now make a change in her clone of the Owner's repository, exactly the same way as we've been doing before: @@ -262,5 +262,3 @@ What are some of the benefits of using version control, Git and GitHub? - `git clone` copies a remote repository to create a local repository with a remote called `origin` automatically set up. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/09-conflict.md b/episodes/09-conflict.md index b1e9e0b3dc..67b3d47bd0 100644 --- a/episodes/09-conflict.md +++ b/episodes/09-conflict.md @@ -125,7 +125,7 @@ hint: (e.g., 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details. ``` -![](fig/conflict.svg){alt='The Conflicting Changes'} +![](fig/conflict.svg){alt='A diagram showing a conflict that might occur when two sets of independent changes are merged'} Git rejects the push because it detects that the remote repository has new updates that have not been incorporated into the local branch. @@ -531,5 +531,3 @@ started. - The version control system does not allow people to overwrite each other's changes blindly, but highlights conflicts so that they can be resolved. :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/14-supplemental-rstudio.md b/episodes/14-supplemental-rstudio.md index c1f5d72ab9..24ced1988c 100644 --- a/episodes/14-supplemental-rstudio.md +++ b/episodes/14-supplemental-rstudio.md @@ -82,7 +82,7 @@ to accept the Xcode license if you are using macOS. Next, RStudio will ask which existing directory we want to use. Click "Browse..." and navigate to the correct directory, then click "Create Project": -![](fig/RStudio_screenshot_navigateexisting.png) +![](fig/RStudio_screenshot_navigateexisting.png){alt='RStudio window showing the "Create Project From Existing Directory" dialog. In the dialog, the project working directory has been set to "~/Desktop/planets"'} Ta-da! We have created a new project in RStudio within the existing planets repository. Notice the vertical "Git" menu in the menu bar. RStudio has @@ -95,12 +95,12 @@ To edit the existing files in the repository, we can click on them in the "Files" panel on the lower right. Now let's add some additional information about Pluto: -![](fig/RStudio_screenshot_editfiles.png) +![](fig/RStudio_screenshot_editfiles.png){alt='RStudio window demonstrating the use of the editor panel to modify the "pluto.txt" file'} Once we have saved our edited files, we can use RStudio to commit the changes by clicking on "Commit..." in the Git menu: -![](fig/RStudio_screenshot_commit.png){alt='RStudio screenshot showing the Git menu dropdown with "Commit..." selected'} +![](fig/RStudio_screenshot_commit.png){alt='RStudio screenshot showing the Git menu dropdown with the "Commit..." option selected'} This will open a dialogue where we can select which files to commit (by checking the appropriate boxes in the "Staged" column), and enter a commit @@ -109,13 +109,13 @@ the current status of each file. Clicking on a file shows information about changes in the lower panel (using output of `git diff`). Once everything is the way we want it, we click "Commit": -![](fig/RStudio_screenshot_review.png) +![](fig/RStudio_screenshot_review.png){alt='RStudio screenshow showing the "Review Changes" dialog. The top left panel shows the list of files that can be included or excluded from the commit. The top right panel is for writing a commit message. The bottom panel shows information about the currently selected file in the top left panel.'} The changes can be pushed by selecting "Push Branch" from the Git menu. There are also options to pull from the remote repository, and to view the commit history: -![](fig/RStudio_screenshot_history.png){alt='RStudio screenshot showing the git menu dropdown with "History" selected'} +![](fig/RStudio_screenshot_history.png){alt='RStudio screenshot showing the git menu dropdown with the "History" option selected'} ::::::::::::::::::::::::::::::::::::::::: callout @@ -131,7 +131,7 @@ terminal to the repository and enter the command: `git push -u origin main`. The If we click on "History", we can see a graphical version of what `git log` would tell us: -![](fig/RStudio_screenshot_viewhistory.png) +![](fig/RStudio_screenshot_viewhistory.png){alt='RStudio screenshot showing the "Review Changes" dialog after pressing the "History" button. The top panel lists the commits in the repository, similar to git log. The bottom panel shows the changes included in the commit that has been selected in the top panel.'} RStudio creates a number of files that it uses to keep track of a project. We often don't want to track these, in which case we add them to our `.gitignore` @@ -188,5 +188,3 @@ enough to get you started! - Using RStudio's Git integration allows you to version control a project over time. :::::::::::::::::::::::::::::::::::::::::::::::::: - -