diff --git a/.nojekyll b/.nojekyll
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/01-basics.html b/01-basics.html
new file mode 100644
index 0000000000..6a3e7493ca
--- /dev/null
+++ b/01-basics.html
@@ -0,0 +1,614 @@
+
+Version Control with Git: Automated Version Control
+ Skip to main content
+
Understand the benefits of an automated version control system.
+
Understand the basics of how automated version control systems
+work.
+
+
+
+
+
+
We’ll start by exploring how version control can be used to keep
+track of what one person did and when. Even if you aren’t collaborating
+with other people, automated version control is much better than this
+situation:
We’ve all been in this situation before: it seems unnecessary to have
+multiple nearly-identical versions of the same document. Some word
+processors let us deal with this a little better, such as Microsoft
+Word’s Track
+Changes, Google Docs’ version
+history, or LibreOffice’s Recording
+and Displaying Changes.
+
Version control systems start with a base version of the document and
+then record changes you make each step of the way. You can 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.
+
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.
+
Unless multiple users make changes to the same section of the
+document - a conflict - you can
+incorporate two sets of changes into the same base document.
+
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 which changes will be made to the next version (each record
+of these changes is called a commit), and keeps useful metadata
+about them. The complete history of commits for a particular project and
+their metadata make up a repository. Repositories can be
+kept in sync across different computers, facilitating collaboration
+among different people.
+
+
+
+
+
+
The Long History of Version Control Systems
+
+
Automated version control systems are nothing new. Tools like RCS, CVS,
+or Subversion
+have been around since the early 1980s and are used by many large
+companies. However, many of these are now considered legacy systems
+(i.e., outdated) due to various limitations in their capabilities. More
+modern systems, such as Git and Mercurial, are
+distributed, meaning that they do not need a centralized server
+to host the repository. These modern systems also include powerful
+merging tools that make it possible for multiple authors to work on the
+same files concurrently.
+
+
+
+
+
+
+
+
+
Paper Writing
+
+
Imagine you drafted an excellent paragraph for a paper you are
+writing, but later ruin it. How would you retrieve the
+excellent version of your conclusion? Is it even
+possible?
+
Imagine you have 5 co-authors. How would you manage the changes
+and comments they make to your paper? If you use LibreOffice Writer or
+Microsoft Word, what happens if you accept changes made using the
+Track Changes option? Do you have a history of those
+changes?
+
+
+
+
+
+
+
+
+
Recovering the excellent version is only possible if you created
+a copy of the old version of the paper. The danger of losing good
+versions often leads to the problematic workflow illustrated in the PhD
+Comics cartoon at the top of this page.
+
Collaborative writing with traditional word processors is
+cumbersome. Either every collaborator has to work on a document
+sequentially (slowing down the process of writing), or you have to send
+out a version to all collaborators and manually merge their comments
+into your document. The ‘track changes’ or ‘record changes’ option can
+highlight changes for you and simplifies merging, but as soon as you
+accept changes you will lose their history. You will then no longer know
+who suggested that change, why it was suggested, or when it was merged
+into the rest of the document. Even online word processors like Google
+Docs or Microsoft Office Online do not fully resolve these
+problems.
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
Version control is like an unlimited ‘undo’.
+
Version control also allows many people to work in parallel.
+
+
diff --git a/02-setup.html b/02-setup.html
new file mode 100644
index 0000000000..03153ebad0
--- /dev/null
+++ b/02-setup.html
@@ -0,0 +1,757 @@
+
+Version Control with Git: Setting Up Git
+ Skip to main content
+
Configure git the first time it is used on a
+computer.
+
Understand the meaning of the --global configuration
+flag.
+
+
+
+
+
+
When we use Git on a new computer for the first time, we need to
+configure a few things. Below are a few examples of configurations we
+will set as we get started with Git:
+
our name and email address,
+
what our preferred text editor is,
+
and that we want to use these settings globally (i.e. for every
+project).
+
On a command line, Git commands are written as
+git verb options, where verb is what we
+actually want to do and options is additional optional
+information which may be needed for the verb. So here is
+how Alfredo sets up his new laptop:
Please use your own name and email address instead of Alfredo’s. This
+user name and email will be associated with your subsequent Git
+activity, which means that any changes pushed to GitHub, BitBucket, GitLab or another Git host server after
+this lesson will include this information.
+
For this lesson, we will be interacting with GitHub and so the email address used
+should be the same as the one used when setting up your GitHub account.
+If you are concerned about privacy, please review GitHub’s
+instructions for keeping your email address private.
+
+
+
+
+
+
Keeping your email private
+
+
If you elect to use a private email address with GitHub, then use
+GitHub’s no-reply email address for the user.email value.
+It looks like ID+username@users.noreply.github.com. You can
+look up your own address in your GitHub email settings.
+
+
+
+
+
+
+
+
+
Line Endings
+
+
As with other keys, when you hit Enter or ↵ or
+on Macs, Return on your keyboard, your computer encodes this
+input as a character. Different operating systems use different
+character(s) to represent the end of a line. (You may also hear these
+referred to as newlines or line breaks.) Because Git uses these
+characters to compare files, it may cause unexpected issues when editing
+a file on different machines. Though it is beyond the scope of this
+lesson, you can read more about this issue in
+the Pro Git book.
+
You can change the way Git recognizes and encodes line endings using
+the core.autocrlf command to git config. The
+following settings are recommended:
+
On macOS and Linux:
+
+
BASH
+
+
$ git config --global core.autocrlf input
+
+
And on Windows:
+
+
BASH
+
+
$ git config --global core.autocrlf true
+
+
+
+
+
Alfredo also has to set his favorite text editor, following this
+table:
It is possible to reconfigure the text editor for Git whenever you
+want to change it.
+
+
+
+
+
+
Exiting Vim
+
+
Note that Vim is the default editor for many programs. If you haven’t
+used Vim before and wish to exit a session without saving your changes,
+press Esc then type :q! and hit Enter
+or ↵ or on Macs, Return. If you want to save your
+changes and quit, press Esc then type :wq and
+hit Enter or ↵ or on Macs, Return.
+
+
+
+
Git (2.28+) allows configuration of the name of the branch created
+when you initialize any new repository. Alfredo decides to use that
+feature to set it to main so it matches the cloud service
+he will eventually use.
+
+
BASH
+
+
$ git config --global init.defaultBranch main
+
+
+
+
+
+
+
Default Git branch naming
+
+
Source file changes are associated with a “branch.” For new learners
+in this lesson, it’s enough to know that branches exist, and this lesson
+uses one branch.
+By default, Git will create a branch called master when you
+create a new repository with git init (as explained in the
+next Episode). This term evokes the racist practice of human slavery and
+the software development
+community has moved to adopt more inclusive language.
+
In 2020, most Git code hosting services transitioned to using
+main as the default branch. As an example, any new
+repository that is opened in GitHub and GitLab default to
+main. However, Git has not yet made the same change. As a
+result, local repositories must be manually configured have the same
+main branch name as most cloud services.
+
For versions of Git prior to 2.28, the change can be made on an
+individual repository level. The command for this is in the next
+episode. Note that if this value is unset in your local Git
+configuration, the init.defaultBranch value defaults to
+master.
+
+
+
+
The five commands we just ran above only need to be run once: the
+flag --global tells Git to use the settings for every
+project, in your user account, on this computer.
+
Let’s review those settings and test our core.editor
+right away:
+
+
BASH
+
+
$ git config --global--edit
+
+
Let’s close the file without making any additional changes. Remember,
+since typos in the config file will cause issues, it’s safer to view the
+configuration with:
+
+
BASH
+
+
$ git config --list
+
+
And if necessary, change your configuration using the same commands
+to choose another editor or update your email address. This can be done
+as many times as you want.
+
+
+
+
+
+
Proxy
+
+
In some networks you need to use a proxy. If this is
+the case, you may also need to tell Git about the proxy:
Always remember that if you forget the subcommands or options of a
+git command, you can access the relevant list of options
+typing git <command> -h or access the corresponding
+Git manual by typing git <command> --help, e.g.:
+
+
BASH
+
+
$ git config -h
+$ git config --help
+
+
While viewing the manual, remember the : is a prompt
+waiting for commands and you can press Q to exit the
+manual.
+
More generally, you can get the list of available git
+commands and further resources of the Git manual typing:
+
+
BASH
+
+
$ git help
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
Use git config with the --global option to
+configure a user name, email address, editor, and other preferences once
+per machine.
+
+
diff --git a/03-create.html b/03-create.html
new file mode 100644
index 0000000000..51c3e482af
--- /dev/null
+++ b/03-create.html
@@ -0,0 +1,710 @@
+
+Version Control with Git: Creating a Repository
+ Skip to main content
+
We will help Alfredo with his new project, create a repository with
+all his recipes.
+
First, let’s create a new directory in the Desktop
+folder for our work and then change the current working directory to the
+newly created one:
+
+
BASH
+
+
$ cd ~/Desktop
+$ mkdir recipes
+$ cd recipes
+
+
Then we tell Git to make recipes a repository -- a place where Git can
+store versions of our files:
+
+
BASH
+
+
$ git init
+
+
It is important to note that git init will create a
+repository that can include subdirectories and their files—there is no
+need to create separate repositories nested within the
+recipes repository, whether subdirectories are present from
+the beginning or added later. Also, note that the creation of the
+recipes directory and its initialization as a repository
+are completely separate processes.
+
If we use ls to show the directory’s contents, it
+appears that nothing has changed:
+
+
BASH
+
+
$ ls
+
+
But if we add the -a flag to show everything, we can see
+that Git has created a hidden directory within recipes
+called .git:
+
+
BASH
+
+
$ ls -a
+
+
+
OUTPUT
+
+
. .. .git
+
+
Git uses this special subdirectory to store all the information about
+the project, including the tracked files and sub-directories located
+within the project’s directory. If we ever delete the .git
+subdirectory, we will lose the project’s history.
+
We can now start using one of the most important git commands, which
+is particularly helpful to beginners. git status tells us
+the status of our project, and better, a list of changes in the project
+and options on what to do with those changes. We can use it as often as
+we want, whenever we want to understand what is going on.
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+
+No commits yet
+
+nothing to commit (create/copy files and use "git add" to track)
+
+
If you are using a different version of git, the exact
+wording of the output might be slightly different.
+
+
+
+
+
+
Places to Create Git Repositories
+
+
Along with tracking information about recipes (the project we have
+already created), Alfredo would also like to track information about
+desserts specifically. Alfredo creates a desserts project
+inside his recipes project with the following sequence of
+commands:
+
+
BASH
+
+
$ cd ~/Desktop # return to Desktop directory
+$ cd recipes # go into recipes directory, which is already a Git repository
+$ ls -a# ensure the .git subdirectory is still present in the recipes directory
+$ mkdir desserts # make a sub-directory recipes/desserts
+$ cd desserts # go into desserts subdirectory
+$ git init # make the desserts subdirectory a Git repository
+$ ls -a# ensure the .git subdirectory is present indicating we have created a new Git repository
+
+
Is the git init command, run inside the
+desserts subdirectory, required for tracking files stored
+in the desserts subdirectory?
+
+
+
+
+
+
+
+
+
No. Alfredo does not need to make the desserts
+subdirectory a Git repository because the recipes
+repository will track all files, sub-directories, and subdirectory files
+under the recipes directory. Thus, in order to track all
+information about desserts, Alfredo only needed to add the
+desserts subdirectory to the recipes
+directory.
+
Additionally, Git repositories can interfere with each other if they
+are “nested”: the outer repository will try to version-control the inner
+repository. Therefore, it’s best to create each new Git repository in a
+separate directory. To be sure that there is no conflicting repository
+in the directory, check the output of git status. If it
+looks like the following, you are good to go to create a new repository
+as shown above:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
fatal: Not a git repository (or any of the parent directories): .git
+
+
+
+
+
+
+
+
+
+
+
Correcting git init Mistakes
+
+
Jimmy explains to Alfredo how a nested repository is redundant and
+may cause confusion down the road. Alfredo would like to go back to a
+single git repository. How can Alfredo undo his last
+git init in the desserts subdirectory?
+
+
+
+
+
+
+
+
+
+
Background
+
Removing files from a Git repository needs to be done with caution.
+But we have not learned yet how to tell Git to track a particular file;
+we will learn this in the next episode. Files that are not tracked by
+Git can easily be removed like any other “ordinary” files with
+
+
BASH
+
+
$ rm filename
+
+
Similarly a directory can be removed using
+rm -r dirname. If the files or folder being removed in this
+fashion are tracked by Git, then their removal becomes another change
+that we will need to track, as we will see in the next episode.
+
+
+
Solution
+
Git keeps all of its files in the .git directory. To
+recover from this little mistake, Alfredo can remove the
+.git folder in the desserts subdirectory by running the
+following command from inside the recipes directory:
+
+
BASH
+
+
$ rm -rf desserts/.git
+
+
But be careful! Running this command in the wrong directory will
+remove the entire Git history of a project you might want to keep. In
+general, deleting files and directories using rm from the
+command line cannot be reversed. Therefore, always check your current
+directory using the command pwd.
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
+git init initializes a repository.
+
Git stores all of its repository data in the .git
+directory.
How do I check the status of my version control repository?
+
How do I record notes about what changes I made and why?
+
+
+
+
+
+
+
Objectives
+
Go through the modify-add-commit cycle for one or more files.
+
Explain where information is stored at each stage of that
+cycle.
+
Distinguish between descriptive and non-descriptive commit
+messages.
+
+
+
+
+
+
First let’s make sure we’re still in the right directory. You should
+be in the recipes directory.
+
+
BASH
+
+
$ cd ~/Desktop/recipes
+
+
Let’s create a file called guacamole.md that contains
+the basic structure to have a recipe. We’ll use nano to
+edit the file; you can use whatever editor you like. In particular, this
+does not have to be the core.editor you set globally
+earlier. But remember, the steps to create create or edit a new file
+will depend on the editor you choose (it might not be nano). For a
+refresher on text editors, check out “Which
+Editor?” in The Unix Shell
+lesson.
+
+
BASH
+
+
$ nano guacamole.md
+
+
Type the text below into the guacamole.md file:
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+## Instructions
+
+
Save the file and exit your editor. Next, let’s verify that the file
+was properly created by running the list command (ls):
+
+
BASH
+
+
$ ls
+
+
+
OUTPUT
+
+
guacamole.md
+
+
guacamole.md contains three lines, which we can see by
+running:
+
+
BASH
+
+
$ cat guacamole.md
+
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+## Instructions
+
+
If we check the status of our project again, Git tells us that it’s
+noticed the new file:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+
+No commits yet
+
+Untracked files:
+ (use "git add <file>..." to include in what will be committed)
+
+ guacamole.md
+
+nothing added to commit but untracked files present (use "git add" to track)
+
+
The “untracked files” message means that there’s a file in the
+directory that Git isn’t keeping track of. We can tell Git to track a
+file using git add:
+
+
BASH
+
+
$ git add guacamole.md
+
+
and then check that the right thing happened:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+
+No commits yet
+
+Changes to be committed:
+ (use "git rm --cached <file>..." to unstage)
+
+ new file: guacamole.md
+
+
+
Git now knows that it’s supposed to keep track of
+guacamole.md, but it hasn’t recorded these changes as a
+commit yet. To get it to do that, we need to run one more command:
+
+
BASH
+
+
$ git commit -m"Create a template for recipe"
+
+
+
OUTPUT
+
+
[main (root-commit) f22b25e] Create a template for recipe
+ 1 file changed, 1 insertion(+)
+ create mode 100644 guacamole.md
+
+
When we run git commit, Git takes everything we have
+told it to save by using git add and stores a copy
+permanently inside the special .git directory. This
+permanent copy is called a commit
+(or revision) and its short
+identifier is f22b25e. Your commit may have another
+identifier.
+
We use the -m flag (for “message”) to record a short,
+descriptive, and specific comment that will help us remember later on
+what we did and why. If we just run git commit without the
+-m option, Git will launch nano (or whatever
+other editor we configured as core.editor) so that we can
+write a longer message.
+
Good commit
+messages start with a brief (<50 characters) statement about the
+changes made in the commit. Generally, the message should complete the
+sentence “If applied, this commit will” . If you
+want to go into more detail, add a blank line between the summary line
+and your additional notes. Use this additional space to explain why you
+made changes and/or what their impact will be.
+
If we run git status now:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+nothing to commit, working tree clean
+
+
it tells us everything is up to date. If we want to know what we’ve
+done recently, we can ask Git to show us the project’s history using
+git log:
+
+
BASH
+
+
$ git log
+
+
+
OUTPUT
+
+
commit f22b25e3233b4645dabd0d81e651fe074bd8e73b
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 09:51:46 2013 -0400
+
+ Create a template for recipe
+
+
git log lists all commits made to a repository in
+reverse chronological order. The listing for each commit includes the
+commit’s full identifier (which starts with the same characters as the
+short identifier printed by the git commit command
+earlier), the commit’s author, when it was created, and the log message
+Git was given when the commit was created.
+
+
+
+
+
+
Where Are My Changes?
+
+
If we run ls at this point, we will still see just one
+file called guacamole.md. That’s because Git saves
+information about files’ history in the special .git
+directory mentioned earlier so that our filesystem doesn’t become
+cluttered (and so that we can’t accidentally edit or delete an old
+version).
+
+
+
+
Now suppose Alfredo adds more information to the file. (Again, we’ll
+edit with nano and then cat the file to show
+its contents; you may use a different editor, and don’t need to
+cat.)
When we run git status now, it tells us that a file it
+already knows about has been modified:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
The last line is the key phrase: “no changes added to commit”. We
+have changed this file, but we haven’t told Git we will want to save
+those changes (which we do with git add) nor have we saved
+them (which we do with git commit). So let’s do that now.
+It is good practice to always review our changes before saving them. We
+do this using git diff. This shows us the differences
+between the current state of the file and the most recently saved
+version:
The output is cryptic because it is actually a series of commands for
+tools like editors and patch telling them how to
+reconstruct one file given the other. If we break it down into
+pieces:
+
The first line tells us that Git is producing output similar to the
+Unix diff command comparing the old and new versions of the
+file.
+
The second line tells exactly which versions of the file Git is
+comparing; df0654a and 315bf3a are unique
+computer-generated labels for those versions.
+
The third and fourth lines once again show the name of the file
+being changed.
+
The remaining lines are the most interesting, they show us the
+actual differences and the lines on which they occur. In particular, the
++ marker in the first column shows where we added a
+line.
+
After reviewing our change, it’s time to commit it:
+
+
BASH
+
+
$ git commit -m"Add basic guacamole's ingredients"
+$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
Whoops: Git won’t commit because we didn’t use git add
+first. Let’s fix that:
Git insists that we add files to the set we want to commit before
+actually committing anything. This allows us to commit our changes in
+stages and capture changes in logical portions rather than only large
+batches. For example, suppose we’re adding a few citations to relevant
+research to our thesis. We might want to commit those additions, and the
+corresponding bibliography entries, but not commit some of our
+work drafting the conclusion (which we haven’t finished yet).
+
To allow for this, Git has a special staging area where it
+keeps track of things that have been added to the current changeset but not yet committed.
+
+
+
+
+
+
Staging Area
+
+
If you think of Git as taking snapshots of changes over the life of a
+project, git add specifies what will go in a
+snapshot (putting things in the staging area), and
+git commit then actually takes the snapshot, and
+makes a permanent record of it (as a commit). If you don’t have anything
+staged when you type git commit, Git will prompt you to use
+git commit -a or git commit --all, which is
+kind of like gathering everyone to take a group photo! However,
+it’s almost always better to explicitly add things to the staging area,
+because you might commit changes you forgot you made. (Going back to the
+group photo simile, you might get an extra with incomplete makeup
+walking on the stage for the picture because you used -a!)
+Try to stage things manually, or you might find yourself searching for
+“git undo commit” more than you would like!
+
+
+
+
Let’s watch as our changes to a file move from our editor to the
+staging area and into long-term storage. First, we’ll improve our recipe
+by changing ‘lemon’ to ‘lime’:
So far, so good: we’ve replaced one line (shown with a -
+in the first column) with a new line (shown with a + in the
+first column). Now let’s put that change in the staging area and see
+what git diff reports:
+
+
BASH
+
+
$ git add guacamole.md
+$ git diff
+
+
There is no output: as far as Git can tell, there’s no difference
+between what it’s been asked to save permanently and what’s currently in
+the directory. However, if we do this:
it shows us the difference between the last committed change and
+what’s in the staging area. Let’s save our changes:
+
+
BASH
+
+
$ git commit -m"Modify guacamole to the traditional recipe"
+
+
+
OUTPUT
+
+
[main 005937f] Modify guacamole to the traditional recipe
+ 1 file changed, 1 insertion(+)
+
+
check our status:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+nothing to commit, working tree clean
+
+
and look at the history of what we’ve done so far:
+
+
BASH
+
+
$ git log
+
+
+
OUTPUT
+
+
commit 005937fbe2a98fb83f0ade869025dc2636b4dad5 (HEAD -> main)
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 10:14:07 2013 -0400
+
+ Modify guacamole to the traditional recipe
+
+commit 34961b159c27df3b475cfe4415d94a6d1fcd064d
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 10:07:21 2013 -0400
+
+ Add basic guacamole's ingredients
+
+commit f22b25e3233b4645dabd0d81e651fe074bd8e73b
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 09:51:46 2013 -0400
+
+ Create a template for recipe
+
+
+
+
+
+
+
Word-based diffing
+
+
Sometimes, e.g. in the case of the text documents a line-wise diff is
+too coarse. That is where the --color-words option of
+git diff comes in very useful as it highlights the changed
+words using colors.
+
+
+
+
+
+
+
+
+
Paging the Log
+
+
When the output of git log is too long to fit in your
+screen, git uses a program to split it into pages of the
+size of your screen. When this “pager” is called, you will notice that
+the last line in your screen is a :, instead of your usual
+prompt.
+
To get out of the pager, press Q.
+
To move to the next page, press Spacebar.
+
To search for some_word in all pages, press
+/ and type some_word. Navigate through matches
+pressing N.
+
+
+
+
+
+
+
+
+
Limit Log Size
+
+
To avoid having git log cover your entire terminal
+screen, you can limit the number of commits that Git lists by using
+-N, where N is the number of commits that you
+want to view. For example, if you only want information from the last
+commit you can use:
+
+
BASH
+
+
$ git log -1
+
+
+
OUTPUT
+
+
commit 005937fbe2a98fb83f0ade869025dc2636b4dad5 (HEAD -> main)
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 10:14:07 2013 -0400
+
+ Modify guacamole to the traditional recipe
+
+
You can also reduce the quantity of information using the
+--oneline option:
+
+
BASH
+
+
$ git log --oneline
+
+
+
OUTPUT
+
+
005937f (HEAD -> main) Modify guacamole to the traditional recipe
+34961b1 Add basic guacamole's ingredients
+f22b25e Create a template for recipe
+
+
You can also combine the --oneline option with others.
+One useful combination adds --graph to display the commit
+history as a text-based graph and to indicate which commits are
+associated with the current HEAD, the current branch
+main, or other
+Git references:
+
+
BASH
+
+
$ git log --oneline--graph
+
+
+
OUTPUT
+
+
* 005937f (HEAD -> main) Modify guacamole to the traditional recipe
+* 34961b1 Add basic guacamole's ingredients
+* f22b25e Create a template for recipe
+
+
+
+
+
+
+
+
+
+
Directories
+
+
Two important facts you should know about directories in Git.
+
Git does not track directories on their own, only files within them.
+Try it for yourself:
+
+
BASH
+
+
$ mkdir cakes
+$ git status
+$ git add cakes
+$ git status
+
+
Note, our newly created empty directory cakes does not
+appear in the list of untracked files even if we explicitly add it
+(viagit add) to our repository. This is the
+reason why you will sometimes see .gitkeep files in
+otherwise empty directories. Unlike .gitignore, these files
+are not special and their sole purpose is to populate a directory so
+that Git adds it to the repository. In fact, you can name such files
+anything you like.
+
If you create a directory in your Git repository and populate it
+with files, you can add all files in the directory at once by:
+
+
BASH
+
+
git add <directory-with-files>
+
+
Try it for yourself:
+
+
BASH
+
+
$ touch cakes/brownie cakes/lemon_drizzle
+$ git status
+$ git add cakes
+$ git status
+
+
Before moving on, we will commit these changes.
+
+
BASH
+
+
$ git commit -m"Add some initial cakes"
+
+
+
+
+
To recap, when we want to add changes to our repository, 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):
+
+
+
+
+
+
Choosing a Commit Message
+
+
Which of the following commit messages would be most appropriate for
+the last commit made to guacamole.md?
+
“Changes”
+
“Changed lemon for lime”
+
“Guacamole modified to the traditional recipe”
+
+
+
+
+
+
+
+
+
Answer 1 is not descriptive enough, and the purpose of the commit is
+unclear; and answer 2 is redundant to using “git diff” to see what
+changed in this commit; but answer 3 is good: short, descriptive, and
+imperative.
+
+
+
+
+
+
+
+
+
+
Committing Changes to Git
+
+
Which command(s) below would save the changes of
+myfile.txt to my local Git repository?
Modify the file as described (modify one line, add a fourth line). To
+display the differences between its updated state and its original
+state, use git diff:
+
+
BASH
+
+
$ git diff me.txt
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
+git status shows the status of a repository.
+
Files can be stored in a project’s working directory (which users
+see), the staging area (where the next commit is being built up) and the
+local repository (where commits are permanently recorded).
+
+git add puts files in the staging area.
+
+git commit saves the staged content as a new commit in
+the local repository.
+
Write a commit message that accurately describes your changes.
+
+
diff --git a/05-history.html b/05-history.html
new file mode 100644
index 0000000000..aebcfd2d08
--- /dev/null
+++ b/05-history.html
@@ -0,0 +1,1103 @@
+
+Version Control with Git: Exploring History
+ Skip to main content
+
Explain what the HEAD of a repository is and how to use it.
+
Identify and use Git commit numbers.
+
Compare various versions of tracked files.
+
Restore old versions of files.
+
+
+
+
+
+
As we saw in the previous episode, we can refer to commits by their
+identifiers. You can refer to the most recent commit of the
+working directory by using the identifier HEAD.
+
We’ve been adding small changes at a time to
+guacamole.md, so it’s easy to track our progress by
+looking, so let’s do that using our HEADs. Before we start,
+let’s make a change to guacamole.md, adding yet another
+line.
which is the same as what you would get if you leave out
+HEAD (try it). The real goodness in all this is when you
+can refer to previous commits. We do that by adding ~1
+(where “~” is “tilde”, pronounced [til-duh])
+to refer to the commit one before HEAD.
+
+
BASH
+
+
$ git diff HEAD~1 guacamole.md
+
+
If we want to see the differences between older commits we can use
+git diff again, but with the notation HEAD~1,
+HEAD~2, and so on, to refer to them:
We could also use git show which shows us what changes
+we made at an older commit as well as the commit message, rather than
+the differences between a commit and our working directory that
+we see by using git diff.
In this way, we can build up a chain of commits. The most recent end
+of the chain is referred to as HEAD; we can refer to
+previous commits using the ~ notation, so
+HEAD~1 means “the previous commit”, while
+HEAD~123 goes back 123 commits from where we are now.
+
We can also refer to commits using those long strings of digits and
+letters that both git log and git show
+display. These are unique IDs for the changes, and “unique” really does
+mean unique: every change to any set of files on any computer has a
+unique 40-character identifier. Our first commit was given the ID
+f22b25e3233b4645dabd0d81e651fe074bd8e73b, so let’s try
+this:
That’s the right answer, but typing out random 40-character strings
+is annoying, so Git lets us use just the first few characters (typically
+seven for normal size projects):
All right! So we can save changes to files and see what we’ve
+changed. Now, how can we restore older versions of things? Let’s suppose
+we change our mind about the last update to guacamole.md
+(the “ill-considered change”).
+
git status now tells us that the file has been changed,
+but those changes haven’t been staged:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
We can put things back the way they were by using
+git restore:
As you might guess from its name, git restore restores
+an old version of a file. By default, it recovers the version of the
+file recorded in HEAD, which is the last saved commit. If
+we want to go back even further, we can use a commit identifier instead,
+using -s option:
+
+
BASH
+
+
$ git restore -s f22b25e guacamole.md
+
+
+
BASH
+
+
$ cat guacamole.md
+
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+## Instructions
+
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
+
Notice that the changes are not currently in the staging area, and
+have not been committed. If we wished, we can put things back the way
+they were at the last commit by using git restore to
+overwrite the working copy with the last committed version:
It’s important to remember that we must use the commit number that
+identifies the state of the repository before the change we’re
+trying to undo. A common mistake is to use the number of 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. We use the
+. to mean all files:
+
So, to put it all together, here’s how Git works in cartoon form:
The fact that files can be reverted one by one tends to change the
+way people organize their work. If everything is in one large document,
+it’s hard (but not impossible) to undo changes to the introduction
+without also undoing changes made later to the conclusion. If the
+introduction and conclusion are stored in separate files, on the other
+hand, moving backward and forward in time becomes much easier.
+
+
+
+
+
+
Recovering Older Versions of a File
+
+
Jennifer has made changes to the Python script that she has been
+working on for weeks, and the modifications she made this morning
+“broke” the script and it no longer runs. She has spent ~ 1hr trying to
+fix it, with no luck…
+
Luckily, she has been keeping track of her project’s versions using
+Git! Which commands below will let her recover the last committed
+version of her Python script called data_cruncher.py?
+
$ git restore
+
$ git restore data_cruncher.py
+
$ git restore -s HEAD~1 data_cruncher.py
+
$ git restore -s <unique ID of last commit> data_cruncher.py
+
Both 2 and 4
+
+
+
+
+
+
+
+
+
The answer is (5)-Both 2 and 4.
+
The restore command restores files from the repository,
+overwriting the files in your working directory. Answers 2 and 4 both
+restore the latest version in the repository of the
+file data_cruncher.py. Answer 2 uses HEAD to
+indicate the latest, whereas answer 4 uses the unique ID of the
+last commit, which is what HEAD means.
+
Answer 3 gets the version of data_cruncher.py from the
+commit beforeHEAD, which is NOT what we
+wanted.
+
Answer 1 results in an error. You need to specify a file to restore.
+If you want to restore all files you should use
+git restore .
+
+
+
+
+
+
+
+
+
+
Reverting a Commit
+
+
Jennifer is collaborating with colleagues on her Python script. She
+realizes her last commit to the project’s repository contained an error,
+and wants to undo it. Jennifer wants to undo correctly so everyone in
+the project’s repository gets the correct change. The command
+git revert [erroneous commit ID] will create a new commit
+that reverses the erroneous commit.
+
The command git revert is different from
+git restore -s [commit ID] . because
+git restore returns the files not yet committed within the
+local repository to a previous state, whereas git revert
+reverses changes committed to the local and project repositories.
+
Below are the right steps and explanations for Jennifer to use
+git revert, what is the missing command?
+
________ # Look at the git history of the project to find the commit ID
+
Copy the ID (the first few characters of the ID,
+e.g. 0b1d055).
+
git revert [commit ID]
+
Type in the new commit message.
+
Save and close.
+
+
+
+
+
+
+
+
+
The command git log lists project history with commit
+IDs.
+
The command git show HEAD shows changes made at the
+latest commit, and lists the commit ID; however, Jennifer should
+double-check it is the correct commit, and no one else has committed
+changes to the repository.
+
+
+
+
+
+
+
+
+
+
Understanding Workflow and History
+
+
What is the output of the last command in
+
+
BASH
+
+
$ cd recipes
+$ echo "I like tomatoes, therefore I like ketchup"> ketchup.md
+$ git add ketchup.md
+$ echo "ketchup enhances pasta dishes">> ketchup.md
+$ git commit -m"My opinions about the red sauce"
+$ git restore ketchup.md
+$ cat ketchup.md # this will print the content of ketchup.md on screen
+
+
+
OUTPUT
+
+
ketchup enhances pasta dishes
+
+
+
OUTPUT
+
+
I like tomatoes, therefore I like ketchup
+
+
+
OUTPUT
+
+
I like tomatoes, therefore I like ketchup
+ ketchup enhances pasta dishes
+
+
+
OUTPUT
+
+
Error because you have changed ketchup.md without committing the changes
+
+
+
+
+
+
+
+
+
+
The answer is 2.
+
The changes to the file from the second echo command are
+only applied to the working copy, The command
+git add ketchup.md places the current version of
+ketchup.md into the staging area. not the version in the
+staging area.
+
So, when git commit -m "My opinions about the red sauce"
+is executed, the version of ketchup.md committed to the
+repository is the one from the staging area and has only one line.
+
At this time, the working copy still has the second line (and
+
git status will show that the file is modified).
+However, git restore ketchup.md replaces the working copy
+with the most recently committed version of ketchup.md. So,
+cat ketchup.md will output
+
+
OUTPUT
+
+
I like tomatoes, therefore I like ketchup
+
+
+
+
+
+
+
+
+
+
+
Checking Understanding of
+git diff
+
+
+
Consider this command: git diff HEAD~9 guacamole.md.
+What do you predict this command will do if you execute it? What happens
+when you do execute it? Why?
+
Try another command, git diff [ID] guacamole.md, where
+[ID] is replaced with the unique identifier for your most recent commit.
+What do you think will happen, and what does happen?
+
+
+
+
+
+
+
+
+
Getting Rid of Staged Changes
+
+
git restore can be used to restore a previous commit
+when unstaged changes have been made, but will it also work for changes
+that have been staged but not committed? Make a change to
+guacamole.md, add that change using git add,
+then use git restore to see if you can remove your
+change.
+
+
+
+
+
+
+
+
+
After adding a change, git restore can not be used
+directly. Let’s look at the output of git status:
+
+
OUTPUT
+
+
On branch main
+Changes to be committed:
+ (use "git restore --staged <file>..." to unstage)
+ modified: guacamole.md
+
+
+
Note that if you don’t have the same output you may either have
+forgotten to change the file, or you have added it and
+committed it.
+
Using the command git restore guacamole.md now does not
+give an error, but it does not restore the file either. Git helpfully
+tells us that we need to use git restore --staged first to
+unstage the file:
+
+
BASH
+
+
$ git restore --staged guacamole.md
+
+
Now, git status gives us:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git git restore <file>..." to discard changes in working directory)
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
This means we can now use git restore to restore the
+file to the previous commit:
+
+
BASH
+
+
$ git restore guacamole.md
+$ git status
+
+
+
OUTPUT
+
+
On branch main
+nothing to commit, working tree clean
+
+
+
+
+
+
+
+
+
+
+
Explore and Summarize Histories
+
+
Exploring history is an important part of Git, and often it is a
+challenge to find the right commit ID, especially if the commit is from
+several months ago.
+
Imagine the recipes project has more than 50 files. You
+would like to find a commit that modifies some specific text in
+guacamole.md. When you type git log, a very
+long list appeared. How can you narrow down the search?
+
Recall that the git diff command allows us to explore
+one specific file, e.g., git diff guacamole.md. We can
+apply a similar idea here.
+
+
BASH
+
+
$ git log guacamole.md
+
+
Unfortunately some of these commit messages are very ambiguous, e.g.,
+update files. How can you search through these files?
+
Both git diff and git log are very useful
+and they summarize a different part of the history for you. Is it
+possible to combine both? Let’s try the following:
+
+
BASH
+
+
$ git log --patch guacamole.md
+
+
You should get a long list of output, and you should be able to see
+both commit messages and the difference between each commit.
+
+
diff --git a/06-ignore.html b/06-ignore.html
new file mode 100644
index 0000000000..ab2908bade
--- /dev/null
+++ b/06-ignore.html
@@ -0,0 +1,924 @@
+
+Version Control with Git: Ignoring Things
+ Skip to main content
+
How can I tell Git to ignore files I don’t want to track?
+
+
+
+
+
+
+
Objectives
+
Configure Git to ignore specific files.
+
Explain why ignoring files can be useful.
+
+
+
+
+
+
What if we have files that we do not want Git to track for us, like
+backup files created by our editor or intermediate files created during
+data analysis? Let’s create a few dummy files:
On branch main
+Untracked files:
+ (use "git add <file>..." to include in what will be committed)
+
+ a.png
+ b.png
+ c.png
+ receipts/
+
+nothing added to commit but untracked files present (use "git add" to track)
+
+
Putting these files under version control would be a waste of disk
+space. What’s worse, having them all listed could distract us from
+changes that actually matter, so let’s tell Git to ignore them.
+
We do this by creating a file in the root directory of our project
+called .gitignore:
+
+
BASH
+
+
$ nano .gitignore
+$ cat .gitignore
+
+
+
OUTPUT
+
+
*.png
+receipts/
+
+
These patterns tell Git to ignore any file whose name ends in
+.png and everything in the receipts directory.
+(If any of these files were already being tracked, Git would continue to
+track them.)
+
Once we have created this file, the output of git status
+is much cleaner:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Untracked files:
+ (use "git add <file>..." to include in what will be committed)
+
+ .gitignore
+
+nothing added to commit but untracked files present (use "git add" to track)
+
+
The only thing Git notices now is the newly-created
+.gitignore file. You might think we wouldn’t want to track
+it, but everyone we’re sharing our repository with will probably want to
+ignore the same things that we’re ignoring. Let’s add and commit
+.gitignore:
+
+
BASH
+
+
$ git add .gitignore
+$ git commit -m"Ignore png files and the receipts folder."
+$ git status
+
+
+
OUTPUT
+
+
On branch main
+nothing to commit, working tree clean
+
+
As a bonus, using .gitignore helps us avoid accidentally
+adding files to the repository that we don’t want to track:
+
+
BASH
+
+
$ git add a.png
+
+
+
OUTPUT
+
+
The following paths are ignored by one of your .gitignore files:
+a.png
+Use -f if you really want to add them.
+
+
If we really want to override our ignore settings, we can use
+git add -f to force Git to add something. For example,
+git add -f a.csv. We can also always see the status of
+ignored files if we want:
+
+
BASH
+
+
$ git status --ignored
+
+
+
OUTPUT
+
+
On branch main
+Ignored files:
+ (use "git add -f <file>..." to include in what will be committed)
+
+ a.png
+ b.png
+ c.png
+ receipts/
+
+nothing to commit, working tree clean
+
+
+
+
+
+
+
Ignoring Nested Files
+
+
Given a directory structure that looks like:
+
+
BASH
+
+
receipts/data
+receipts/plots
+
+
How would you ignore only receipts/plots and not
+receipts/data?
+
+
+
+
+
+
+
+
+
If you only want to ignore the contents of
+receipts/plots, you can change your .gitignore
+to ignore only the /plots/ subfolder by adding the
+following line to your .gitignore:
+
+
OUTPUT
+
+
receipts/plots/
+
+
This line will ensure only the contents of
+receipts/plots is ignored, and not the contents of
+receipts/data.
+
As with most programming issues, there are a few alternative ways
+that one may ensure this ignore rule is followed. The “Ignoring Nested
+Files: Variation” exercise has a slightly different directory structure
+that presents an alternative solution. Further, the discussion page has
+more detail on ignore rules.
+
+
+
+
+
+
+
+
+
+
Including Specific Files
+
+
How would you ignore all .png files in your root
+directory except for final.png? Hint: Find out what
+! (the exclamation point operator) does
+
+
+
+
+
+
+
+
+
You would add the following two lines to your .gitignore:
+
+
OUTPUT
+
+
*.png # ignore all png files
+!final.png # except final.png
+
+
The exclamation point operator will include a previously excluded
+entry.
+
Note also that because you’ve previously committed .png
+files in this lesson they will not be ignored with this new rule. Only
+future additions of .png files added to the root directory
+will be ignored.
+
+
+
+
+
+
+
+
+
+
Ignoring Nested Files: Variation
+
+
Given a directory structure that looks similar to the earlier Nested
+Files exercise, but with a slightly different directory structure:
How would you ignore all of the contents in the receipts folder, but
+not receipts/data?
+
Hint: think a bit about how you created an exception with the
+! operator before.
+
+
+
+
+
+
+
+
+
If you want to ignore the contents of receipts/ but not
+those of receipts/data/, you can change your
+.gitignore to ignore the contents of receipts folder, but
+create an exception for the contents of the receipts/data
+subfolder. Your .gitignore would look like this:
+
+
OUTPUT
+
+
receipts/* # ignore everything in receipts folder
+!receipts/data/ # do not ignore receipts/data/ contents
+
+
+
+
+
+
+
+
+
+
+
Ignoring all data Files in a Directory
+
+
Assuming you have an empty .gitignore file, and given a directory
+structure that looks like:
What’s the shortest .gitignore rule you could write to
+ignore all .dat files in
+result/data/market_position/gps? Do not ignore the
+info.txt.
+
+
+
+
+
+
+
+
+
Appending receipts/data/market_position/gps/*.dat will
+match every file in receipts/data/market_position/gps that
+ends with .dat. The file
+receipts/data/market_position/gps/info.txt will not be
+ignored.
+
+
+
+
+
+
+
+
+
+
Ignoring all data Files in the repository
+
+
Let us assume you have many .csv files in different
+subdirectories of your repository. For example, you might have:
How do you ignore all the .csv files, without explicitly
+listing the names of the corresponding folders?
+
+
+
+
+
+
+
+
+
In the .gitignore file, write:
+
+
OUTPUT
+
+
**/*.csv
+
+
This will ignore all the .csv files, regardless of their
+position in the directory tree. You can still include some specific
+exception with the exclamation point operator.
+
+
+
+
+
+
+
+
+
+
The Order of Rules
+
+
Given a .gitignore file with the following contents:
+
+
BASH
+
+
*.csv
+!*.csv
+
+
What will be the result?
+
+
+
+
+
+
+
+
+
The ! modifier will negate an entry from a previously
+defined ignore pattern. Because the !*.csv entry negates
+all of the previous .csv files in the
+.gitignore, none of them will be ignored, and all
+.csv files will be tracked.
+
+
+
+
+
+
+
+
+
+
Log Files
+
+
You wrote a script that creates many intermediate log-files of the
+form log_01, log_02, log_03, etc.
+You want to keep them but you do not want to track them through
+git.
+
Write one.gitignore entry that
+excludes files of the form log_01, log_02,
+etc.
+
Test your “ignore pattern” by creating some dummy files of the
+form log_01, etc.
+
You find that the file log_01 is very important
+after all, add it to the tracked files without changing the
+.gitignore again.
+
Discuss with your neighbor what other types of files could reside
+in your directory that you do not want to track and thus would exclude
+via .gitignore.
+
+
+
+
+
+
+
+
+
append either log_* or log* as a new entry
+in your .gitignore
+
track log_01 using git add -f log_01
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
The .gitignore file tells Git what files to
+ignore.
+
+
diff --git a/07-github.html b/07-github.html
new file mode 100644
index 0000000000..be7999f2f6
--- /dev/null
+++ b/07-github.html
@@ -0,0 +1,1126 @@
+
+Version Control with Git: Remotes in GitHub
+ Skip to main content
+
Explain what remote repositories are and why they are useful.
+
Push to or pull from a remote repository.
+
+
+
+
+
+
Version control really comes into its own when we begin to
+collaborate with other people. We already have most of the machinery we
+need to do this; the only thing missing is to copy changes from one
+repository to another.
+
Systems like Git allow us to move work between any two repositories.
+In practice, though, it’s easiest to use one copy as a central hub, and
+to keep it on the web rather than on someone’s laptop. Most programmers
+use hosting services like GitHub, Bitbucket or GitLab to hold those main copies; we’ll
+explore the pros and cons of this in a later
+episode.
+
Let’s start by sharing the changes we’ve made to our current project
+with the world. To this end we are going to create a remote
+repository that will be linked to our local repository.
+
1. Create a remote repository
+
Log in to GitHub, then click on the
+icon in the top right corner to create a new repository called
+recipes:
+
Name your repository “recipes” and then click “Create
+Repository”.
+
Note: Since this repository will be connected to a local repository,
+it needs to be empty. Leave “Initialize this repository with a README”
+unchecked, and keep “None” as options for both “Add .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.
+
As soon as the repository is created, GitHub displays a page with a
+URL and some information on how to configure your local repository:
+
This effectively does the following on GitHub’s servers:
+
+
BASH
+
+
$ mkdir recipes
+$ cd recipes
+$ git init
+
+
If you remember back to the earlier episode where we added and committed our
+earlier work on guacamole.md, we had a diagram of the local
+repository which looked like this:
+
Now that we have two repositories, we need a diagram like this:
+
Note that our local repository still contains our earlier work on
+guacamole.md, but the remote repository on GitHub appears
+empty as it doesn’t contain any files yet.
+
2. Connect local to remote repository
+
Now we connect the two repositories. We do this by making the GitHub
+repository a remote for the local
+repository. The home page of the repository on GitHub includes the URL
+string we need to identify it:
+
Click on the ‘SSH’ link to change the protocol from HTTPS to SSH.
+
+
+
+
+
+
HTTPS vs. SSH
+
+
We use SSH here because, while it requires some additional
+configuration, it is a security protocol widely used by many
+applications. The steps below describe SSH at a minimum level for
+GitHub.
+
+
+
+
Copy that URL from the browser, go into the local
+recipes repository, and run this command:
Make sure to use the URL for your repository rather than Alfredo’s:
+the only difference should be your username instead of
+alflin.
+
origin is a local name used to refer to the remote
+repository. It could be called anything, but origin is a
+convention that is often used by default in git and GitHub, so it’s
+helpful to stick with this unless there’s a reason not to.
+
We can check that the command has worked by running
+git remote -v:
We’ll discuss remotes in more detail in the next episode, while
+talking about how they might be used for collaboration.
+
3. SSH Background and Setup
+
Before Alfredo can connect to a remote repository, he needs to set up
+a way for his computer to authenticate with GitHub so it knows it’s him
+trying to connect to his remote repository.
+
We are going to set up the method that is commonly used by many
+different services to authenticate access on the command line. This
+method is called Secure Shell Protocol (SSH). SSH is a cryptographic
+network protocol that allows secure communication between computers
+using an otherwise insecure network.
+
SSH uses what is called a key pair. This is two keys that work
+together to validate access. One key is publicly known and called the
+public key, and the other key called the private key is kept private.
+Very descriptive names.
+
You can think of the public key as a padlock, and only you have the
+key (the private key) to open it. You use the public key where you want
+a secure method of communication, such as your GitHub account. You give
+this padlock, or public key, to GitHub and say “lock the communications
+to my account with this so that only computers that have my private key
+can unlock communications and send git commands as my GitHub
+account.”
+
What we will do now is the minimum required to set up the SSH keys
+and add the public key to a GitHub account.
+
+
+
+
+
+
Advanced SSH
+
+
A supplemental episode in this lesson discusses SSH and key pairs in
+more depth and detail.
+
+
+
+
The first thing we are going to do is check if this has already been
+done on the computer you’re on. Because generally speaking, this setup
+only needs to happen once and then you can forget about it.
+
+
+
+
+
+
Keeping your keys secure
+
+
You shouldn’t really forget about your SSH keys, since they keep your
+account secure. It’s good practice to audit your secure shell keys every
+so often. Especially if you are using multiple computers to access your
+account.
+
+
+
+
We will run the list command to check what key pairs already exist on
+your computer.
+
+
BASH
+
+
ls-al ~/.ssh
+
+
Your output is going to look a little different depending on whether
+or not SSH has ever been set up on the computer you are using.
+
Alfredo has not set up SSH on his computer, so his output is
+
+
OUTPUT
+
+
ls: cannot access '/c/Users/Alfredo/.ssh': No such file or directory
+
+
If SSH has been set up on the computer you’re using, the public and
+private key pairs will be listed. The file names are either
+id_ed25519/id_ed25519.pub or
+id_rsa/id_rsa.pub depending on how the key
+pairs were set up. Since they don’t exist on Alfredo’s computer, he uses
+this command to create them.
+
+
3.1 Create an SSH key pair
+
To create an SSH key pair Alfredo uses this command, where the
+-t option specifies which type of algorithm to use and
+-C attaches a comment to the key (here, Alfredo’s
+email):
If you are using a legacy system that doesn’t support the Ed25519
+algorithm, use:
+$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
+
+
OUTPUT
+
+
Generating public/private ed25519 key pair.
+Enter file in which to save the key (/c/Users/Alfredo/.ssh/id_ed25519):
+
+
We want to use the default file, so just press Enter.
+
+
OUTPUT
+
+
Created directory '/c/Users/Alfredo/.ssh'.
+Enter passphrase (empty for no passphrase):
+
+
Now, it is prompting Alfredo for a passphrase. Since he is using his
+kitchen’s laptop that other people sometimes have access to, he wants to
+create a passphrase. Be sure to use something memorable or save your
+passphrase somewhere, as there is no “reset my password” option. Note
+that, when typing a passphrase on a terminal, there won’t be any visual
+feedback of your typing. This is normal: your passphrase will be
+recorded even if you see nothing changing on your screen.
+
+
OUTPUT
+
+
Enter same passphrase again:
+
+
After entering the same passphrase a second time, we receive the
+confirmation
+
+
OUTPUT
+
+
Your identification has been saved in /c/Users/Alfredo/.ssh/id_ed25519
+Your public key has been saved in /c/Users/Alfredo/.ssh/id_ed25519.pub
+The key fingerprint is:
+SHA256:SMSPIStNyA00KPxuYu94KpZgRAYjgt9g4BA4kFy3g1o a.linguini@ratatouille.fr
+The key's randomart image is:
++--[ED25519 256]--+
+|^B== o. |
+|%*=.*.+ |
+|+=.E =.+ |
+| .=.+.o.. |
+|.... . S |
+|.+ o |
+|+ = |
+|.o.o |
+|oo+. |
++----[SHA256]-----+
+
+
The “identification” is actually the private key. You should never
+share it. The public key is appropriately named. The “key fingerprint”
+is a shorter version of a public key.
+
Now that we have generated the SSH keys, we will find the SSH files
+when we check.
Now we have a SSH key pair and we can run this command to check if
+GitHub can read our authentication.
+
+
BASH
+
+
ssh-T git@github.com
+
+
+
OUTPUT
+
+
The authenticity of host 'github.com (192.30.255.112)' can't be established.
+RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
+This key is not known by any other names
+Are you sure you want to continue connecting (yes/no/[fingerprint])? y
+Please type 'yes', 'no' or the fingerprint: yes
+Warning: Permanently added 'github.com' (RSA) to the list of known hosts.
+git@github.com: Permission denied (publickey).
+
+
Right, we forgot that we need to give GitHub our public key!
+
First, we need to copy the public key. Be sure to include the
+.pub at the end, otherwise you’re looking at the private
+key.
Now, going to GitHub.com, click on your profile icon in the top right
+corner to get the drop-down menu. Click “Settings”, then on the settings
+page, click “SSH and GPG keys”, on the left side “Access” menu. Click
+the “New SSH key” button on the right side. Now, you can add the title
+(Alfredo uses the title “Alfredo’s Kitchen Laptop” so he can remember
+where the original key pair files are located), paste your SSH key into
+the field, and click the “Add SSH key” to complete the setup.
+
Now that we’ve set that up, let’s check our authentication again from
+the command line.
+
+
BASH
+
+
$ ssh -T git@github.com
+
+
+
OUTPUT
+
+
Hi Alfredo! You've successfully authenticated, but GitHub does not provide shell access.
+
+
Good! This output confirms that the SSH key works as intended. We are
+now ready to push our work to the remote repository.
+
+
4. Push local changes to a remote
+
Now that authentication is setup, we can return to the remote. This
+command will push the changes from our local repository to the
+repository on GitHub:
+
+
BASH
+
+
$ git push origin main
+
+
Since Alfredo set up a passphrase, it will prompt him for it. If you
+completed advanced settings for your authentication, it will not prompt
+for a passphrase.
If the network you are connected to uses a proxy, there is a chance
+that your last command failed with “Could not resolve hostname” as the
+error message. To solve this issue, you need to tell Git about the
+proxy:
If your operating system has a password manager configured,
+git push will try to use it when it needs your username and
+password. For example, this is the default behavior for Git Bash on
+Windows. If you want to type your username and password at the terminal
+instead of using a password manager, type:
+
+
BASH
+
+
$ unset SSH_ASKPASS
+
+
in the terminal, before you run git push. Despite the
+name, Git
+uses SSH_ASKPASS for all credential entry, so you may
+want to unset SSH_ASKPASS whether you are using Git via SSH
+or https.
+
You may also want to add unset SSH_ASKPASS at the end of
+your ~/.bashrc to make Git default to using the terminal
+for usernames and passwords.
+
+
+
+
Our local and remote repositories are now in this state:
+
+
+
+
+
+
The ‘-u’ Flag
+
+
You may see a -u option used with git push
+in some documentation. This option is synonymous with the
+--set-upstream-to option for the git branch
+command, and is used to associate the current branch with a remote
+branch so that the git pull command can be used without any
+arguments. To do this, simply use git push -u origin main
+once the remote has been set up.
+
+
+
+
We can pull changes from the remote repository to the local one as
+well:
+
+
BASH
+
+
$ git pull origin main
+
+
+
OUTPUT
+
+
From https://github.com/alflin/recipes
+ * branch main -> FETCH_HEAD
+Already up-to-date.
+
+
Pulling has no effect in this case because the two repositories are
+already synchronized. If someone else had pushed some changes to the
+repository on GitHub, though, this command would download them to our
+local repository.
+
+
+
+
+
+
GitHub GUI
+
+
Browse to your recipes repository on GitHub. Under the
+Code tab, find and click on the text that says “XX commits” (where “XX”
+is some number). Hover over, and click on, the three buttons to the
+right of each commit. What information can you gather/explore from these
+buttons? How would you get that same information in the shell?
+
+
+
+
+
+
+
+
+
The left-most button (with the picture of a clipboard) copies the
+full identifier of the commit to the clipboard. In the shell,
+git log will show you the full commit identifier for each
+commit.
+
When you click on the middle button, you’ll see all of the changes
+that were made in that particular commit. Green shaded lines indicate
+additions and red ones removals. In the shell we can do the same thing
+with git diff. In particular,
+git diff ID1..ID2 where ID1 and ID2 are commit identifiers
+(e.g. git diff a3bf1e5..041e637) will show the differences
+between those two commits.
+
The right-most button lets you view all of the files in the
+repository at the time of that commit. To do this in the shell, we’d
+need to checkout the repository at that particular time. We can do this
+with git checkout ID where ID is the identifier of the
+commit we want to look at. If we do this, we need to remember to put the
+repository back to the right state afterwards!
+
+
+
+
+
+
+
+
+
+
Uploading files directly in GitHub browser
+
+
Github also allows you to skip the command line and upload files
+directly to your repository without having to leave the browser. There
+are two options. First you can click the “Upload files” button in the
+toolbar at the top of the file tree. Or, you can drag and drop files
+from your desktop onto the file tree. You can read more about this on
+this GitHub page.
+
+
+
+
+
+
+
+
+
GitHub Timestamp
+
+
Create a remote repository on GitHub. Push the contents of your local
+repository to the remote. Make changes to your local repository and push
+these changes. Go to the repo you just created on GitHub and check the
+timestamps of the files. How does
+GitHub record times, and why?
+
+
+
+
+
+
+
+
+
GitHub displays timestamps in a human readable relative format
+(i.e. “22 hours ago” or “three weeks ago”). However, if you hover over
+the timestamp, you can see the exact time at which the last change to
+the file occurred.
+
+
+
+
+
+
+
+
+
+
Push vs. Commit
+
+
In this episode, we introduced the “git push” command. How is “git
+push” different from “git commit”?
+
+
+
+
+
+
+
+
+
When we push changes, we’re interacting with a remote repository to
+update it with the changes we’ve made locally (often this corresponds to
+sharing the changes we’ve made with others). Commit only updates your
+local repository.
+
+
+
+
+
+
+
+
+
+
GitHub License and README files
+
+
In this episode we learned about creating a remote repository on
+GitHub, but when you initialized your GitHub repo, you didn’t add a
+README.md or a license file. If you had, what do you think would have
+happened when you tried to link your local and remote repositories?
+
+
+
+
+
+
+
+
+
In this case, we’d see a merge conflict due to unrelated histories.
+When GitHub creates a README.md file, it performs a commit in the remote
+repository. When you try to pull the remote repository to your local
+repository, Git detects that they have histories that do not share a
+common origin and refuses to merge.
+
+
BASH
+
+
$ git pull origin main
+
+
+
OUTPUT
+
+
warning: no common commits
+remote: Enumerating objects: 3, done.
+remote: Counting objects: 100% (3/3), done.
+remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
+Unpacking objects: 100% (3/3), done.
+From https://github.com/alflin/recipes
+ * branch main -> FETCH_HEAD
+ * [new branch] main -> origin/main
+fatal: refusing to merge unrelated histories
+
+
You can force git to merge the two repositories with the option
+--allow-unrelated-histories. Be careful when you use this
+option and carefully examine the contents of local and remote
+repositories before merging.
+
+
BASH
+
+
$ git pull --allow-unrelated-histories origin main
+
+
+
OUTPUT
+
+
From https://github.com/alflin/recipes
+ * branch main -> FETCH_HEAD
+Merge made by the 'recursive' strategy.
+README.md | 1 +
+1 file changed, 1 insertion(+)
+create mode 100644 README.md
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
A local Git repository can be connected to one or more remote
+repositories.
+
Use the SSH protocol to connect to remote repositories.
+
+git push copies changes from a local repository to a
+remote repository.
+
+git pull copies changes from a remote repository to a
+local repository.
How can I use version control to collaborate with other people?
+
+
+
+
+
+
+
Objectives
+
Clone a remote repository.
+
Collaborate by pushing to a common repository.
+
Describe the basic collaborative workflow.
+
+
+
+
+
+
For the next step, get into pairs. One person will be the “Owner” and
+the other will be the “Collaborator”. The goal is that the Collaborator
+add changes into the Owner’s repository. We will switch roles at the
+end, so both persons will play Owner and Collaborator.
+
+
+
+
+
+
Practicing By Yourself
+
+
If you’re working through this lesson on your own, you can carry on
+by opening a second terminal window. This window will represent your
+partner, working on another computer. You won’t need to give anyone
+access on GitHub, because both ‘partners’ are you.
+
+
+
+
The Owner needs to give the Collaborator access. In your repository
+page on GitHub, click the “Settings” button on the right, select
+“Collaborators”, click “Add people”, and then enter your partner’s
+username.
+
To accept access to the Owner’s repo, the Collaborator needs to go to
+https://github.com/notifications
+or check for email notification. Once there she can accept access to the
+Owner’s repo.
+
Next, the Collaborator needs to download a copy of the Owner’s
+repository to her machine. This is called “cloning a repo”.
+
The Collaborator doesn’t want to overwrite her own version of
+recipes.git, so needs to clone the Owner’s repository to a
+different location than her own repository with the same name.
+
To clone the Owner’s repo into her Desktop folder, the
+Collaborator enters:
If you choose to clone without the clone path
+(~/Desktop/alflin-recipes) specified at the end, you will
+clone inside your own recipes folder! Make sure to navigate to the
+Desktop folder first.
+
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:
+
+
BASH
+
+
$ cd ~/Desktop/alflin-recipes
+$ nano hummus.md
+$ cat hummus.md
Then push the change to the Owner’s repository on
+GitHub:
+
+
BASH
+
+
$ git push origin main
+
+
+
OUTPUT
+
+
Enumerating objects: 4, done.
+Counting objects: 4, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (2/2), done.
+Writing objects: 100% (3/3), 306 bytes, done.
+Total 3 (delta 0), reused 0 (delta 0)
+To https://github.com/alflin/recipes.git
+ 9272da5..29aba7c main -> main
+
+
Note that we didn’t have to create a remote called
+origin: Git uses this name by default when we clone a
+repository. (This is why origin was a sensible choice
+earlier when we were setting up remotes by hand.)
+
Take a look at the Owner’s repository on GitHub again, and you should
+be able to see the new commit made by the Collaborator. You may need to
+refresh your browser to see the new commit.
+
+
+
+
+
+
Some more about remotes
+
+
In this episode and the previous one, our local repository has had a
+single “remote”, called origin. A remote is a copy of the
+repository that is hosted somewhere else, that we can push to and pull
+from, and there’s no reason that you have to work with only one. For
+example, on some large projects you might have your own copy in your own
+GitHub account (you’d probably call this origin) and also
+the main “upstream” project repository (let’s call this
+upstream for the sake of examples). You would pull from
+upstream from time to time to get the latest updates that
+other people have committed.
+
Remember that the name you give to a remote only exists locally. It’s
+an alias that you choose - whether origin, or
+upstream, or alfred - and not something
+intrinstic to the remote repository.
+
The git remote family of commands is used to set up and
+alter the remotes associated with a repository. Here are some of the
+most useful ones:
+
+git remote -v lists all the remotes that are configured
+(we already used this in the last episode)
+
+git remote add [name] [url] is used to add a new
+remote
+
+git remote remove [name] removes a remote. Note that it
+doesn’t affect the remote repository at all - it just removes the link
+to it from the local repo.
+
+git remote set-url [name] [newurl] changes the URL that
+is associated with the remote. This is useful if it has moved, e.g. to a
+different GitHub account, or from GitHub to a different hosting service.
+Or, if we made a typo when adding it!
+
+git remote rename [oldname] [newname] changes the local
+alias by which a remote is known - its name. For example, one could use
+this to change upstream to alfred.
+
+
+
+
To download the Collaborator’s changes from GitHub, the Owner now
+enters:
Now the three repositories (Owner’s local, Collaborator’s local, and
+Owner’s on GitHub) are back in sync.
+
+
+
+
+
+
A Basic Collaborative Workflow
+
+
In practice, it is good to be sure that you have an updated version
+of the repository you are collaborating on, so you should
+git pull before making our changes. The basic collaborative
+workflow would be:
+
update your local repo with git pull origin main,
+
make your changes and stage them with git add,
+
commit your changes with git commit -m, and
+
upload the changes to GitHub with
+git push origin main
+
+
It is better to make many commits with smaller changes rather than of
+one commit with massive changes: small commits are easier to read and
+review.
+
+
+
+
+
+
+
+
+
Switch Roles and Repeat
+
+
Switch roles and repeat the whole process.
+
+
+
+
+
+
+
+
+
Review Changes
+
+
The Owner pushed commits to the repository without giving any
+information to the Collaborator. How can the Collaborator find out what
+has changed with command line? And on GitHub?
+
+
+
+
+
+
+
+
+
On the command line, the Collaborator can use
+git fetch origin main to get the remote changes into the
+local repository, but without merging them. Then by running
+git diff main origin/main the Collaborator will see the
+changes output in the terminal.
+
On GitHub, the Collaborator can go to the repository and click on
+“commits” to view the most recent commits pushed to the repository.
+
+
+
+
+
+
+
+
+
+
Comment Changes in GitHub
+
+
The Collaborator has some questions about one line change made by the
+Owner and has some suggestions to propose.
+
With GitHub, it is possible to comment on the diff of a commit. Over
+the line of code to comment, a blue comment icon appears to open a
+comment window.
+
The Collaborator posts her comments and suggestions using the GitHub
+interface.
+
+
+
+
+
+
+
+
+
Version History, Backup, and Version Control
+
+
Some backup software can keep a history of the versions of your
+files. They also allows you to recover specific versions. How is this
+functionality different from version control? What are some of the
+benefits of using version control, Git and GitHub?
+
+
+
+
+
+
+
+
+
Key Points
+
+
+git clone copies a remote repository to create a local
+repository with a remote called origin automatically set
+up.
What do I do when my changes conflict with someone else’s?
+
+
+
+
+
+
+
Objectives
+
Explain what conflicts are and when they can occur.
+
Resolve conflicts resulting from a merge.
+
+
+
+
+
+
As soon as people can work in parallel, they’ll likely step on each
+other’s toes. This will even happen with a single person: if we are
+working on a piece of software on both our laptop and a server in the
+lab, we could make different changes to each copy. Version control helps
+us manage these conflicts by
+giving us tools to resolve
+overlapping changes.
+
To see how we can resolve conflicts, we must first create one. The
+file guacamole.md currently looks like this in both
+partners’ copies of our recipes repository:
To https://github.com/alflin/recipes.git
+ ! [rejected] main -> main (fetch first)
+error: failed to push some refs to 'https://github.com/alflin/recipes.git'
+hint: Updates were rejected because the remote contains work that you do
+hint: not have locally. This is usually caused by another repository pushing
+hint: to the same ref. You may want to first integrate the remote changes
+hint: (e.g., 'git pull ...') before pushing again.
+hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+
+
Git rejects the push because it detects that the remote repository
+has new updates that have not been incorporated into the local branch.
+What we have to do is pull the changes from GitHub, merge them into the copy we’re currently
+working in, and then push that. Let’s start by pulling:
+
+
BASH
+
+
$ git pull origin main
+
+
+
OUTPUT
+
+
remote: Enumerating objects: 5, done.
+remote: Counting objects: 100% (5/5), done.
+remote: Compressing objects: 100% (1/1), done.
+remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0
+Unpacking objects: 100% (3/3), done.
+From https://github.com/alflin/recipes
+ * branch main -> FETCH_HEAD
+ 29aba7c..dabb4c8 main -> origin/main
+Auto-merging guacamole.md
+CONFLICT (content): Merge conflict in guacamole.md
+Automatic merge failed; fix conflicts and then commit the result.
+
+
+
+
+
+
+
You may need to tell Git what to do
+
+
If you see the below in your output, Git is asking what it should
+do.
+
+
OUTPUT
+
+
hint: You have divergent branches and need to specify how to reconcile them.
+hint: You can do so by running one of the following commands sometime before
+hint: your next pull:
+hint:
+hint: git config pull.rebase false # merge (the default strategy)
+hint: git config pull.rebase true # rebase
+hint: git config pull.ff only # fast-forward only
+hint:
+hint: You can replace "git config" with "git config --global" to set a default
+hint: preference for all repositories. You can also pass --rebase, --no-rebase,
+hint: or --ff-only on the command line to override the configured default per
+hint: invocation.
+
+
In newer versions of Git it gives you the option of specifying
+different behaviours when a pull would merge divergent branches. In our
+case we want ‘the default strategy’. To use this strategy run the
+following command to select it as the default thing git should do.
+
+
BASH
+
+
$ git config pull.rebase false
+
+
Then attempt the pull again.
+
+
BASH
+
+
$ git pull origin main
+
+
+
+
+
The git pull command updates the local repository to
+include those changes already included in the remote repository. After
+the changes from remote branch have been fetched, Git detects that
+changes made to the local copy overlap with those made to the remote
+repository, and therefore refuses to merge the two versions to stop us
+from trampling on our previous work. The conflict is marked in in the
+affected file:
+
+
BASH
+
+
$ cat guacamole.md
+
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+* avocado
+* lime
+* salt
+## Instructions
+<<<<<<< HEAD
+* peel the avocados
+=======
+* put one avocado into a bowl.
+>>>>>>> dabb4c8c450e8475aee9b14b4383acc99f42af1d
+
+
Our change is preceded by
+<<<<<<< HEAD. Git has then inserted
+======= as a separator between the conflicting changes and
+marked the end of the content downloaded from GitHub with
+>>>>>>>. (The string of letters and
+digits after that marker identifies the commit we’ve just
+downloaded.)
+
It is now up to us to edit this file to remove these markers and
+reconcile the changes. We can do anything we want: keep the change made
+in the local repository, keep the change made in the remote repository,
+write something new to replace both, or get rid of the change entirely.
+Let’s replace both so that the file looks like this:
+
+
BASH
+
+
$ cat guacamole.md
+
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+* avocado
+* lime
+* salt
+## Instructions
+* peel the avocados and put them into a bowl.
+
+
To finish merging, we add guacamole.md to the changes
+being made by the merge and then commit:
+
+
BASH
+
+
$ git add guacamole.md
+$ git status
+
+
+
OUTPUT
+
+
On branch main
+All conflicts fixed but you are still merging.
+ (use "git commit" to conclude merge)
+
+Changes to be committed:
+
+ modified: guacamole.md
+
+
+
+
BASH
+
+
$ git commit -m"Merge changes from GitHub"
+
+
+
OUTPUT
+
+
[main 2abf2b1] Merge changes from GitHub
+
+
Now we can push our changes to GitHub:
+
+
BASH
+
+
$ git push origin main
+
+
+
OUTPUT
+
+
Enumerating objects: 10, done.
+Counting objects: 100% (10/10), done.
+Delta compression using up to 8 threads
+Compressing objects: 100% (6/6), done.
+Writing objects: 100% (6/6), 645 bytes | 645.00 KiB/s, done.
+Total 6 (delta 4), reused 0 (delta 0)
+remote: Resolving deltas: 100% (4/4), completed with 2 local objects.
+To https://github.com/alflin/recipes.git
+ dabb4c8..2abf2b1 main -> main
+
+
Git keeps track of what we’ve merged with what, so we don’t have to
+fix things by hand again when the collaborator who made the first change
+pulls again:
# Guacamole
+## Ingredients
+* avocado
+* lime
+* salt
+## Instructions
+* peel the avocados and put them into a bowl.
+
+
We don’t need to merge again because Git knows someone has already
+done that.
+
Git’s ability to resolve conflicts is very useful, but conflict
+resolution costs time and effort, and can introduce errors if conflicts
+are not resolved correctly. If you find yourself resolving a lot of
+conflicts in a project, consider these technical approaches to reducing
+them:
+
Pull from upstream more frequently, especially before starting new
+work
+
Use topic branches to segregate work, merging to main when
+complete
+
Make smaller more atomic commits
+
Push your work when it is done and encourage your team to do the
+same to reduce work in progress and, by extension, the chance of having
+conflicts
+
Where logically appropriate, break large files into smaller ones so
+that it is less likely that two authors will alter the same file
+simultaneously
+
Conflicts can also be minimized with project management
+strategies:
+
Clarify who is responsible for what areas with your
+collaborators
+
Discuss what order tasks should be carried out in with your
+collaborators so that tasks expected to change the same lines won’t be
+worked on simultaneously
+
If the conflicts are stylistic churn (e.g. tabs vs. spaces),
+establish a project convention that is governing and use code style
+tools (e.g. htmltidy, perltidy,
+rubocop, etc.) to enforce, if necessary
+
+
+
+
+
+
Solving Conflicts that You Create
+
+
Clone the repository created by your instructor. Add a new file to
+it, and modify an existing file (your instructor will tell you which
+one). When asked by your instructor, pull her changes from the
+repository to create a conflict, then resolve it.
+
+
+
+
+
+
+
+
+
Conflicts on Non-textual files
+
+
What does Git do when there is a conflict in an image or some other
+non-textual file that is stored in version control?
+
+
+
+
+
+
+
+
+
Let’s try it. Suppose Alfredo takes a picture of its guacamole and
+calls it guacamole.jpg.
+
If you do not have an image file of guacamole available, you can
+create a dummy binary file like this:
+
+
BASH
+
+
$ head --bytes 1024 /dev/urandom > guacamole.jpg
+$ ls -lh guacamole.jpg
+
+
+
OUTPUT
+
+
-rw-r--r-- 1 alflin 57095 1.0K Mar 8 20:24 guacamole.jpg
+
+
ls shows us that this created a 1-kilobyte file. It is
+full of random bytes read from the special file,
+/dev/urandom.
+
Now, suppose Alfredo adds guacamole.jpg to his
+repository:
Suppose that Jimmy has added a similar picture in the meantime. His
+is a picture of a guacamole with nachos, but it is also called
+guacamole.jpg. When Alfredo tries to push, he gets a
+familiar message:
+
+
BASH
+
+
$ git push origin main
+
+
+
OUTPUT
+
+
To https://github.com/alflin/recipes.git
+ ! [rejected] main -> main (fetch first)
+error: failed to push some refs to 'https://github.com/alflin/recipes.git'
+hint: Updates were rejected because the remote contains work that you do
+hint: not have locally. This is usually caused by another repository pushing
+hint: to the same ref. You may want to first integrate the remote changes
+hint: (e.g., 'git pull ...') before pushing again.
+hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+
+
We’ve learned that we must pull first and resolve any conflicts:
+
+
BASH
+
+
$ git pull origin main
+
+
When there is a conflict on an image or other binary file, git prints
+a message like this:
+
+
OUTPUT
+
+
$ git pull origin main
+remote: Counting objects: 3, done.
+remote: Compressing objects: 100% (3/3), done.
+remote: Total 3 (delta 0), reused 0 (delta 0)
+Unpacking objects: 100% (3/3), done.
+From https://github.com/alflin/recipes.git
+ * branch main -> FETCH_HEAD
+ 6a67967..439dc8c main -> origin/main
+warning: Cannot merge binary files: guacamole.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e)
+Auto-merging guacamole.jpg
+CONFLICT (add/add): Merge conflict in guacamole.jpg
+Automatic merge failed; fix conflicts and then commit the result.
+
+
The conflict message here is mostly the same as it was for
+guacamole.md, but there is one key additional line:
+
+
OUTPUT
+
+
warning: Cannot merge binary files: guacamole.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e)
+
+
Git cannot automatically insert conflict markers into an image as it
+does for text files. So, instead of editing the image file, we must
+check out the version we want to keep. Then we can add and commit this
+version.
+
On the key line above, Git has conveniently given us commit
+identifiers for the two versions of guacamole.jpg. Our
+version is HEAD, and Jimmy’s version is
+439dc8c0.... If we want to use our version, we can use
+git checkout:
+
+
BASH
+
+
$ git checkout HEAD guacamole.jpg
+$ git add guacamole.jpg
+$ git commit -m"Use image of just guacamole instead of with nachos"
+
+
+
OUTPUT
+
+
[main 21032c3] Use image of just guacamole instead of with nachos
+
+
If instead we want to use Jimmy’s version, we can use
+git checkout with Jimmy’s commit identifier,
+439dc8c0:
+
+
BASH
+
+
$ git checkout 439dc8c0 guacamole.jpg
+$ git add guacamole.jpg
+$ git commit -m"Use image of guacamole with nachos instead of just guacamole"
+
+
+
OUTPUT
+
+
[main da21b34] Use image of guacamole with nachos instead of just guacamole
+
+
We can also keep both images. The catch is that we cannot
+keep them under the same name. But, we can check out each version in
+succession and rename it, then add the renamed versions. First,
+check out each image and rename it:
Then, remove the old guacamole.jpg and add the two new
+files:
+
+
BASH
+
+
$ git rm guacamole.jpg
+$ git add guacamole-only.jpg
+$ git add guacamole-nachos.jpg
+$ git commit -m"Use two images: just guacamole and with nachos"
+
+
+
OUTPUT
+
+
[main 94ae08c] Use two images: just guacamole and with nachos
+ 2 files changed, 0 insertions(+), 0 deletions(-)
+ create mode 100644 guacamole-nachos.jpg
+ rename guacamole.jpg => guacamole-only.jpg (100%)
+
+
Now both images of guacamole are checked into the repository, and
+guacamole.jpg no longer exists.
+
+
+
+
+
+
+
+
+
+
A Typical Work Session
+
+
You sit down at your computer to work on a shared project that is
+tracked in a remote Git repository. During your work session, you take
+the following actions, but not in this order:
+
+Make changes by appending the number 100 to a
+text file numbers.txt
+
+
+Update remote repository to match the local repository
+
+Celebrate your success with some fancy beverage(s)
+
+Update local repository to match the remote repository
+
+Stage changes to be committed
+
+Commit changes to the local repository
+
In what order should you perform these actions to minimize the
+chances of conflicts? Put the commands above in order in the
+action column of the table below. When you have the order
+right, see if you can write the corresponding commands in the
+command column. A few steps are populated to get you
+started.
+
order
+
action . . . . . . . . . .
+
command . . . . . . . . . .
+
1
+
+
+
2
+
+
echo 100 >> numbers.txt
+
3
+
+
+
4
+
+
+
5
+
+
+
6
+
Celebrate!
+
+
+
+
+
+
+
+
+
+
order
+
action . . . . . .
+
command . . . . . . . . . . . . . . . . . . .
+
1
+
Update local
+
git pull origin main
+
2
+
Make changes
+
echo 100 >> numbers.txt
+
3
+
Stage changes
+
git add numbers.txt
+
4
+
Commit changes
+
git commit -m "Add 100 to numbers.txt"
+
5
+
Update remote
+
git push origin main
+
6
+
Celebrate!
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
Conflicts occur when two or more people change the same lines of the
+same file.
+
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/10-open.html b/10-open.html
new file mode 100644
index 0000000000..9e692ca2c2
--- /dev/null
+++ b/10-open.html
@@ -0,0 +1,642 @@
+
+Version Control with Git: Open Science
+ Skip to main content
+
How can version control help me make my work more open?
+
+
+
+
+
+
+
Objectives
+
Explain how a version control system can be leveraged as an
+electronic lab notebook for computational work.
+
+
+
+
+
+
+
The opposite of “open” isn’t “closed”. The opposite of “open” is
+“broken”.
+
-– John Wilbanks
+
+
Free sharing of information might be the ideal in science, but the
+reality is often more complicated. Normal practice today looks something
+like this:
+
A scientist collects some data and stores it on a machine that is
+occasionally backed up by their department.
+
They then write or modify a few small programs (which also reside on
+the machine) to analyze that data.
+
Once they have some results, they write them up and submit a paper.
+The scientist might include their data – a growing number of journals
+require this – but they probably don’t include the code.
+
Time passes.
+
The journal sends the scientist reviews written anonymously by a
+handful of other people in their field. The scientist revises the paper
+to satisfy the reviewers, during which time they might also modify the
+scripts they wrote earlier, and resubmits.
+
More time passes.
+
The paper is eventually published. It might include a link to an
+online copy of the data, but the paper itself will be behind a paywall:
+only people who have personal or institutional access will be able to
+read it.
+
For a growing number of scientists, though, the process looks like
+this:
+
The data that the scientist collects is stored in an open access
+repository like figshare or Zenodo, possibly as soon as it’s
+collected, and given its own Digital
+Object Identifier (DOI). Or the data was already published and is
+stored in Dryad.
+
The scientist creates a new repository on GitHub to hold their
+work.
+
During analysis, they push changes to their scripts (and possibly
+some output files) to that repository. The scientist also uses the
+repository for their paper; that repository is then the hub for
+collaboration with colleagues.
+
When they are happy with the state of the paper, the scientist posts
+a version to arXiv or some other
+preprint server to invite feedback from peers.
+
Based on that feedback, they may post several revisions before
+finally submitting the paper to a journal.
+
The published paper includes links to the preprint and to the code
+and data repositories, which makes it much easier for other scientists
+to use their work as starting point for their own research.
+
This open model accelerates discovery: the more open work is, the more widely it
+is cited and re-used. However, people who want to work this way need
+to make some decisions about what exactly “open” means and how to do it.
+You can find more on the different aspects of Open Science in this
+book.
+
This is one of the (many) reasons we teach version control. When used
+diligently, it answers the “how” question by acting as a shareable
+electronic lab notebook for computational work:
+
The conceptual stages of your work are documented, including who did
+what and when. Every step is stamped with an identifier (the commit ID)
+that is for most intents and purposes unique.
+
You can tie documentation of rationale, ideas, and other
+intellectual work directly to the changes that spring from them.
+
You can refer to what you used in your research to obtain your
+computational results in a way that is unique and recoverable.
+
With a version control system such as Git, the entire history of the
+repository is easy to archive for perpetuity.
+
+
+
+
+
+
Making Code Citable
+
+
Anything that is hosted in a version control repository (data, code,
+papers, etc.) can be turned into a citable object. You’ll learn how to
+do this in the later episode on
+Citation.
+
+
+
+
+
+
+
+
+
How Reproducible Is My Work?
+
+
Ask one of your labmates to reproduce a result you recently obtained
+using only what they can find in your papers or on the web. Try to do
+the same for one of their results, then try to do it for a result from a
+lab you work with.
+
+
+
+
+
+
+
+
+
How to Find an Appropriate Data Repository?
+
+
Surf the internet for a couple of minutes and check out the data
+repositories mentioned above: Figshare, Zenodo, Dryad. Depending on your field of
+research, you might find community-recognized repositories that are
+well-known in your field. You might also find useful these
+data repositories recommended by Nature. Discuss with your neighbor
+which data repository you might want to approach for your current
+project and explain why.
+
+
+
+
+
+
+
+
+
How to Track Large Data or Image Files using Git?
+
+
Large data or image files such as .md5 or
+.psd file types can be tracked within a github repository
+using the Git Large File
+Storage open source extension tool. This tool automatically uploads
+large file contents to a remote server and replaces the file with a text
+pointer within the github repository.
+
Try downloading and installing the Git Large File Storage extension
+tool, then add tracking of a large file to your github repository. Ask a
+colleague to clone your repository and describe what they see when they
+access that large file.
+
+
+
+
+
+
+
+
+
Key Points
+
+
Open scientific work is more useful and more highly cited than
+closed.
What licensing information should I include with my work?
+
+
+
+
+
+
+
Objectives
+
Explain why adding licensing information to a repository is
+important.
+
Choose a proper license.
+
Explain differences in licensing and social expectations.
+
+
+
+
+
+
When a repository with source code, a manuscript or other creative
+works becomes public, it should include a file LICENSE or
+LICENSE.txt in the base directory of the repository that
+clearly states under which license the content is being made available.
+This is because creative works are automatically eligible for
+intellectual property (and thus copyright) protection. Reusing creative
+works without a license is dangerous, because the copyright holders
+could sue you for copyright infringement.
+
A license solves this problem by granting rights to others (the
+licensees) that they would otherwise not have. What rights are being
+granted under which conditions differs, often only slightly, from one
+license to another. In practice, a few licenses are by far the most
+popular, and choosealicense.com will help you
+find a common license that suits your needs. Important considerations
+include:
+
Whether you want to address patent rights.
+
Whether you require people distributing derivative works to also
+distribute their source code.
+
Whether the content you are licensing is source code.
+
Whether you want to license the code at all.
+
Choosing a license that is in common use makes life easier for
+contributors and users, because they are more likely to already be
+familiar with the license and don’t have to wade through a bunch of
+jargon to decide if they’re ok with it. The Open Source Initiative and Free Software
+Foundation both maintain lists of licenses which are good
+choices.
+
This
+article provides an excellent overview of licensing and licensing
+options from the perspective of scientists who also write code.
+
At the end of the day what matters is that there is a clear statement
+as to what the license is. Also, the license is best chosen from the
+get-go, even if for a repository that is not public. Pushing off the
+decision only makes it more complicated later, because each time a new
+collaborator starts contributing, they, too, hold copyright and will
+thus need to be asked for approval once a license is chosen.
+
+
+
+
+
+
Can I Use Open License?
+
+
Find out whether you are allowed to apply an open license to your
+software. Can you do this unilaterally, or do you need permission from
+someone in your institution? If so, who?
+
+
+
+
+
+
+
+
+
What licenses have I already accepted?
+
+
Many of the software tools we use on a daily basis (including in this
+workshop) are released as open-source software. Pick a project on GitHub
+from the list below, or one of your own choosing. Find its license
+(usually in a file called LICENSE or COPYING)
+and talk about how it restricts your use of the software. Is it one of
+the licenses discussed in this session? How is it different?
The LICENSE, LICENSE.md, or
+LICENSE.txt file is often used in a repository to indicate
+how the contents of the repo may be used by others.
+
People who incorporate General Public License (GPL’d) software into
+their own software must make the derived software also open under the
+GPL license if they decide to share it; most other open licenses do not
+require this.
+
The Creative Commons family of licenses allow people to mix and
+match requirements and restrictions on attribution, creation of
+derivative works, further sharing, and commercialization.
+
People who are not lawyers should not try to write licenses from
+scratch.
Smith AM, Katz DS, Niemeyer KE, FORCE11 Software Citation Working Group. (2016) Software citation
+principles. [PeerJ Computer Science 2:e86](https://peerj.com/articles/cs-86/)
+https://doi.org/10.7717/peerj-cs.8
+
There is also an @software{...
+BibTeX entry type in case
+no “umbrella” citation like a paper or book exists for the project you
+want to make citable.
+
+
+
+
+
+
Key Points
+
+
Add a CITATION file to a repository to explain how you want your
+work cited.
Where should I host my version control repositories?
+
+
+
+
+
+
+
Objectives
+
Explain different options for hosting scientific work.
+
+
+
+
+
+
After choosing a license, another big
+question for groups that want to open up their work is where to host
+their code and data. One option is for the lab, the department, or the
+university to provide a server, manage accounts and backups, and so on.
+The main benefit of this is that it clarifies who owns what, which is
+particularly important if any of the material is sensitive (i.e.,
+relates to experiments involving human subjects or may be used in a
+patent application). The main drawbacks are the cost of providing the
+service and its longevity: a scientist who has spent ten years
+collecting data would like to be sure that data will still be available
+ten years from now, but that’s well beyond the lifespan of most of the
+grants that fund academic infrastructure.
+
Another option is to purchase a domain and pay an Internet service
+provider (ISP) to host it. This gives the individual or group more
+control, and sidesteps problems that can arise when moving from one
+institution to another, but requires more time and effort to set up than
+either the option above or the option below.
+
The third option is to use a public hosting service like GitHub, GitLab, or BitBucket. Each of these services
+provides a web interface that enables people to create, view, and edit
+their code repositories. These services also provide communication and
+project management tools including issue tracking, wiki pages, email
+notifications, and code reviews. These services benefit from economies
+of scale and network effects: it’s easier to run one large service well
+than to run many smaller services to the same standard. It’s also easier
+for people to collaborate. Using a popular service can help connect your
+project with communities already using the same service.
+
As an example, Software Carpentry is on GitHub where you can
+find the source
+for this page. Anyone with a GitHub account can suggest changes to
+this text.
Using large, well-established services can also help you quickly take
+advantage of powerful tools. One such tool, continuous integration (CI),
+can automatically run software builds and tests whenever code is
+committed or pull requests are submitted. Direct integration of CI with
+an online hosting service means this information is present in any pull
+request, and helps maintain code integrity and quality standards. While
+CI is still available in self-hosted situations, there is much less
+setup and maintenance involved with using an online service.
+Furthermore, such tools are often provided free of charge to open source
+projects, and are also available for private repositories for a fee.
+
+
+
+
+
+
Institutional Barriers
+
+
Sharing is the ideal for science, but many institutions place
+restrictions on sharing, for example to protect potentially patentable
+intellectual property. If you encounter such restrictions, it can be
+productive to inquire about the underlying motivations and either to
+request an exception for a specific project or domain, or to push more
+broadly for institutional reform to support more open science.
+
+
+
+
+
+
+
+
+
Can My Work Be Public?
+
+
Find out whether you are allowed to host your work openly in a public
+repository. Can you do this unilaterally, or do you need permission from
+someone in your institution? If so, who?
+
+
+
+
+
+
+
+
+
Where Can I Share My Work?
+
+
Does your institution have a repository or repositories that you can
+use to share your papers, data and software? How do institutional
+repositories differ from services like arXiV, figshare, GitHub or GitLab?
+
+
+
+
+
+
+
+
+
Key Points
+
+
Projects can be hosted on university servers, on personal domains,
+or on a public hosting service.
+
Rules regarding intellectual property and storage of sensitive
+information apply no matter where code and data are hosted.
+
+
diff --git a/14-supplemental-rstudio.html b/14-supplemental-rstudio.html
new file mode 100644
index 0000000000..7ca9017277
--- /dev/null
+++ b/14-supplemental-rstudio.html
@@ -0,0 +1,665 @@
+
+Version Control with Git: Supplemental: Using Git from RStudio
+ Skip to main content
+
Version control can be very useful when developing data analysis
+scripts. For that reason, the popular development environment RStudio for the R programming
+language has built-in integration with Git. While some advanced Git
+features still require the command-line, RStudio has a nice interface
+for many common Git operations.
+
RStudio allows us to create a project
+associated with a given directory to keep track of various related
+files. To be able to track the development of the project over time, to
+be able to revert to previous versions, and to collaborate with others,
+we version control the Rstudio project with Git. To get started using
+Git in RStudio, we create a new project:
+
This opens a dialog asking us how we want to create the project. We
+have some options here. Let’s say that we want to use RStudio with the
+recipes repository that we already made. Since that repository lives in
+a directory on our computer, we choose the option “Existing
+Directory”:
+
+
+
+
+
+
Do You See a “Version Control” Option?
+
+
Although we’re not going to use it here, there should be a “version
+control” option on this menu. That is what you would click on if you
+wanted to create a project on your computer by cloning a repository from
+GitHub. If that option is not present, it probably means that RStudio
+doesn’t know where your Git executable is, and you won’t be able to
+progress further in this lesson until you tell RStudio where it is.
+
+
Find your Git Executable
+
First let’s make sure that Git is installed on your computer. Open
+your shell on Mac or Linux, or on Windows open the command prompt and
+then type:
+
+which git (macOS, Linux)
+
+where git (Windows)
+
If there is no version of Git on your computer, please follow the Git
+installation instructions in the setup of this lesson to install Git
+now. Next open your shell or command prompt and type
+which git (macOS, Linux), or where git
+(Windows). Copy the path to the git executable.
+
On one Windows computer which had GitHub Desktop installed on it, the
+path was:
+C:/Users/UserName/AppData/Local/GitHubDesktop/app-1.1.1/resources/app/git/cmd/git.exe
+
NOTE: The path on your computer will be somewhat different.
+
+
+
Tell RStudio where to find GitHub
+
In RStudio, go to the Tools menu >
+Global Options > Git/SVN and then browse to
+the Git executable you found in the command prompt or shell. Now restart
+RStudio. Note: Even if you have Git installed, you may need 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”:
+
Ta-da! We have created a new project in RStudio within the existing
+recipes repository. Notice the vertical “Git” menu in the menu bar.
+RStudio has recognized that the current directory is a Git repository,
+and gives us a number of tools to use Git:
+
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 Hummus:
+
Once we have saved our edited files, we can use RStudio to commit the
+changes by clicking on “Commit…” in the Git menu:
+
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 message (in the upper right panel). The icons in the “Status”
+column indicate 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”:
+
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:
+
+
+
+
+
+
Are the Push/Pull Commands Grayed Out?
+
+
Grayed out Push/Pull commands generally mean that RStudio doesn’t
+know the location of your remote repository (e.g. on GitHub). To fix
+this, open a terminal to the repository and enter the command:
+git push -u origin main. Then restart RStudio.
+
+
+
+
If we click on “History”, we can see a graphical version of what
+git log would tell us:
+
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 file:
+
+
+
+
+
+
Tip: versioning disposable output
+
+
Generally you do not want to version control disposable output (or
+read-only data). You should modify the .gitignore file to
+tell Git to ignore these files and directories.
+
+
+
+
+
+
+
+
+
Challenge
+
+
Create a new directory within your project called
+graphs.
+
Modify the .gitignore so that the graphs
+directory is not version controlled.
+
+
+
+
+
+
+
+
+
This can be done in Rstudio:
+
+
R
+
+
+dir.create("./graphs")
+
+
Then open up the .gitignore file from the right-hand
+panel of Rstudio and add graphs/ to the list of files to
+ignore.
+
+
+
+
+
There are many more features in the RStudio Git menu, but these
+should be enough to get you started!
+
+
+
+
+
+
Key Points
+
+
Using RStudio’s Git integration allows you to version control a
+project over time.
+
+
diff --git a/404.html b/404.html
new file mode 100644
index 0000000000..3cd0fcf4c7
--- /dev/null
+++ b/404.html
@@ -0,0 +1,478 @@
+
+Version Control with Git: Page not found
+ Skip to main content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Version Control with Git
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Page not found
+
+
Our apologies!
+
We cannot seem to find the page you are looking for. Here are some
+tips that may help:
+
+
diff --git a/CODE_OF_CONDUCT.html b/CODE_OF_CONDUCT.html
new file mode 100644
index 0000000000..3ff8244af6
--- /dev/null
+++ b/CODE_OF_CONDUCT.html
@@ -0,0 +1,482 @@
+
+Version Control with Git: Contributor Code of Conduct
+ Skip to main content
+
to Share—copy and redistribute the material in any
+medium or format
+
to Adapt—remix, transform, and build upon the
+material
+
for any purpose, even commercially.
+
The licensor cannot revoke these freedoms as long as you follow the
+license terms.
+
Under the following terms:
+
Attribution—You must give appropriate credit
+(mentioning that your work is derived from work that is Copyright (c)
+The Carpentries and, where practical, linking to https://carpentries.org/), provide a link to the
+license, and indicate if changes were made. You may do so in any
+reasonable manner, but not in any way that suggests the licensor
+endorses you or your use.
+
No additional restrictions—You may not apply
+legal terms or technological measures that legally restrict others from
+doing anything the license permits. With the understanding
+that:
+
Notices:
+
You do not have to comply with the license for elements of the
+material in the public domain or where your use is permitted by an
+applicable exception or limitation.
+
No warranties are given. The license may not give you all of the
+permissions necessary for your intended use. For example, other rights
+such as publicity, privacy, or moral rights may limit how you use the
+material.
+
Software
+
Except where otherwise noted, the example programs and other software
+provided by The Carpentries are made available under the OSI-approved MIT
+license.
+
Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+“Software”), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
Trademark
+
“The Carpentries”, “Software Carpentry”, “Data Carpentry”, and
+“Library Carpentry” and their respective logos are registered trademarks
+of Community Initiatives.
Understand the benefits of an automated version control system.
+
Understand the basics of how automated version control systems
+work.
+
+
+
+
+
+
+
We’ll start by exploring how version control can be used to keep
+track of what one person did and when. Even if you aren’t collaborating
+with other people, automated version control is much better than this
+situation:
We’ve all been in this situation before: it seems unnecessary to have
+multiple nearly-identical versions of the same document. Some word
+processors let us deal with this a little better, such as Microsoft
+Word’s Track
+Changes, Google Docs’ version
+history, or LibreOffice’s Recording
+and Displaying Changes.
+
Version control systems start with a base version of the document and
+then record changes you make each step of the way. You can 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.
+
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.
+
Unless multiple users make changes to the same section of the
+document - a conflict - you can
+incorporate two sets of changes into the same base document.
+
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 which changes will be made to the next version (each record
+of these changes is called a commit), and keeps useful metadata
+about them. The complete history of commits for a particular project and
+their metadata make up a repository. Repositories can be
+kept in sync across different computers, facilitating collaboration
+among different people.
+
+
+
+
+
+
The Long History of Version Control Systems
+
+
Automated version control systems are nothing new. Tools like RCS, CVS,
+or Subversion
+have been around since the early 1980s and are used by many large
+companies. However, many of these are now considered legacy systems
+(i.e., outdated) due to various limitations in their capabilities. More
+modern systems, such as Git and Mercurial, are
+distributed, meaning that they do not need a centralized server
+to host the repository. These modern systems also include powerful
+merging tools that make it possible for multiple authors to work on the
+same files concurrently.
+
+
+
+
+
+
+
+
+
Paper Writing
+
+
+
Imagine you drafted an excellent paragraph for a paper you are
+writing, but later ruin it. How would you retrieve the
+excellent version of your conclusion? Is it even
+possible?
+
Imagine you have 5 co-authors. How would you manage the changes
+and comments they make to your paper? If you use LibreOffice Writer or
+Microsoft Word, what happens if you accept changes made using the
+Track Changes option? Do you have a history of those
+changes?
+
+
+
+
+
+
+
+
+
+
+
Recovering the excellent version is only possible if you created
+a copy of the old version of the paper. The danger of losing good
+versions often leads to the problematic workflow illustrated in the PhD
+Comics cartoon at the top of this page.
+
Collaborative writing with traditional word processors is
+cumbersome. Either every collaborator has to work on a document
+sequentially (slowing down the process of writing), or you have to send
+out a version to all collaborators and manually merge their comments
+into your document. The ‘track changes’ or ‘record changes’ option can
+highlight changes for you and simplifies merging, but as soon as you
+accept changes you will lose their history. You will then no longer know
+who suggested that change, why it was suggested, or when it was merged
+into the rest of the document. Even online word processors like Google
+Docs or Microsoft Office Online do not fully resolve these
+problems.
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
Version control is like an unlimited ‘undo’.
+
Version control also allows many people to work in parallel.
Configure git the first time it is used on a
+computer.
+
Understand the meaning of the --global configuration
+flag.
+
+
+
+
+
+
+
When we use Git on a new computer for the first time, we need to
+configure a few things. Below are a few examples of configurations we
+will set as we get started with Git:
+
+
our name and email address,
+
what our preferred text editor is,
+
and that we want to use these settings globally (i.e. for every
+project).
+
+
On a command line, Git commands are written as
+git verb options, where verb is what we
+actually want to do and options is additional optional
+information which may be needed for the verb. So here is
+how Alfredo sets up his new laptop:
Please use your own name and email address instead of Alfredo’s. This
+user name and email will be associated with your subsequent Git
+activity, which means that any changes pushed to GitHub, BitBucket, GitLab or another Git host server after
+this lesson will include this information.
+
For this lesson, we will be interacting with GitHub and so the email address used
+should be the same as the one used when setting up your GitHub account.
+If you are concerned about privacy, please review GitHub’s
+instructions for keeping your email address private.
+
+
+
+
+
+
Keeping your email private
+
+
If you elect to use a private email address with GitHub, then use
+GitHub’s no-reply email address for the user.email value.
+It looks like ID+username@users.noreply.github.com. You can
+look up your own address in your GitHub email settings.
+
+
+
+
+
+
+
+
+
Line Endings
+
+
As with other keys, when you hit Enter or ↵ or
+on Macs, Return on your keyboard, your computer encodes this
+input as a character. Different operating systems use different
+character(s) to represent the end of a line. (You may also hear these
+referred to as newlines or line breaks.) Because Git uses these
+characters to compare files, it may cause unexpected issues when editing
+a file on different machines. Though it is beyond the scope of this
+lesson, you can read more about this issue in
+the Pro Git book.
+
You can change the way Git recognizes and encodes line endings using
+the core.autocrlf command to git config. The
+following settings are recommended:
+
On macOS and Linux:
+
+
BASH
+
+
$ git config --global core.autocrlf input
+
+
And on Windows:
+
+
BASH
+
+
$ git config --global core.autocrlf true
+
+
+
+
+
Alfredo also has to set his favorite text editor, following this
+table:
It is possible to reconfigure the text editor for Git whenever you
+want to change it.
+
+
+
+
+
+
Exiting Vim
+
+
Note that Vim is the default editor for many programs. If you haven’t
+used Vim before and wish to exit a session without saving your changes,
+press Esc then type :q! and hit Enter
+or ↵ or on Macs, Return. If you want to save your
+changes and quit, press Esc then type :wq and
+hit Enter or ↵ or on Macs, Return.
+
+
+
+
Git (2.28+) allows configuration of the name of the branch created
+when you initialize any new repository. Alfredo decides to use that
+feature to set it to main so it matches the cloud service
+he will eventually use.
+
+
BASH
+
+
$ git config --global init.defaultBranch main
+
+
+
+
+
+
+
Default Git branch naming
+
+
Source file changes are associated with a “branch.” For new learners
+in this lesson, it’s enough to know that branches exist, and this lesson
+uses one branch.
+By default, Git will create a branch called master when you
+create a new repository with git init (as explained in the
+next Episode). This term evokes the racist practice of human slavery and
+the software development
+community has moved to adopt more inclusive language.
+
In 2020, most Git code hosting services transitioned to using
+main as the default branch. As an example, any new
+repository that is opened in GitHub and GitLab default to
+main. However, Git has not yet made the same change. As a
+result, local repositories must be manually configured have the same
+main branch name as most cloud services.
+
For versions of Git prior to 2.28, the change can be made on an
+individual repository level. The command for this is in the next
+episode. Note that if this value is unset in your local Git
+configuration, the init.defaultBranch value defaults to
+master.
+
+
+
+
The five commands we just ran above only need to be run once: the
+flag --global tells Git to use the settings for every
+project, in your user account, on this computer.
+
Let’s review those settings and test our core.editor
+right away:
+
+
BASH
+
+
$ git config --global--edit
+
+
Let’s close the file without making any additional changes. Remember,
+since typos in the config file will cause issues, it’s safer to view the
+configuration with:
+
+
BASH
+
+
$ git config --list
+
+
And if necessary, change your configuration using the same commands
+to choose another editor or update your email address. This can be done
+as many times as you want.
+
+
+
+
+
+
Proxy
+
+
In some networks you need to use a proxy. If this is
+the case, you may also need to tell Git about the proxy:
Always remember that if you forget the subcommands or options of a
+git command, you can access the relevant list of options
+typing git <command> -h or access the corresponding
+Git manual by typing git <command> --help, e.g.:
+
+
BASH
+
+
$ git config -h
+$ git config --help
+
+
While viewing the manual, remember the : is a prompt
+waiting for commands and you can press Q to exit the
+manual.
+
More generally, you can get the list of available git
+commands and further resources of the Git manual typing:
+
+
BASH
+
+
$ git help
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
Use git config with the --global option to
+configure a user name, email address, editor, and other preferences once
+per machine.
We will help Alfredo with his new project, create a repository with
+all his recipes.
+
First, let’s create a new directory in the Desktop
+folder for our work and then change the current working directory to the
+newly created one:
+
+
BASH
+
+
$ cd ~/Desktop
+$ mkdir recipes
+$ cd recipes
+
+
Then we tell Git to make recipes a repository -- a place where Git can
+store versions of our files:
+
+
BASH
+
+
$ git init
+
+
It is important to note that git init will create a
+repository that can include subdirectories and their files—there is no
+need to create separate repositories nested within the
+recipes repository, whether subdirectories are present from
+the beginning or added later. Also, note that the creation of the
+recipes directory and its initialization as a repository
+are completely separate processes.
+
If we use ls to show the directory’s contents, it
+appears that nothing has changed:
+
+
BASH
+
+
$ ls
+
+
But if we add the -a flag to show everything, we can see
+that Git has created a hidden directory within recipes
+called .git:
+
+
BASH
+
+
$ ls -a
+
+
+
OUTPUT
+
+
. .. .git
+
+
Git uses this special subdirectory to store all the information about
+the project, including the tracked files and sub-directories located
+within the project’s directory. If we ever delete the .git
+subdirectory, we will lose the project’s history.
+
We can now start using one of the most important git commands, which
+is particularly helpful to beginners. git status tells us
+the status of our project, and better, a list of changes in the project
+and options on what to do with those changes. We can use it as often as
+we want, whenever we want to understand what is going on.
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+
+No commits yet
+
+nothing to commit (create/copy files and use "git add" to track)
+
+
If you are using a different version of git, the exact
+wording of the output might be slightly different.
+
+
+
+
+
+
Places to Create Git Repositories
+
+
Along with tracking information about recipes (the project we have
+already created), Alfredo would also like to track information about
+desserts specifically. Alfredo creates a desserts project
+inside his recipes project with the following sequence of
+commands:
+
+
BASH
+
+
$ cd ~/Desktop # return to Desktop directory
+$ cd recipes # go into recipes directory, which is already a Git repository
+$ ls -a# ensure the .git subdirectory is still present in the recipes directory
+$ mkdir desserts # make a sub-directory recipes/desserts
+$ cd desserts # go into desserts subdirectory
+$ git init # make the desserts subdirectory a Git repository
+$ ls -a# ensure the .git subdirectory is present indicating we have created a new Git repository
+
+
Is the git init command, run inside the
+desserts subdirectory, required for tracking files stored
+in the desserts subdirectory?
+
+
+
+
+
+
+
+
+
No. Alfredo does not need to make the desserts
+subdirectory a Git repository because the recipes
+repository will track all files, sub-directories, and subdirectory files
+under the recipes directory. Thus, in order to track all
+information about desserts, Alfredo only needed to add the
+desserts subdirectory to the recipes
+directory.
+
Additionally, Git repositories can interfere with each other if they
+are “nested”: the outer repository will try to version-control the inner
+repository. Therefore, it’s best to create each new Git repository in a
+separate directory. To be sure that there is no conflicting repository
+in the directory, check the output of git status. If it
+looks like the following, you are good to go to create a new repository
+as shown above:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
fatal: Not a git repository (or any of the parent directories): .git
+
+
+
+
+
+
+
+
+
+
+
Correcting git init Mistakes
+
+
Jimmy explains to Alfredo how a nested repository is redundant and
+may cause confusion down the road. Alfredo would like to go back to a
+single git repository. How can Alfredo undo his last
+git init in the desserts subdirectory?
+
+
+
+
+
+
+
+
+
+
Background
+
+
Removing files from a Git repository needs to be done with caution.
+But we have not learned yet how to tell Git to track a particular file;
+we will learn this in the next episode. Files that are not tracked by
+Git can easily be removed like any other “ordinary” files with
+
+
BASH
+
+
$ rm filename
+
+
Similarly a directory can be removed using
+rm -r dirname. If the files or folder being removed in this
+fashion are tracked by Git, then their removal becomes another change
+that we will need to track, as we will see in the next episode.
+
+
+
Solution
+
+
Git keeps all of its files in the .git directory. To
+recover from this little mistake, Alfredo can remove the
+.git folder in the desserts subdirectory by running the
+following command from inside the recipes directory:
+
+
BASH
+
+
$ rm -rf desserts/.git
+
+
But be careful! Running this command in the wrong directory will
+remove the entire Git history of a project you might want to keep. In
+general, deleting files and directories using rm from the
+command line cannot be reversed. Therefore, always check your current
+directory using the command pwd.
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
+git init initializes a repository.
+
Git stores all of its repository data in the .git
+directory.
How do I check the status of my version control repository?
+
How do I record notes about what changes I made and why?
+
+
+
+
+
+
+
+
Objectives
+
+
Go through the modify-add-commit cycle for one or more files.
+
Explain where information is stored at each stage of that
+cycle.
+
Distinguish between descriptive and non-descriptive commit
+messages.
+
+
+
+
+
+
+
First let’s make sure we’re still in the right directory. You should
+be in the recipes directory.
+
+
BASH
+
+
$ cd ~/Desktop/recipes
+
+
Let’s create a file called guacamole.md that contains
+the basic structure to have a recipe. We’ll use nano to
+edit the file; you can use whatever editor you like. In particular, this
+does not have to be the core.editor you set globally
+earlier. But remember, the steps to create create or edit a new file
+will depend on the editor you choose (it might not be nano). For a
+refresher on text editors, check out “Which
+Editor?” in The Unix Shell
+lesson.
+
+
BASH
+
+
$ nano guacamole.md
+
+
Type the text below into the guacamole.md file:
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+## Instructions
+
+
Save the file and exit your editor. Next, let’s verify that the file
+was properly created by running the list command (ls):
+
+
BASH
+
+
$ ls
+
+
+
OUTPUT
+
+
guacamole.md
+
+
guacamole.md contains three lines, which we can see by
+running:
+
+
BASH
+
+
$ cat guacamole.md
+
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+## Instructions
+
+
If we check the status of our project again, Git tells us that it’s
+noticed the new file:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+
+No commits yet
+
+Untracked files:
+ (use "git add <file>..." to include in what will be committed)
+
+ guacamole.md
+
+nothing added to commit but untracked files present (use "git add" to track)
+
+
The “untracked files” message means that there’s a file in the
+directory that Git isn’t keeping track of. We can tell Git to track a
+file using git add:
+
+
BASH
+
+
$ git add guacamole.md
+
+
and then check that the right thing happened:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+
+No commits yet
+
+Changes to be committed:
+ (use "git rm --cached <file>..." to unstage)
+
+ new file: guacamole.md
+
+
+
Git now knows that it’s supposed to keep track of
+guacamole.md, but it hasn’t recorded these changes as a
+commit yet. To get it to do that, we need to run one more command:
+
+
BASH
+
+
$ git commit -m"Create a template for recipe"
+
+
+
OUTPUT
+
+
[main (root-commit) f22b25e] Create a template for recipe
+ 1 file changed, 1 insertion(+)
+ create mode 100644 guacamole.md
+
+
When we run git commit, Git takes everything we have
+told it to save by using git add and stores a copy
+permanently inside the special .git directory. This
+permanent copy is called a commit
+(or revision) and its short
+identifier is f22b25e. Your commit may have another
+identifier.
+
We use the -m flag (for “message”) to record a short,
+descriptive, and specific comment that will help us remember later on
+what we did and why. If we just run git commit without the
+-m option, Git will launch nano (or whatever
+other editor we configured as core.editor) so that we can
+write a longer message.
+
Good commit
+messages start with a brief (<50 characters) statement about the
+changes made in the commit. Generally, the message should complete the
+sentence “If applied, this commit will” . If you
+want to go into more detail, add a blank line between the summary line
+and your additional notes. Use this additional space to explain why you
+made changes and/or what their impact will be.
+
If we run git status now:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+nothing to commit, working tree clean
+
+
it tells us everything is up to date. If we want to know what we’ve
+done recently, we can ask Git to show us the project’s history using
+git log:
+
+
BASH
+
+
$ git log
+
+
+
OUTPUT
+
+
commit f22b25e3233b4645dabd0d81e651fe074bd8e73b
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 09:51:46 2013 -0400
+
+ Create a template for recipe
+
+
git log lists all commits made to a repository in
+reverse chronological order. The listing for each commit includes the
+commit’s full identifier (which starts with the same characters as the
+short identifier printed by the git commit command
+earlier), the commit’s author, when it was created, and the log message
+Git was given when the commit was created.
+
+
+
+
+
+
Where Are My Changes?
+
+
If we run ls at this point, we will still see just one
+file called guacamole.md. That’s because Git saves
+information about files’ history in the special .git
+directory mentioned earlier so that our filesystem doesn’t become
+cluttered (and so that we can’t accidentally edit or delete an old
+version).
+
+
+
+
Now suppose Alfredo adds more information to the file. (Again, we’ll
+edit with nano and then cat the file to show
+its contents; you may use a different editor, and don’t need to
+cat.)
When we run git status now, it tells us that a file it
+already knows about has been modified:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
The last line is the key phrase: “no changes added to commit”. We
+have changed this file, but we haven’t told Git we will want to save
+those changes (which we do with git add) nor have we saved
+them (which we do with git commit). So let’s do that now.
+It is good practice to always review our changes before saving them. We
+do this using git diff. This shows us the differences
+between the current state of the file and the most recently saved
+version:
The output is cryptic because it is actually a series of commands for
+tools like editors and patch telling them how to
+reconstruct one file given the other. If we break it down into
+pieces:
+
+
The first line tells us that Git is producing output similar to the
+Unix diff command comparing the old and new versions of the
+file.
+
The second line tells exactly which versions of the file Git is
+comparing; df0654a and 315bf3a are unique
+computer-generated labels for those versions.
+
The third and fourth lines once again show the name of the file
+being changed.
+
The remaining lines are the most interesting, they show us the
+actual differences and the lines on which they occur. In particular, the
++ marker in the first column shows where we added a
+line.
+
+
After reviewing our change, it’s time to commit it:
+
+
BASH
+
+
$ git commit -m"Add basic guacamole's ingredients"
+$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
Whoops: Git won’t commit because we didn’t use git add
+first. Let’s fix that:
Git insists that we add files to the set we want to commit before
+actually committing anything. This allows us to commit our changes in
+stages and capture changes in logical portions rather than only large
+batches. For example, suppose we’re adding a few citations to relevant
+research to our thesis. We might want to commit those additions, and the
+corresponding bibliography entries, but not commit some of our
+work drafting the conclusion (which we haven’t finished yet).
+
To allow for this, Git has a special staging area where it
+keeps track of things that have been added to the current changeset but not yet committed.
+
+
+
+
+
+
Staging Area
+
+
If you think of Git as taking snapshots of changes over the life of a
+project, git add specifies what will go in a
+snapshot (putting things in the staging area), and
+git commit then actually takes the snapshot, and
+makes a permanent record of it (as a commit). If you don’t have anything
+staged when you type git commit, Git will prompt you to use
+git commit -a or git commit --all, which is
+kind of like gathering everyone to take a group photo! However,
+it’s almost always better to explicitly add things to the staging area,
+because you might commit changes you forgot you made. (Going back to the
+group photo simile, you might get an extra with incomplete makeup
+walking on the stage for the picture because you used -a!)
+Try to stage things manually, or you might find yourself searching for
+“git undo commit” more than you would like!
+
+
+
+
Let’s watch as our changes to a file move from our editor to the
+staging area and into long-term storage. First, we’ll improve our recipe
+by changing ‘lemon’ to ‘lime’:
So far, so good: we’ve replaced one line (shown with a -
+in the first column) with a new line (shown with a + in the
+first column). Now let’s put that change in the staging area and see
+what git diff reports:
+
+
BASH
+
+
$ git add guacamole.md
+$ git diff
+
+
There is no output: as far as Git can tell, there’s no difference
+between what it’s been asked to save permanently and what’s currently in
+the directory. However, if we do this:
it shows us the difference between the last committed change and
+what’s in the staging area. Let’s save our changes:
+
+
BASH
+
+
$ git commit -m"Modify guacamole to the traditional recipe"
+
+
+
OUTPUT
+
+
[main 005937f] Modify guacamole to the traditional recipe
+ 1 file changed, 1 insertion(+)
+
+
check our status:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+nothing to commit, working tree clean
+
+
and look at the history of what we’ve done so far:
+
+
BASH
+
+
$ git log
+
+
+
OUTPUT
+
+
commit 005937fbe2a98fb83f0ade869025dc2636b4dad5 (HEAD -> main)
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 10:14:07 2013 -0400
+
+ Modify guacamole to the traditional recipe
+
+commit 34961b159c27df3b475cfe4415d94a6d1fcd064d
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 10:07:21 2013 -0400
+
+ Add basic guacamole's ingredients
+
+commit f22b25e3233b4645dabd0d81e651fe074bd8e73b
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 09:51:46 2013 -0400
+
+ Create a template for recipe
+
+
+
+
+
+
+
Word-based diffing
+
+
Sometimes, e.g. in the case of the text documents a line-wise diff is
+too coarse. That is where the --color-words option of
+git diff comes in very useful as it highlights the changed
+words using colors.
+
+
+
+
+
+
+
+
+
Paging the Log
+
+
When the output of git log is too long to fit in your
+screen, git uses a program to split it into pages of the
+size of your screen. When this “pager” is called, you will notice that
+the last line in your screen is a :, instead of your usual
+prompt.
+
+
To get out of the pager, press Q.
+
To move to the next page, press Spacebar.
+
To search for some_word in all pages, press
+/ and type some_word. Navigate through matches
+pressing N.
+
+
+
+
+
+
+
+
+
+
Limit Log Size
+
+
To avoid having git log cover your entire terminal
+screen, you can limit the number of commits that Git lists by using
+-N, where N is the number of commits that you
+want to view. For example, if you only want information from the last
+commit you can use:
+
+
BASH
+
+
$ git log -1
+
+
+
OUTPUT
+
+
commit 005937fbe2a98fb83f0ade869025dc2636b4dad5 (HEAD -> main)
+Author: Alfredo Linguini <a.linguini@ratatouille.fr>
+Date: Thu Aug 22 10:14:07 2013 -0400
+
+ Modify guacamole to the traditional recipe
+
+
You can also reduce the quantity of information using the
+--oneline option:
+
+
BASH
+
+
$ git log --oneline
+
+
+
OUTPUT
+
+
005937f (HEAD -> main) Modify guacamole to the traditional recipe
+34961b1 Add basic guacamole's ingredients
+f22b25e Create a template for recipe
+
+
You can also combine the --oneline option with others.
+One useful combination adds --graph to display the commit
+history as a text-based graph and to indicate which commits are
+associated with the current HEAD, the current branch
+main, or other
+Git references:
+
+
BASH
+
+
$ git log --oneline--graph
+
+
+
OUTPUT
+
+
* 005937f (HEAD -> main) Modify guacamole to the traditional recipe
+* 34961b1 Add basic guacamole's ingredients
+* f22b25e Create a template for recipe
+
+
+
+
+
+
+
+
+
+
Directories
+
+
Two important facts you should know about directories in Git.
+
+
Git does not track directories on their own, only files within them.
+Try it for yourself:
+
+
+
BASH
+
+
$ mkdir cakes
+$ git status
+$ git add cakes
+$ git status
+
+
Note, our newly created empty directory cakes does not
+appear in the list of untracked files even if we explicitly add it
+(viagit add) to our repository. This is the
+reason why you will sometimes see .gitkeep files in
+otherwise empty directories. Unlike .gitignore, these files
+are not special and their sole purpose is to populate a directory so
+that Git adds it to the repository. In fact, you can name such files
+anything you like.
+
+
If you create a directory in your Git repository and populate it
+with files, you can add all files in the directory at once by:
+
+
+
BASH
+
+
git add <directory-with-files>
+
+
Try it for yourself:
+
+
BASH
+
+
$ touch cakes/brownie cakes/lemon_drizzle
+$ git status
+$ git add cakes
+$ git status
+
+
Before moving on, we will commit these changes.
+
+
BASH
+
+
$ git commit -m"Add some initial cakes"
+
+
+
+
+
To recap, when we want to add changes to our repository, 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):
+
+
+
+
+
+
Choosing a Commit Message
+
+
Which of the following commit messages would be most appropriate for
+the last commit made to guacamole.md?
+
+
“Changes”
+
“Changed lemon for lime”
+
“Guacamole modified to the traditional recipe”
+
+
+
+
+
+
+
+
+
+
Answer 1 is not descriptive enough, and the purpose of the commit is
+unclear; and answer 2 is redundant to using “git diff” to see what
+changed in this commit; but answer 3 is good: short, descriptive, and
+imperative.
+
+
+
+
+
+
+
+
+
+
Committing Changes to Git
+
+
Which command(s) below would save the changes of
+myfile.txt to my local Git repository?
Modify the file as described (modify one line, add a fourth line). To
+display the differences between its updated state and its original
+state, use git diff:
+
+
BASH
+
+
$ git diff me.txt
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
+git status shows the status of a repository.
+
Files can be stored in a project’s working directory (which users
+see), the staging area (where the next commit is being built up) and the
+local repository (where commits are permanently recorded).
+
+git add puts files in the staging area.
+
+git commit saves the staged content as a new commit in
+the local repository.
+
Write a commit message that accurately describes your changes.
Explain what the HEAD of a repository is and how to use it.
+
Identify and use Git commit numbers.
+
Compare various versions of tracked files.
+
Restore old versions of files.
+
+
+
+
+
+
+
As we saw in the previous episode, we can refer to commits by their
+identifiers. You can refer to the most recent commit of the
+working directory by using the identifier HEAD.
+
We’ve been adding small changes at a time to
+guacamole.md, so it’s easy to track our progress by
+looking, so let’s do that using our HEADs. Before we start,
+let’s make a change to guacamole.md, adding yet another
+line.
which is the same as what you would get if you leave out
+HEAD (try it). The real goodness in all this is when you
+can refer to previous commits. We do that by adding ~1
+(where “~” is “tilde”, pronounced [til-duh])
+to refer to the commit one before HEAD.
+
+
BASH
+
+
$ git diff HEAD~1 guacamole.md
+
+
If we want to see the differences between older commits we can use
+git diff again, but with the notation HEAD~1,
+HEAD~2, and so on, to refer to them:
We could also use git show which shows us what changes
+we made at an older commit as well as the commit message, rather than
+the differences between a commit and our working directory that
+we see by using git diff.
In this way, we can build up a chain of commits. The most recent end
+of the chain is referred to as HEAD; we can refer to
+previous commits using the ~ notation, so
+HEAD~1 means “the previous commit”, while
+HEAD~123 goes back 123 commits from where we are now.
+
We can also refer to commits using those long strings of digits and
+letters that both git log and git show
+display. These are unique IDs for the changes, and “unique” really does
+mean unique: every change to any set of files on any computer has a
+unique 40-character identifier. Our first commit was given the ID
+f22b25e3233b4645dabd0d81e651fe074bd8e73b, so let’s try
+this:
That’s the right answer, but typing out random 40-character strings
+is annoying, so Git lets us use just the first few characters (typically
+seven for normal size projects):
All right! So we can save changes to files and see what we’ve
+changed. Now, how can we restore older versions of things? Let’s suppose
+we change our mind about the last update to guacamole.md
+(the “ill-considered change”).
+
git status now tells us that the file has been changed,
+but those changes haven’t been staged:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
We can put things back the way they were by using
+git restore:
As you might guess from its name, git restore restores
+an old version of a file. By default, it recovers the version of the
+file recorded in HEAD, which is the last saved commit. If
+we want to go back even further, we can use a commit identifier instead,
+using -s option:
+
+
BASH
+
+
$ git restore -s f22b25e guacamole.md
+
+
+
BASH
+
+
$ cat guacamole.md
+
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+## Instructions
+
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
+
Notice that the changes are not currently in the staging area, and
+have not been committed. If we wished, we can put things back the way
+they were at the last commit by using git restore to
+overwrite the working copy with the last committed version:
It’s important to remember that we must use the commit number that
+identifies the state of the repository before the change we’re
+trying to undo. A common mistake is to use the number of 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. We use the
+. to mean all files:
+
So, to put it all together, here’s how Git works in cartoon form:
The fact that files can be reverted one by one tends to change the
+way people organize their work. If everything is in one large document,
+it’s hard (but not impossible) to undo changes to the introduction
+without also undoing changes made later to the conclusion. If the
+introduction and conclusion are stored in separate files, on the other
+hand, moving backward and forward in time becomes much easier.
+
+
+
+
+
+
Recovering Older Versions of a File
+
+
Jennifer has made changes to the Python script that she has been
+working on for weeks, and the modifications she made this morning
+“broke” the script and it no longer runs. She has spent ~ 1hr trying to
+fix it, with no luck…
+
Luckily, she has been keeping track of her project’s versions using
+Git! Which commands below will let her recover the last committed
+version of her Python script called data_cruncher.py?
+
+
$ git restore
+
$ git restore data_cruncher.py
+
$ git restore -s HEAD~1 data_cruncher.py
+
$ git restore -s <unique ID of last commit> data_cruncher.py
+
Both 2 and 4
+
+
+
+
+
+
+
+
+
+
The answer is (5)-Both 2 and 4.
+
The restore command restores files from the repository,
+overwriting the files in your working directory. Answers 2 and 4 both
+restore the latest version in the repository of the
+file data_cruncher.py. Answer 2 uses HEAD to
+indicate the latest, whereas answer 4 uses the unique ID of the
+last commit, which is what HEAD means.
+
Answer 3 gets the version of data_cruncher.py from the
+commit beforeHEAD, which is NOT what we
+wanted.
+
Answer 1 results in an error. You need to specify a file to restore.
+If you want to restore all files you should use
+git restore .
+
+
+
+
+
+
+
+
+
+
Reverting a Commit
+
+
Jennifer is collaborating with colleagues on her Python script. She
+realizes her last commit to the project’s repository contained an error,
+and wants to undo it. Jennifer wants to undo correctly so everyone in
+the project’s repository gets the correct change. The command
+git revert [erroneous commit ID] will create a new commit
+that reverses the erroneous commit.
+
The command git revert is different from
+git restore -s [commit ID] . because
+git restore returns the files not yet committed within the
+local repository to a previous state, whereas git revert
+reverses changes committed to the local and project repositories.
+
Below are the right steps and explanations for Jennifer to use
+git revert, what is the missing command?
+
+
________ # Look at the git history of the project to find the commit ID
+
Copy the ID (the first few characters of the ID,
+e.g. 0b1d055).
+
git revert [commit ID]
+
Type in the new commit message.
+
Save and close.
+
+
+
+
+
+
+
+
+
+
The command git log lists project history with commit
+IDs.
+
The command git show HEAD shows changes made at the
+latest commit, and lists the commit ID; however, Jennifer should
+double-check it is the correct commit, and no one else has committed
+changes to the repository.
+
+
+
+
+
+
+
+
+
+
Understanding Workflow and History
+
+
What is the output of the last command in
+
+
BASH
+
+
$ cd recipes
+$ echo "I like tomatoes, therefore I like ketchup"> ketchup.md
+$ git add ketchup.md
+$ echo "ketchup enhances pasta dishes">> ketchup.md
+$ git commit -m"My opinions about the red sauce"
+$ git restore ketchup.md
+$ cat ketchup.md # this will print the content of ketchup.md on screen
+
+
+
+
OUTPUT
+
+
ketchup enhances pasta dishes
+
+
+
OUTPUT
+
+
I like tomatoes, therefore I like ketchup
+
+
+
OUTPUT
+
+
I like tomatoes, therefore I like ketchup
+ ketchup enhances pasta dishes
+
+
+
OUTPUT
+
+
Error because you have changed ketchup.md without committing the changes
+
+
+
+
+
+
+
+
+
+
+
The answer is 2.
+
The changes to the file from the second echo command are
+only applied to the working copy, The command
+git add ketchup.md places the current version of
+ketchup.md into the staging area. not the version in the
+staging area.
+
So, when git commit -m "My opinions about the red sauce"
+is executed, the version of ketchup.md committed to the
+repository is the one from the staging area and has only one line.
+
At this time, the working copy still has the second line (and
+
git status will show that the file is modified).
+However, git restore ketchup.md replaces the working copy
+with the most recently committed version of ketchup.md. So,
+cat ketchup.md will output
+
+
OUTPUT
+
+
I like tomatoes, therefore I like ketchup
+
+
+
+
+
+
+
+
+
+
+
Checking Understanding of
+git diff
+
+
+
Consider this command: git diff HEAD~9 guacamole.md.
+What do you predict this command will do if you execute it? What happens
+when you do execute it? Why?
+
Try another command, git diff [ID] guacamole.md, where
+[ID] is replaced with the unique identifier for your most recent commit.
+What do you think will happen, and what does happen?
+
+
+
+
+
+
+
+
+
Getting Rid of Staged Changes
+
+
git restore can be used to restore a previous commit
+when unstaged changes have been made, but will it also work for changes
+that have been staged but not committed? Make a change to
+guacamole.md, add that change using git add,
+then use git restore to see if you can remove your
+change.
+
+
+
+
+
+
+
+
+
After adding a change, git restore can not be used
+directly. Let’s look at the output of git status:
+
+
OUTPUT
+
+
On branch main
+Changes to be committed:
+ (use "git restore --staged <file>..." to unstage)
+ modified: guacamole.md
+
+
+
Note that if you don’t have the same output you may either have
+forgotten to change the file, or you have added it and
+committed it.
+
Using the command git restore guacamole.md now does not
+give an error, but it does not restore the file either. Git helpfully
+tells us that we need to use git restore --staged first to
+unstage the file:
+
+
BASH
+
+
$ git restore --staged guacamole.md
+
+
Now, git status gives us:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git git restore <file>..." to discard changes in working directory)
+ modified: guacamole.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+
This means we can now use git restore to restore the
+file to the previous commit:
+
+
BASH
+
+
$ git restore guacamole.md
+$ git status
+
+
+
OUTPUT
+
+
On branch main
+nothing to commit, working tree clean
+
+
+
+
+
+
+
+
+
+
+
Explore and Summarize Histories
+
+
Exploring history is an important part of Git, and often it is a
+challenge to find the right commit ID, especially if the commit is from
+several months ago.
+
Imagine the recipes project has more than 50 files. You
+would like to find a commit that modifies some specific text in
+guacamole.md. When you type git log, a very
+long list appeared. How can you narrow down the search?
+
Recall that the git diff command allows us to explore
+one specific file, e.g., git diff guacamole.md. We can
+apply a similar idea here.
+
+
BASH
+
+
$ git log guacamole.md
+
+
Unfortunately some of these commit messages are very ambiguous, e.g.,
+update files. How can you search through these files?
+
Both git diff and git log are very useful
+and they summarize a different part of the history for you. Is it
+possible to combine both? Let’s try the following:
+
+
BASH
+
+
$ git log --patch guacamole.md
+
+
You should get a long list of output, and you should be able to see
+both commit messages and the difference between each commit.
How can I tell Git to ignore files I don’t want to track?
+
+
+
+
+
+
+
+
Objectives
+
+
Configure Git to ignore specific files.
+
Explain why ignoring files can be useful.
+
+
+
+
+
+
+
What if we have files that we do not want Git to track for us, like
+backup files created by our editor or intermediate files created during
+data analysis? Let’s create a few dummy files:
On branch main
+Untracked files:
+ (use "git add <file>..." to include in what will be committed)
+
+ a.png
+ b.png
+ c.png
+ receipts/
+
+nothing added to commit but untracked files present (use "git add" to track)
+
+
Putting these files under version control would be a waste of disk
+space. What’s worse, having them all listed could distract us from
+changes that actually matter, so let’s tell Git to ignore them.
+
We do this by creating a file in the root directory of our project
+called .gitignore:
+
+
BASH
+
+
$ nano .gitignore
+$ cat .gitignore
+
+
+
OUTPUT
+
+
*.png
+receipts/
+
+
These patterns tell Git to ignore any file whose name ends in
+.png and everything in the receipts directory.
+(If any of these files were already being tracked, Git would continue to
+track them.)
+
Once we have created this file, the output of git status
+is much cleaner:
+
+
BASH
+
+
$ git status
+
+
+
OUTPUT
+
+
On branch main
+Untracked files:
+ (use "git add <file>..." to include in what will be committed)
+
+ .gitignore
+
+nothing added to commit but untracked files present (use "git add" to track)
+
+
The only thing Git notices now is the newly-created
+.gitignore file. You might think we wouldn’t want to track
+it, but everyone we’re sharing our repository with will probably want to
+ignore the same things that we’re ignoring. Let’s add and commit
+.gitignore:
+
+
BASH
+
+
$ git add .gitignore
+$ git commit -m"Ignore png files and the receipts folder."
+$ git status
+
+
+
OUTPUT
+
+
On branch main
+nothing to commit, working tree clean
+
+
As a bonus, using .gitignore helps us avoid accidentally
+adding files to the repository that we don’t want to track:
+
+
BASH
+
+
$ git add a.png
+
+
+
OUTPUT
+
+
The following paths are ignored by one of your .gitignore files:
+a.png
+Use -f if you really want to add them.
+
+
If we really want to override our ignore settings, we can use
+git add -f to force Git to add something. For example,
+git add -f a.csv. We can also always see the status of
+ignored files if we want:
+
+
BASH
+
+
$ git status --ignored
+
+
+
OUTPUT
+
+
On branch main
+Ignored files:
+ (use "git add -f <file>..." to include in what will be committed)
+
+ a.png
+ b.png
+ c.png
+ receipts/
+
+nothing to commit, working tree clean
+
+
+
+
+
+
+
Ignoring Nested Files
+
+
Given a directory structure that looks like:
+
+
BASH
+
+
receipts/data
+receipts/plots
+
+
How would you ignore only receipts/plots and not
+receipts/data?
+
+
+
+
+
+
+
+
+
If you only want to ignore the contents of
+receipts/plots, you can change your .gitignore
+to ignore only the /plots/ subfolder by adding the
+following line to your .gitignore:
+
+
OUTPUT
+
+
receipts/plots/
+
+
This line will ensure only the contents of
+receipts/plots is ignored, and not the contents of
+receipts/data.
+
As with most programming issues, there are a few alternative ways
+that one may ensure this ignore rule is followed. The “Ignoring Nested
+Files: Variation” exercise has a slightly different directory structure
+that presents an alternative solution. Further, the discussion page has
+more detail on ignore rules.
+
+
+
+
+
+
+
+
+
+
Including Specific Files
+
+
How would you ignore all .png files in your root
+directory except for final.png? Hint: Find out what
+! (the exclamation point operator) does
+
+
+
+
+
+
+
+
+
You would add the following two lines to your .gitignore:
+
+
OUTPUT
+
+
*.png # ignore all png files
+!final.png # except final.png
+
+
The exclamation point operator will include a previously excluded
+entry.
+
Note also that because you’ve previously committed .png
+files in this lesson they will not be ignored with this new rule. Only
+future additions of .png files added to the root directory
+will be ignored.
+
+
+
+
+
+
+
+
+
+
Ignoring Nested Files: Variation
+
+
Given a directory structure that looks similar to the earlier Nested
+Files exercise, but with a slightly different directory structure:
How would you ignore all of the contents in the receipts folder, but
+not receipts/data?
+
Hint: think a bit about how you created an exception with the
+! operator before.
+
+
+
+
+
+
+
+
+
If you want to ignore the contents of receipts/ but not
+those of receipts/data/, you can change your
+.gitignore to ignore the contents of receipts folder, but
+create an exception for the contents of the receipts/data
+subfolder. Your .gitignore would look like this:
+
+
OUTPUT
+
+
receipts/* # ignore everything in receipts folder
+!receipts/data/ # do not ignore receipts/data/ contents
+
+
+
+
+
+
+
+
+
+
+
Ignoring all data Files in a Directory
+
+
Assuming you have an empty .gitignore file, and given a directory
+structure that looks like:
What’s the shortest .gitignore rule you could write to
+ignore all .dat files in
+result/data/market_position/gps? Do not ignore the
+info.txt.
+
+
+
+
+
+
+
+
+
Appending receipts/data/market_position/gps/*.dat will
+match every file in receipts/data/market_position/gps that
+ends with .dat. The file
+receipts/data/market_position/gps/info.txt will not be
+ignored.
+
+
+
+
+
+
+
+
+
+
Ignoring all data Files in the repository
+
+
Let us assume you have many .csv files in different
+subdirectories of your repository. For example, you might have:
How do you ignore all the .csv files, without explicitly
+listing the names of the corresponding folders?
+
+
+
+
+
+
+
+
+
In the .gitignore file, write:
+
+
OUTPUT
+
+
**/*.csv
+
+
This will ignore all the .csv files, regardless of their
+position in the directory tree. You can still include some specific
+exception with the exclamation point operator.
+
+
+
+
+
+
+
+
+
+
The Order of Rules
+
+
Given a .gitignore file with the following contents:
+
+
BASH
+
+
*.csv
+!*.csv
+
+
What will be the result?
+
+
+
+
+
+
+
+
+
The ! modifier will negate an entry from a previously
+defined ignore pattern. Because the !*.csv entry negates
+all of the previous .csv files in the
+.gitignore, none of them will be ignored, and all
+.csv files will be tracked.
+
+
+
+
+
+
+
+
+
+
Log Files
+
+
You wrote a script that creates many intermediate log-files of the
+form log_01, log_02, log_03, etc.
+You want to keep them but you do not want to track them through
+git.
+
+
Write one.gitignore entry that
+excludes files of the form log_01, log_02,
+etc.
+
Test your “ignore pattern” by creating some dummy files of the
+form log_01, etc.
+
You find that the file log_01 is very important
+after all, add it to the tracked files without changing the
+.gitignore again.
+
Discuss with your neighbor what other types of files could reside
+in your directory that you do not want to track and thus would exclude
+via .gitignore.
+
+
+
+
+
+
+
+
+
+
+
append either log_* or log* as a new entry
+in your .gitignore
+
track log_01 using git add -f log_01
+
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
The .gitignore file tells Git what files to
+ignore.
Explain what remote repositories are and why they are useful.
+
Push to or pull from a remote repository.
+
+
+
+
+
+
+
Version control really comes into its own when we begin to
+collaborate with other people. We already have most of the machinery we
+need to do this; the only thing missing is to copy changes from one
+repository to another.
+
Systems like Git allow us to move work between any two repositories.
+In practice, though, it’s easiest to use one copy as a central hub, and
+to keep it on the web rather than on someone’s laptop. Most programmers
+use hosting services like GitHub, Bitbucket or GitLab to hold those main copies; we’ll
+explore the pros and cons of this in a later
+episode.
+
Let’s start by sharing the changes we’ve made to our current project
+with the world. To this end we are going to create a remote
+repository that will be linked to our local repository.
+
1. Create a remote repository
+
+
+
Log in to GitHub, then click on the
+icon in the top right corner to create a new repository called
+recipes:
+
Name your repository “recipes” and then click “Create
+Repository”.
+
Note: Since this repository will be connected to a local repository,
+it needs to be empty. Leave “Initialize this repository with a README”
+unchecked, and keep “None” as options for both “Add .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.
+
As soon as the repository is created, GitHub displays a page with a
+URL and some information on how to configure your local repository:
+
This effectively does the following on GitHub’s servers:
+
+
BASH
+
+
$ mkdir recipes
+$ cd recipes
+$ git init
+
+
If you remember back to the earlier episode where we added and committed our
+earlier work on guacamole.md, we had a diagram of the local
+repository which looked like this:
+
Now that we have two repositories, we need a diagram like this:
+
Note that our local repository still contains our earlier work on
+guacamole.md, but the remote repository on GitHub appears
+empty as it doesn’t contain any files yet.
+
2. Connect local to remote repository
+
+
+
Now we connect the two repositories. We do this by making the GitHub
+repository a remote for the local
+repository. The home page of the repository on GitHub includes the URL
+string we need to identify it:
+
Click on the ‘SSH’ link to change the protocol from HTTPS to SSH.
+
+
+
+
+
+
HTTPS vs. SSH
+
+
We use SSH here because, while it requires some additional
+configuration, it is a security protocol widely used by many
+applications. The steps below describe SSH at a minimum level for
+GitHub.
+
+
+
+
Copy that URL from the browser, go into the local
+recipes repository, and run this command:
Make sure to use the URL for your repository rather than Alfredo’s:
+the only difference should be your username instead of
+alflin.
+
origin is a local name used to refer to the remote
+repository. It could be called anything, but origin is a
+convention that is often used by default in git and GitHub, so it’s
+helpful to stick with this unless there’s a reason not to.
+
We can check that the command has worked by running
+git remote -v:
We’ll discuss remotes in more detail in the next episode, while
+talking about how they might be used for collaboration.
+
3. SSH Background and Setup
+
+
+
Before Alfredo can connect to a remote repository, he needs to set up
+a way for his computer to authenticate with GitHub so it knows it’s him
+trying to connect to his remote repository.
+
We are going to set up the method that is commonly used by many
+different services to authenticate access on the command line. This
+method is called Secure Shell Protocol (SSH). SSH is a cryptographic
+network protocol that allows secure communication between computers
+using an otherwise insecure network.
+
SSH uses what is called a key pair. This is two keys that work
+together to validate access. One key is publicly known and called the
+public key, and the other key called the private key is kept private.
+Very descriptive names.
+
You can think of the public key as a padlock, and only you have the
+key (the private key) to open it. You use the public key where you want
+a secure method of communication, such as your GitHub account. You give
+this padlock, or public key, to GitHub and say “lock the communications
+to my account with this so that only computers that have my private key
+can unlock communications and send git commands as my GitHub
+account.”
+
What we will do now is the minimum required to set up the SSH keys
+and add the public key to a GitHub account.
+
+
+
+
+
+
Advanced SSH
+
+
A supplemental episode in this lesson discusses SSH and key pairs in
+more depth and detail.
+
+
+
+
The first thing we are going to do is check if this has already been
+done on the computer you’re on. Because generally speaking, this setup
+only needs to happen once and then you can forget about it.
+
+
+
+
+
+
Keeping your keys secure
+
+
You shouldn’t really forget about your SSH keys, since they keep your
+account secure. It’s good practice to audit your secure shell keys every
+so often. Especially if you are using multiple computers to access your
+account.
+
+
+
+
We will run the list command to check what key pairs already exist on
+your computer.
+
+
BASH
+
+
ls-al ~/.ssh
+
+
Your output is going to look a little different depending on whether
+or not SSH has ever been set up on the computer you are using.
+
Alfredo has not set up SSH on his computer, so his output is
+
+
OUTPUT
+
+
ls: cannot access '/c/Users/Alfredo/.ssh': No such file or directory
+
+
If SSH has been set up on the computer you’re using, the public and
+private key pairs will be listed. The file names are either
+id_ed25519/id_ed25519.pub or
+id_rsa/id_rsa.pub depending on how the key
+pairs were set up. Since they don’t exist on Alfredo’s computer, he uses
+this command to create them.
+
+
3.1 Create an SSH key pair
+
+
To create an SSH key pair Alfredo uses this command, where the
+-t option specifies which type of algorithm to use and
+-C attaches a comment to the key (here, Alfredo’s
+email):
If you are using a legacy system that doesn’t support the Ed25519
+algorithm, use:
+$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
+
+
OUTPUT
+
+
Generating public/private ed25519 key pair.
+Enter file in which to save the key (/c/Users/Alfredo/.ssh/id_ed25519):
+
+
We want to use the default file, so just press Enter.
+
+
OUTPUT
+
+
Created directory '/c/Users/Alfredo/.ssh'.
+Enter passphrase (empty for no passphrase):
+
+
Now, it is prompting Alfredo for a passphrase. Since he is using his
+kitchen’s laptop that other people sometimes have access to, he wants to
+create a passphrase. Be sure to use something memorable or save your
+passphrase somewhere, as there is no “reset my password” option. Note
+that, when typing a passphrase on a terminal, there won’t be any visual
+feedback of your typing. This is normal: your passphrase will be
+recorded even if you see nothing changing on your screen.
+
+
OUTPUT
+
+
Enter same passphrase again:
+
+
After entering the same passphrase a second time, we receive the
+confirmation
+
+
OUTPUT
+
+
Your identification has been saved in /c/Users/Alfredo/.ssh/id_ed25519
+Your public key has been saved in /c/Users/Alfredo/.ssh/id_ed25519.pub
+The key fingerprint is:
+SHA256:SMSPIStNyA00KPxuYu94KpZgRAYjgt9g4BA4kFy3g1o a.linguini@ratatouille.fr
+The key's randomart image is:
++--[ED25519 256]--+
+|^B== o. |
+|%*=.*.+ |
+|+=.E =.+ |
+| .=.+.o.. |
+|.... . S |
+|.+ o |
+|+ = |
+|.o.o |
+|oo+. |
++----[SHA256]-----+
+
+
The “identification” is actually the private key. You should never
+share it. The public key is appropriately named. The “key fingerprint”
+is a shorter version of a public key.
+
Now that we have generated the SSH keys, we will find the SSH files
+when we check.
Now we have a SSH key pair and we can run this command to check if
+GitHub can read our authentication.
+
+
BASH
+
+
ssh-T git@github.com
+
+
+
OUTPUT
+
+
The authenticity of host 'github.com (192.30.255.112)' can't be established.
+RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
+This key is not known by any other names
+Are you sure you want to continue connecting (yes/no/[fingerprint])? y
+Please type 'yes', 'no' or the fingerprint: yes
+Warning: Permanently added 'github.com' (RSA) to the list of known hosts.
+git@github.com: Permission denied (publickey).
+
+
Right, we forgot that we need to give GitHub our public key!
+
First, we need to copy the public key. Be sure to include the
+.pub at the end, otherwise you’re looking at the private
+key.
Now, going to GitHub.com, click on your profile icon in the top right
+corner to get the drop-down menu. Click “Settings”, then on the settings
+page, click “SSH and GPG keys”, on the left side “Access” menu. Click
+the “New SSH key” button on the right side. Now, you can add the title
+(Alfredo uses the title “Alfredo’s Kitchen Laptop” so he can remember
+where the original key pair files are located), paste your SSH key into
+the field, and click the “Add SSH key” to complete the setup.
+
Now that we’ve set that up, let’s check our authentication again from
+the command line.
+
+
BASH
+
+
$ ssh -T git@github.com
+
+
+
OUTPUT
+
+
Hi Alfredo! You've successfully authenticated, but GitHub does not provide shell access.
+
+
Good! This output confirms that the SSH key works as intended. We are
+now ready to push our work to the remote repository.
+
+
4. Push local changes to a remote
+
+
+
Now that authentication is setup, we can return to the remote. This
+command will push the changes from our local repository to the
+repository on GitHub:
+
+
BASH
+
+
$ git push origin main
+
+
Since Alfredo set up a passphrase, it will prompt him for it. If you
+completed advanced settings for your authentication, it will not prompt
+for a passphrase.
If the network you are connected to uses a proxy, there is a chance
+that your last command failed with “Could not resolve hostname” as the
+error message. To solve this issue, you need to tell Git about the
+proxy:
If your operating system has a password manager configured,
+git push will try to use it when it needs your username and
+password. For example, this is the default behavior for Git Bash on
+Windows. If you want to type your username and password at the terminal
+instead of using a password manager, type:
+
+
BASH
+
+
$ unset SSH_ASKPASS
+
+
in the terminal, before you run git push. Despite the
+name, Git
+uses SSH_ASKPASS for all credential entry, so you may
+want to unset SSH_ASKPASS whether you are using Git via SSH
+or https.
+
You may also want to add unset SSH_ASKPASS at the end of
+your ~/.bashrc to make Git default to using the terminal
+for usernames and passwords.
+
+
+
+
Our local and remote repositories are now in this state:
+
+
+
+
+
+
The ‘-u’ Flag
+
+
You may see a -u option used with git push
+in some documentation. This option is synonymous with the
+--set-upstream-to option for the git branch
+command, and is used to associate the current branch with a remote
+branch so that the git pull command can be used without any
+arguments. To do this, simply use git push -u origin main
+once the remote has been set up.
+
+
+
+
We can pull changes from the remote repository to the local one as
+well:
+
+
BASH
+
+
$ git pull origin main
+
+
+
OUTPUT
+
+
From https://github.com/alflin/recipes
+ * branch main -> FETCH_HEAD
+Already up-to-date.
+
+
Pulling has no effect in this case because the two repositories are
+already synchronized. If someone else had pushed some changes to the
+repository on GitHub, though, this command would download them to our
+local repository.
+
+
+
+
+
+
GitHub GUI
+
+
Browse to your recipes repository on GitHub. Under the
+Code tab, find and click on the text that says “XX commits” (where “XX”
+is some number). Hover over, and click on, the three buttons to the
+right of each commit. What information can you gather/explore from these
+buttons? How would you get that same information in the shell?
+
+
+
+
+
+
+
+
+
The left-most button (with the picture of a clipboard) copies the
+full identifier of the commit to the clipboard. In the shell,
+git log will show you the full commit identifier for each
+commit.
+
When you click on the middle button, you’ll see all of the changes
+that were made in that particular commit. Green shaded lines indicate
+additions and red ones removals. In the shell we can do the same thing
+with git diff. In particular,
+git diff ID1..ID2 where ID1 and ID2 are commit identifiers
+(e.g. git diff a3bf1e5..041e637) will show the differences
+between those two commits.
+
The right-most button lets you view all of the files in the
+repository at the time of that commit. To do this in the shell, we’d
+need to checkout the repository at that particular time. We can do this
+with git checkout ID where ID is the identifier of the
+commit we want to look at. If we do this, we need to remember to put the
+repository back to the right state afterwards!
+
+
+
+
+
+
+
+
+
+
Uploading files directly in GitHub browser
+
+
Github also allows you to skip the command line and upload files
+directly to your repository without having to leave the browser. There
+are two options. First you can click the “Upload files” button in the
+toolbar at the top of the file tree. Or, you can drag and drop files
+from your desktop onto the file tree. You can read more about this on
+this GitHub page.
+
+
+
+
+
+
+
+
+
GitHub Timestamp
+
+
Create a remote repository on GitHub. Push the contents of your local
+repository to the remote. Make changes to your local repository and push
+these changes. Go to the repo you just created on GitHub and check the
+timestamps of the files. How does
+GitHub record times, and why?
+
+
+
+
+
+
+
+
+
GitHub displays timestamps in a human readable relative format
+(i.e. “22 hours ago” or “three weeks ago”). However, if you hover over
+the timestamp, you can see the exact time at which the last change to
+the file occurred.
+
+
+
+
+
+
+
+
+
+
Push vs. Commit
+
+
In this episode, we introduced the “git push” command. How is “git
+push” different from “git commit”?
+
+
+
+
+
+
+
+
+
When we push changes, we’re interacting with a remote repository to
+update it with the changes we’ve made locally (often this corresponds to
+sharing the changes we’ve made with others). Commit only updates your
+local repository.
+
+
+
+
+
+
+
+
+
+
GitHub License and README files
+
+
In this episode we learned about creating a remote repository on
+GitHub, but when you initialized your GitHub repo, you didn’t add a
+README.md or a license file. If you had, what do you think would have
+happened when you tried to link your local and remote repositories?
+
+
+
+
+
+
+
+
+
In this case, we’d see a merge conflict due to unrelated histories.
+When GitHub creates a README.md file, it performs a commit in the remote
+repository. When you try to pull the remote repository to your local
+repository, Git detects that they have histories that do not share a
+common origin and refuses to merge.
+
+
BASH
+
+
$ git pull origin main
+
+
+
OUTPUT
+
+
warning: no common commits
+remote: Enumerating objects: 3, done.
+remote: Counting objects: 100% (3/3), done.
+remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
+Unpacking objects: 100% (3/3), done.
+From https://github.com/alflin/recipes
+ * branch main -> FETCH_HEAD
+ * [new branch] main -> origin/main
+fatal: refusing to merge unrelated histories
+
+
You can force git to merge the two repositories with the option
+--allow-unrelated-histories. Be careful when you use this
+option and carefully examine the contents of local and remote
+repositories before merging.
+
+
BASH
+
+
$ git pull --allow-unrelated-histories origin main
+
+
+
OUTPUT
+
+
From https://github.com/alflin/recipes
+ * branch main -> FETCH_HEAD
+Merge made by the 'recursive' strategy.
+README.md | 1 +
+1 file changed, 1 insertion(+)
+create mode 100644 README.md
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
A local Git repository can be connected to one or more remote
+repositories.
+
Use the SSH protocol to connect to remote repositories.
+
+git push copies changes from a local repository to a
+remote repository.
+
+git pull copies changes from a remote repository to a
+local repository.
How can I use version control to collaborate with other people?
+
+
+
+
+
+
+
+
Objectives
+
+
Clone a remote repository.
+
Collaborate by pushing to a common repository.
+
Describe the basic collaborative workflow.
+
+
+
+
+
+
+
For the next step, get into pairs. One person will be the “Owner” and
+the other will be the “Collaborator”. The goal is that the Collaborator
+add changes into the Owner’s repository. We will switch roles at the
+end, so both persons will play Owner and Collaborator.
+
+
+
+
+
+
Practicing By Yourself
+
+
If you’re working through this lesson on your own, you can carry on
+by opening a second terminal window. This window will represent your
+partner, working on another computer. You won’t need to give anyone
+access on GitHub, because both ‘partners’ are you.
+
+
+
+
The Owner needs to give the Collaborator access. In your repository
+page on GitHub, click the “Settings” button on the right, select
+“Collaborators”, click “Add people”, and then enter your partner’s
+username.
+
To accept access to the Owner’s repo, the Collaborator needs to go to
+https://github.com/notifications
+or check for email notification. Once there she can accept access to the
+Owner’s repo.
+
Next, the Collaborator needs to download a copy of the Owner’s
+repository to her machine. This is called “cloning a repo”.
+
The Collaborator doesn’t want to overwrite her own version of
+recipes.git, so needs to clone the Owner’s repository to a
+different location than her own repository with the same name.
+
To clone the Owner’s repo into her Desktop folder, the
+Collaborator enters:
If you choose to clone without the clone path
+(~/Desktop/alflin-recipes) specified at the end, you will
+clone inside your own recipes folder! Make sure to navigate to the
+Desktop folder first.
+
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:
+
+
BASH
+
+
$ cd ~/Desktop/alflin-recipes
+$ nano hummus.md
+$ cat hummus.md
Then push the change to the Owner’s repository on
+GitHub:
+
+
BASH
+
+
$ git push origin main
+
+
+
OUTPUT
+
+
Enumerating objects: 4, done.
+Counting objects: 4, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (2/2), done.
+Writing objects: 100% (3/3), 306 bytes, done.
+Total 3 (delta 0), reused 0 (delta 0)
+To https://github.com/alflin/recipes.git
+ 9272da5..29aba7c main -> main
+
+
Note that we didn’t have to create a remote called
+origin: Git uses this name by default when we clone a
+repository. (This is why origin was a sensible choice
+earlier when we were setting up remotes by hand.)
+
Take a look at the Owner’s repository on GitHub again, and you should
+be able to see the new commit made by the Collaborator. You may need to
+refresh your browser to see the new commit.
+
+
+
+
+
+
Some more about remotes
+
+
In this episode and the previous one, our local repository has had a
+single “remote”, called origin. A remote is a copy of the
+repository that is hosted somewhere else, that we can push to and pull
+from, and there’s no reason that you have to work with only one. For
+example, on some large projects you might have your own copy in your own
+GitHub account (you’d probably call this origin) and also
+the main “upstream” project repository (let’s call this
+upstream for the sake of examples). You would pull from
+upstream from time to time to get the latest updates that
+other people have committed.
+
Remember that the name you give to a remote only exists locally. It’s
+an alias that you choose - whether origin, or
+upstream, or alfred - and not something
+intrinstic to the remote repository.
+
The git remote family of commands is used to set up and
+alter the remotes associated with a repository. Here are some of the
+most useful ones:
+
+
+git remote -v lists all the remotes that are configured
+(we already used this in the last episode)
+
+git remote add [name] [url] is used to add a new
+remote
+
+git remote remove [name] removes a remote. Note that it
+doesn’t affect the remote repository at all - it just removes the link
+to it from the local repo.
+
+git remote set-url [name] [newurl] changes the URL that
+is associated with the remote. This is useful if it has moved, e.g. to a
+different GitHub account, or from GitHub to a different hosting service.
+Or, if we made a typo when adding it!
+
+git remote rename [oldname] [newname] changes the local
+alias by which a remote is known - its name. For example, one could use
+this to change upstream to alfred.
+
+
+
+
+
To download the Collaborator’s changes from GitHub, the Owner now
+enters:
Now the three repositories (Owner’s local, Collaborator’s local, and
+Owner’s on GitHub) are back in sync.
+
+
+
+
+
+
A Basic Collaborative Workflow
+
+
In practice, it is good to be sure that you have an updated version
+of the repository you are collaborating on, so you should
+git pull before making our changes. The basic collaborative
+workflow would be:
+
+
update your local repo with git pull origin main,
+
make your changes and stage them with git add,
+
commit your changes with git commit -m, and
+
upload the changes to GitHub with
+git push origin main
+
+
+
It is better to make many commits with smaller changes rather than of
+one commit with massive changes: small commits are easier to read and
+review.
+
+
+
+
+
+
+
+
+
Switch Roles and Repeat
+
+
Switch roles and repeat the whole process.
+
+
+
+
+
+
+
+
+
Review Changes
+
+
The Owner pushed commits to the repository without giving any
+information to the Collaborator. How can the Collaborator find out what
+has changed with command line? And on GitHub?
+
+
+
+
+
+
+
+
+
On the command line, the Collaborator can use
+git fetch origin main to get the remote changes into the
+local repository, but without merging them. Then by running
+git diff main origin/main the Collaborator will see the
+changes output in the terminal.
+
On GitHub, the Collaborator can go to the repository and click on
+“commits” to view the most recent commits pushed to the repository.
+
+
+
+
+
+
+
+
+
+
Comment Changes in GitHub
+
+
The Collaborator has some questions about one line change made by the
+Owner and has some suggestions to propose.
+
With GitHub, it is possible to comment on the diff of a commit. Over
+the line of code to comment, a blue comment icon appears to open a
+comment window.
+
The Collaborator posts her comments and suggestions using the GitHub
+interface.
+
+
+
+
+
+
+
+
+
Version History, Backup, and Version Control
+
+
Some backup software can keep a history of the versions of your
+files. They also allows you to recover specific versions. How is this
+functionality different from version control? What are some of the
+benefits of using version control, Git and GitHub?
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
+git clone copies a remote repository to create a local
+repository with a remote called origin automatically set
+up.
What do I do when my changes conflict with someone else’s?
+
+
+
+
+
+
+
+
Objectives
+
+
Explain what conflicts are and when they can occur.
+
Resolve conflicts resulting from a merge.
+
+
+
+
+
+
+
As soon as people can work in parallel, they’ll likely step on each
+other’s toes. This will even happen with a single person: if we are
+working on a piece of software on both our laptop and a server in the
+lab, we could make different changes to each copy. Version control helps
+us manage these conflicts by
+giving us tools to resolve
+overlapping changes.
+
To see how we can resolve conflicts, we must first create one. The
+file guacamole.md currently looks like this in both
+partners’ copies of our recipes repository:
To https://github.com/alflin/recipes.git
+ ! [rejected] main -> main (fetch first)
+error: failed to push some refs to 'https://github.com/alflin/recipes.git'
+hint: Updates were rejected because the remote contains work that you do
+hint: not have locally. This is usually caused by another repository pushing
+hint: to the same ref. You may want to first integrate the remote changes
+hint: (e.g., 'git pull ...') before pushing again.
+hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+
+
Git rejects the push because it detects that the remote repository
+has new updates that have not been incorporated into the local branch.
+What we have to do is pull the changes from GitHub, merge them into the copy we’re currently
+working in, and then push that. Let’s start by pulling:
+
+
BASH
+
+
$ git pull origin main
+
+
+
OUTPUT
+
+
remote: Enumerating objects: 5, done.
+remote: Counting objects: 100% (5/5), done.
+remote: Compressing objects: 100% (1/1), done.
+remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0
+Unpacking objects: 100% (3/3), done.
+From https://github.com/alflin/recipes
+ * branch main -> FETCH_HEAD
+ 29aba7c..dabb4c8 main -> origin/main
+Auto-merging guacamole.md
+CONFLICT (content): Merge conflict in guacamole.md
+Automatic merge failed; fix conflicts and then commit the result.
+
+
+
+
+
+
+
You may need to tell Git what to do
+
+
If you see the below in your output, Git is asking what it should
+do.
+
+
OUTPUT
+
+
hint: You have divergent branches and need to specify how to reconcile them.
+hint: You can do so by running one of the following commands sometime before
+hint: your next pull:
+hint:
+hint: git config pull.rebase false # merge (the default strategy)
+hint: git config pull.rebase true # rebase
+hint: git config pull.ff only # fast-forward only
+hint:
+hint: You can replace "git config" with "git config --global" to set a default
+hint: preference for all repositories. You can also pass --rebase, --no-rebase,
+hint: or --ff-only on the command line to override the configured default per
+hint: invocation.
+
+
In newer versions of Git it gives you the option of specifying
+different behaviours when a pull would merge divergent branches. In our
+case we want ‘the default strategy’. To use this strategy run the
+following command to select it as the default thing git should do.
+
+
BASH
+
+
$ git config pull.rebase false
+
+
Then attempt the pull again.
+
+
BASH
+
+
$ git pull origin main
+
+
+
+
+
The git pull command updates the local repository to
+include those changes already included in the remote repository. After
+the changes from remote branch have been fetched, Git detects that
+changes made to the local copy overlap with those made to the remote
+repository, and therefore refuses to merge the two versions to stop us
+from trampling on our previous work. The conflict is marked in in the
+affected file:
+
+
BASH
+
+
$ cat guacamole.md
+
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+* avocado
+* lime
+* salt
+## Instructions
+<<<<<<< HEAD
+* peel the avocados
+=======
+* put one avocado into a bowl.
+>>>>>>> dabb4c8c450e8475aee9b14b4383acc99f42af1d
+
+
Our change is preceded by
+<<<<<<< HEAD. Git has then inserted
+======= as a separator between the conflicting changes and
+marked the end of the content downloaded from GitHub with
+>>>>>>>. (The string of letters and
+digits after that marker identifies the commit we’ve just
+downloaded.)
+
It is now up to us to edit this file to remove these markers and
+reconcile the changes. We can do anything we want: keep the change made
+in the local repository, keep the change made in the remote repository,
+write something new to replace both, or get rid of the change entirely.
+Let’s replace both so that the file looks like this:
+
+
BASH
+
+
$ cat guacamole.md
+
+
+
OUTPUT
+
+
# Guacamole
+## Ingredients
+* avocado
+* lime
+* salt
+## Instructions
+* peel the avocados and put them into a bowl.
+
+
To finish merging, we add guacamole.md to the changes
+being made by the merge and then commit:
+
+
BASH
+
+
$ git add guacamole.md
+$ git status
+
+
+
OUTPUT
+
+
On branch main
+All conflicts fixed but you are still merging.
+ (use "git commit" to conclude merge)
+
+Changes to be committed:
+
+ modified: guacamole.md
+
+
+
+
BASH
+
+
$ git commit -m"Merge changes from GitHub"
+
+
+
OUTPUT
+
+
[main 2abf2b1] Merge changes from GitHub
+
+
Now we can push our changes to GitHub:
+
+
BASH
+
+
$ git push origin main
+
+
+
OUTPUT
+
+
Enumerating objects: 10, done.
+Counting objects: 100% (10/10), done.
+Delta compression using up to 8 threads
+Compressing objects: 100% (6/6), done.
+Writing objects: 100% (6/6), 645 bytes | 645.00 KiB/s, done.
+Total 6 (delta 4), reused 0 (delta 0)
+remote: Resolving deltas: 100% (4/4), completed with 2 local objects.
+To https://github.com/alflin/recipes.git
+ dabb4c8..2abf2b1 main -> main
+
+
Git keeps track of what we’ve merged with what, so we don’t have to
+fix things by hand again when the collaborator who made the first change
+pulls again:
# Guacamole
+## Ingredients
+* avocado
+* lime
+* salt
+## Instructions
+* peel the avocados and put them into a bowl.
+
+
We don’t need to merge again because Git knows someone has already
+done that.
+
Git’s ability to resolve conflicts is very useful, but conflict
+resolution costs time and effort, and can introduce errors if conflicts
+are not resolved correctly. If you find yourself resolving a lot of
+conflicts in a project, consider these technical approaches to reducing
+them:
+
+
Pull from upstream more frequently, especially before starting new
+work
+
Use topic branches to segregate work, merging to main when
+complete
+
Make smaller more atomic commits
+
Push your work when it is done and encourage your team to do the
+same to reduce work in progress and, by extension, the chance of having
+conflicts
+
Where logically appropriate, break large files into smaller ones so
+that it is less likely that two authors will alter the same file
+simultaneously
+
+
Conflicts can also be minimized with project management
+strategies:
+
+
Clarify who is responsible for what areas with your
+collaborators
+
Discuss what order tasks should be carried out in with your
+collaborators so that tasks expected to change the same lines won’t be
+worked on simultaneously
+
If the conflicts are stylistic churn (e.g. tabs vs. spaces),
+establish a project convention that is governing and use code style
+tools (e.g. htmltidy, perltidy,
+rubocop, etc.) to enforce, if necessary
+
+
+
+
+
+
+
Solving Conflicts that You Create
+
+
Clone the repository created by your instructor. Add a new file to
+it, and modify an existing file (your instructor will tell you which
+one). When asked by your instructor, pull her changes from the
+repository to create a conflict, then resolve it.
+
+
+
+
+
+
+
+
+
Conflicts on Non-textual files
+
+
What does Git do when there is a conflict in an image or some other
+non-textual file that is stored in version control?
+
+
+
+
+
+
+
+
+
Let’s try it. Suppose Alfredo takes a picture of its guacamole and
+calls it guacamole.jpg.
+
If you do not have an image file of guacamole available, you can
+create a dummy binary file like this:
+
+
BASH
+
+
$ head --bytes 1024 /dev/urandom > guacamole.jpg
+$ ls -lh guacamole.jpg
+
+
+
OUTPUT
+
+
-rw-r--r-- 1 alflin 57095 1.0K Mar 8 20:24 guacamole.jpg
+
+
ls shows us that this created a 1-kilobyte file. It is
+full of random bytes read from the special file,
+/dev/urandom.
+
Now, suppose Alfredo adds guacamole.jpg to his
+repository:
Suppose that Jimmy has added a similar picture in the meantime. His
+is a picture of a guacamole with nachos, but it is also called
+guacamole.jpg. When Alfredo tries to push, he gets a
+familiar message:
+
+
BASH
+
+
$ git push origin main
+
+
+
OUTPUT
+
+
To https://github.com/alflin/recipes.git
+ ! [rejected] main -> main (fetch first)
+error: failed to push some refs to 'https://github.com/alflin/recipes.git'
+hint: Updates were rejected because the remote contains work that you do
+hint: not have locally. This is usually caused by another repository pushing
+hint: to the same ref. You may want to first integrate the remote changes
+hint: (e.g., 'git pull ...') before pushing again.
+hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+
+
We’ve learned that we must pull first and resolve any conflicts:
+
+
BASH
+
+
$ git pull origin main
+
+
When there is a conflict on an image or other binary file, git prints
+a message like this:
+
+
OUTPUT
+
+
$ git pull origin main
+remote: Counting objects: 3, done.
+remote: Compressing objects: 100% (3/3), done.
+remote: Total 3 (delta 0), reused 0 (delta 0)
+Unpacking objects: 100% (3/3), done.
+From https://github.com/alflin/recipes.git
+ * branch main -> FETCH_HEAD
+ 6a67967..439dc8c main -> origin/main
+warning: Cannot merge binary files: guacamole.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e)
+Auto-merging guacamole.jpg
+CONFLICT (add/add): Merge conflict in guacamole.jpg
+Automatic merge failed; fix conflicts and then commit the result.
+
+
The conflict message here is mostly the same as it was for
+guacamole.md, but there is one key additional line:
+
+
OUTPUT
+
+
warning: Cannot merge binary files: guacamole.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e)
+
+
Git cannot automatically insert conflict markers into an image as it
+does for text files. So, instead of editing the image file, we must
+check out the version we want to keep. Then we can add and commit this
+version.
+
On the key line above, Git has conveniently given us commit
+identifiers for the two versions of guacamole.jpg. Our
+version is HEAD, and Jimmy’s version is
+439dc8c0.... If we want to use our version, we can use
+git checkout:
+
+
BASH
+
+
$ git checkout HEAD guacamole.jpg
+$ git add guacamole.jpg
+$ git commit -m"Use image of just guacamole instead of with nachos"
+
+
+
OUTPUT
+
+
[main 21032c3] Use image of just guacamole instead of with nachos
+
+
If instead we want to use Jimmy’s version, we can use
+git checkout with Jimmy’s commit identifier,
+439dc8c0:
+
+
BASH
+
+
$ git checkout 439dc8c0 guacamole.jpg
+$ git add guacamole.jpg
+$ git commit -m"Use image of guacamole with nachos instead of just guacamole"
+
+
+
OUTPUT
+
+
[main da21b34] Use image of guacamole with nachos instead of just guacamole
+
+
We can also keep both images. The catch is that we cannot
+keep them under the same name. But, we can check out each version in
+succession and rename it, then add the renamed versions. First,
+check out each image and rename it:
Then, remove the old guacamole.jpg and add the two new
+files:
+
+
BASH
+
+
$ git rm guacamole.jpg
+$ git add guacamole-only.jpg
+$ git add guacamole-nachos.jpg
+$ git commit -m"Use two images: just guacamole and with nachos"
+
+
+
OUTPUT
+
+
[main 94ae08c] Use two images: just guacamole and with nachos
+ 2 files changed, 0 insertions(+), 0 deletions(-)
+ create mode 100644 guacamole-nachos.jpg
+ rename guacamole.jpg => guacamole-only.jpg (100%)
+
+
Now both images of guacamole are checked into the repository, and
+guacamole.jpg no longer exists.
+
+
+
+
+
+
+
+
+
+
A Typical Work Session
+
+
You sit down at your computer to work on a shared project that is
+tracked in a remote Git repository. During your work session, you take
+the following actions, but not in this order:
+
+
+Make changes by appending the number 100 to a
+text file numbers.txt
+
+
+Update remote repository to match the local repository
+
+Celebrate your success with some fancy beverage(s)
+
+Update local repository to match the remote repository
+
+Stage changes to be committed
+
+Commit changes to the local repository
+
+
In what order should you perform these actions to minimize the
+chances of conflicts? Put the commands above in order in the
+action column of the table below. When you have the order
+right, see if you can write the corresponding commands in the
+command column. A few steps are populated to get you
+started.
+
+
+
+
+
+
+
+
order
+
action . . . . . . . . . .
+
command . . . . . . . . . .
+
+
+
+
1
+
+
+
+
+
2
+
+
echo 100 >> numbers.txt
+
+
+
3
+
+
+
+
+
4
+
+
+
+
+
5
+
+
+
+
+
6
+
Celebrate!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
order
+
action . . . . . .
+
command . . . . . . . . . . . . . . . . . . .
+
+
+
+
1
+
Update local
+
git pull origin main
+
+
+
2
+
Make changes
+
echo 100 >> numbers.txt
+
+
+
3
+
Stage changes
+
git add numbers.txt
+
+
+
4
+
Commit changes
+
git commit -m "Add 100 to numbers.txt"
+
+
+
5
+
Update remote
+
git push origin main
+
+
+
6
+
Celebrate!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
Conflicts occur when two or more people change the same lines of the
+same file.
+
The version control system does not allow people to overwrite each
+other’s changes blindly, but highlights conflicts so that they can be
+resolved.
How can version control help me make my work more open?
+
+
+
+
+
+
+
+
Objectives
+
+
Explain how a version control system can be leveraged as an
+electronic lab notebook for computational work.
+
+
+
+
+
+
+
+
The opposite of “open” isn’t “closed”. The opposite of “open” is
+“broken”.
+
-– John Wilbanks
+
+
Free sharing of information might be the ideal in science, but the
+reality is often more complicated. Normal practice today looks something
+like this:
+
+
A scientist collects some data and stores it on a machine that is
+occasionally backed up by their department.
+
They then write or modify a few small programs (which also reside on
+the machine) to analyze that data.
+
Once they have some results, they write them up and submit a paper.
+The scientist might include their data – a growing number of journals
+require this – but they probably don’t include the code.
+
Time passes.
+
The journal sends the scientist reviews written anonymously by a
+handful of other people in their field. The scientist revises the paper
+to satisfy the reviewers, during which time they might also modify the
+scripts they wrote earlier, and resubmits.
+
More time passes.
+
The paper is eventually published. It might include a link to an
+online copy of the data, but the paper itself will be behind a paywall:
+only people who have personal or institutional access will be able to
+read it.
+
+
For a growing number of scientists, though, the process looks like
+this:
+
+
The data that the scientist collects is stored in an open access
+repository like figshare or Zenodo, possibly as soon as it’s
+collected, and given its own Digital
+Object Identifier (DOI). Or the data was already published and is
+stored in Dryad.
+
The scientist creates a new repository on GitHub to hold their
+work.
+
During analysis, they push changes to their scripts (and possibly
+some output files) to that repository. The scientist also uses the
+repository for their paper; that repository is then the hub for
+collaboration with colleagues.
+
When they are happy with the state of the paper, the scientist posts
+a version to arXiv or some other
+preprint server to invite feedback from peers.
+
Based on that feedback, they may post several revisions before
+finally submitting the paper to a journal.
+
The published paper includes links to the preprint and to the code
+and data repositories, which makes it much easier for other scientists
+to use their work as starting point for their own research.
+
+
This open model accelerates discovery: the more open work is, the more widely it
+is cited and re-used. However, people who want to work this way need
+to make some decisions about what exactly “open” means and how to do it.
+You can find more on the different aspects of Open Science in this
+book.
+
This is one of the (many) reasons we teach version control. When used
+diligently, it answers the “how” question by acting as a shareable
+electronic lab notebook for computational work:
+
+
The conceptual stages of your work are documented, including who did
+what and when. Every step is stamped with an identifier (the commit ID)
+that is for most intents and purposes unique.
+
You can tie documentation of rationale, ideas, and other
+intellectual work directly to the changes that spring from them.
+
You can refer to what you used in your research to obtain your
+computational results in a way that is unique and recoverable.
+
With a version control system such as Git, the entire history of the
+repository is easy to archive for perpetuity.
+
+
+
+
+
+
+
Making Code Citable
+
+
Anything that is hosted in a version control repository (data, code,
+papers, etc.) can be turned into a citable object. You’ll learn how to
+do this in the later episode on
+Citation.
+
+
+
+
+
+
+
+
+
How Reproducible Is My Work?
+
+
Ask one of your labmates to reproduce a result you recently obtained
+using only what they can find in your papers or on the web. Try to do
+the same for one of their results, then try to do it for a result from a
+lab you work with.
+
+
+
+
+
+
+
+
+
How to Find an Appropriate Data Repository?
+
+
Surf the internet for a couple of minutes and check out the data
+repositories mentioned above: Figshare, Zenodo, Dryad. Depending on your field of
+research, you might find community-recognized repositories that are
+well-known in your field. You might also find useful these
+data repositories recommended by Nature. Discuss with your neighbor
+which data repository you might want to approach for your current
+project and explain why.
+
+
+
+
+
+
+
+
+
How to Track Large Data or Image Files using Git?
+
+
Large data or image files such as .md5 or
+.psd file types can be tracked within a github repository
+using the Git Large File
+Storage open source extension tool. This tool automatically uploads
+large file contents to a remote server and replaces the file with a text
+pointer within the github repository.
+
Try downloading and installing the Git Large File Storage extension
+tool, then add tracking of a large file to your github repository. Ask a
+colleague to clone your repository and describe what they see when they
+access that large file.
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
Open scientific work is more useful and more highly cited than
+closed.
What licensing information should I include with my work?
+
+
+
+
+
+
+
+
Objectives
+
+
Explain why adding licensing information to a repository is
+important.
+
Choose a proper license.
+
Explain differences in licensing and social expectations.
+
+
+
+
+
+
+
When a repository with source code, a manuscript or other creative
+works becomes public, it should include a file LICENSE or
+LICENSE.txt in the base directory of the repository that
+clearly states under which license the content is being made available.
+This is because creative works are automatically eligible for
+intellectual property (and thus copyright) protection. Reusing creative
+works without a license is dangerous, because the copyright holders
+could sue you for copyright infringement.
+
A license solves this problem by granting rights to others (the
+licensees) that they would otherwise not have. What rights are being
+granted under which conditions differs, often only slightly, from one
+license to another. In practice, a few licenses are by far the most
+popular, and choosealicense.com will help you
+find a common license that suits your needs. Important considerations
+include:
+
+
Whether you want to address patent rights.
+
Whether you require people distributing derivative works to also
+distribute their source code.
+
Whether the content you are licensing is source code.
+
Whether you want to license the code at all.
+
+
Choosing a license that is in common use makes life easier for
+contributors and users, because they are more likely to already be
+familiar with the license and don’t have to wade through a bunch of
+jargon to decide if they’re ok with it. The Open Source Initiative and Free Software
+Foundation both maintain lists of licenses which are good
+choices.
+
This
+article provides an excellent overview of licensing and licensing
+options from the perspective of scientists who also write code.
+
At the end of the day what matters is that there is a clear statement
+as to what the license is. Also, the license is best chosen from the
+get-go, even if for a repository that is not public. Pushing off the
+decision only makes it more complicated later, because each time a new
+collaborator starts contributing, they, too, hold copyright and will
+thus need to be asked for approval once a license is chosen.
+
+
+
+
+
+
Can I Use Open License?
+
+
Find out whether you are allowed to apply an open license to your
+software. Can you do this unilaterally, or do you need permission from
+someone in your institution? If so, who?
+
+
+
+
+
+
+
+
+
What licenses have I already accepted?
+
+
Many of the software tools we use on a daily basis (including in this
+workshop) are released as open-source software. Pick a project on GitHub
+from the list below, or one of your own choosing. Find its license
+(usually in a file called LICENSE or COPYING)
+and talk about how it restricts your use of the software. Is it one of
+the licenses discussed in this session? How is it different?
The LICENSE, LICENSE.md, or
+LICENSE.txt file is often used in a repository to indicate
+how the contents of the repo may be used by others.
+
People who incorporate General Public License (GPL’d) software into
+their own software must make the derived software also open under the
+GPL license if they decide to share it; most other open licenses do not
+require this.
+
The Creative Commons family of licenses allow people to mix and
+match requirements and restrictions on attribution, creation of
+derivative works, further sharing, and commercialization.
+
People who are not lawyers should not try to write licenses from
+scratch.
Smith AM, Katz DS, Niemeyer KE, FORCE11 Software Citation Working Group. (2016) Software citation
+principles. [PeerJ Computer Science 2:e86](https://peerj.com/articles/cs-86/)
+https://doi.org/10.7717/peerj-cs.8
+
There is also an @software{...
+BibTeX entry type in case
+no “umbrella” citation like a paper or book exists for the project you
+want to make citable.
+
+
+
+
+
+
Key Points
+
+
+
Add a CITATION file to a repository to explain how you want your
+work cited.
Where should I host my version control repositories?
+
+
+
+
+
+
+
+
Objectives
+
+
Explain different options for hosting scientific work.
+
+
+
+
+
+
+
After choosing a license, another big
+question for groups that want to open up their work is where to host
+their code and data. One option is for the lab, the department, or the
+university to provide a server, manage accounts and backups, and so on.
+The main benefit of this is that it clarifies who owns what, which is
+particularly important if any of the material is sensitive (i.e.,
+relates to experiments involving human subjects or may be used in a
+patent application). The main drawbacks are the cost of providing the
+service and its longevity: a scientist who has spent ten years
+collecting data would like to be sure that data will still be available
+ten years from now, but that’s well beyond the lifespan of most of the
+grants that fund academic infrastructure.
+
Another option is to purchase a domain and pay an Internet service
+provider (ISP) to host it. This gives the individual or group more
+control, and sidesteps problems that can arise when moving from one
+institution to another, but requires more time and effort to set up than
+either the option above or the option below.
+
The third option is to use a public hosting service like GitHub, GitLab, or BitBucket. Each of these services
+provides a web interface that enables people to create, view, and edit
+their code repositories. These services also provide communication and
+project management tools including issue tracking, wiki pages, email
+notifications, and code reviews. These services benefit from economies
+of scale and network effects: it’s easier to run one large service well
+than to run many smaller services to the same standard. It’s also easier
+for people to collaborate. Using a popular service can help connect your
+project with communities already using the same service.
+
As an example, Software Carpentry is on GitHub where you can
+find the source
+for this page. Anyone with a GitHub account can suggest changes to
+this text.
Using large, well-established services can also help you quickly take
+advantage of powerful tools. One such tool, continuous integration (CI),
+can automatically run software builds and tests whenever code is
+committed or pull requests are submitted. Direct integration of CI with
+an online hosting service means this information is present in any pull
+request, and helps maintain code integrity and quality standards. While
+CI is still available in self-hosted situations, there is much less
+setup and maintenance involved with using an online service.
+Furthermore, such tools are often provided free of charge to open source
+projects, and are also available for private repositories for a fee.
+
+
+
+
+
+
Institutional Barriers
+
+
Sharing is the ideal for science, but many institutions place
+restrictions on sharing, for example to protect potentially patentable
+intellectual property. If you encounter such restrictions, it can be
+productive to inquire about the underlying motivations and either to
+request an exception for a specific project or domain, or to push more
+broadly for institutional reform to support more open science.
+
+
+
+
+
+
+
+
+
Can My Work Be Public?
+
+
Find out whether you are allowed to host your work openly in a public
+repository. Can you do this unilaterally, or do you need permission from
+someone in your institution? If so, who?
+
+
+
+
+
+
+
+
+
Where Can I Share My Work?
+
+
Does your institution have a repository or repositories that you can
+use to share your papers, data and software? How do institutional
+repositories differ from services like arXiV, figshare, GitHub or GitLab?
+
+
+
+
+
+
+
+
+
Key Points
+
+
+
Projects can be hosted on university servers, on personal domains,
+or on a public hosting service.
+
Rules regarding intellectual property and storage of sensitive
+information apply no matter where code and data are hosted.
Version control can be very useful when developing data analysis
+scripts. For that reason, the popular development environment RStudio for the R programming
+language has built-in integration with Git. While some advanced Git
+features still require the command-line, RStudio has a nice interface
+for many common Git operations.
+
RStudio allows us to create a project
+associated with a given directory to keep track of various related
+files. To be able to track the development of the project over time, to
+be able to revert to previous versions, and to collaborate with others,
+we version control the Rstudio project with Git. To get started using
+Git in RStudio, we create a new project:
+
This opens a dialog asking us how we want to create the project. We
+have some options here. Let’s say that we want to use RStudio with the
+recipes repository that we already made. Since that repository lives in
+a directory on our computer, we choose the option “Existing
+Directory”:
+
+
+
+
+
+
Do You See a “Version Control” Option?
+
+
Although we’re not going to use it here, there should be a “version
+control” option on this menu. That is what you would click on if you
+wanted to create a project on your computer by cloning a repository from
+GitHub. If that option is not present, it probably means that RStudio
+doesn’t know where your Git executable is, and you won’t be able to
+progress further in this lesson until you tell RStudio where it is.
+
+
Find your Git Executable
+
+
First let’s make sure that Git is installed on your computer. Open
+your shell on Mac or Linux, or on Windows open the command prompt and
+then type:
+
+
+which git (macOS, Linux)
+
+where git (Windows)
+
+
If there is no version of Git on your computer, please follow the Git
+installation instructions in the setup of this lesson to install Git
+now. Next open your shell or command prompt and type
+which git (macOS, Linux), or where git
+(Windows). Copy the path to the git executable.
+
On one Windows computer which had GitHub Desktop installed on it, the
+path was:
+C:/Users/UserName/AppData/Local/GitHubDesktop/app-1.1.1/resources/app/git/cmd/git.exe
+
NOTE: The path on your computer will be somewhat different.
+
+
+
Tell RStudio where to find GitHub
+
+
In RStudio, go to the Tools menu >
+Global Options > Git/SVN and then browse to
+the Git executable you found in the command prompt or shell. Now restart
+RStudio. Note: Even if you have Git installed, you may need 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”:
+
Ta-da! We have created a new project in RStudio within the existing
+recipes repository. Notice the vertical “Git” menu in the menu bar.
+RStudio has recognized that the current directory is a Git repository,
+and gives us a number of tools to use Git:
+
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 Hummus:
+
Once we have saved our edited files, we can use RStudio to commit the
+changes by clicking on “Commit…” in the Git menu:
+
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 message (in the upper right panel). The icons in the “Status”
+column indicate 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”:
+
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:
+
+
+
+
+
+
Are the Push/Pull Commands Grayed Out?
+
+
Grayed out Push/Pull commands generally mean that RStudio doesn’t
+know the location of your remote repository (e.g. on GitHub). To fix
+this, open a terminal to the repository and enter the command:
+git push -u origin main. Then restart RStudio.
+
+
+
+
If we click on “History”, we can see a graphical version of what
+git log would tell us:
+
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 file:
+
+
+
+
+
+
Tip: versioning disposable output
+
+
Generally you do not want to version control disposable output (or
+read-only data). You should modify the .gitignore file to
+tell Git to ignore these files and directories.
+
+
+
+
+
+
+
+
+
Challenge
+
+
+
Create a new directory within your project called
+graphs.
+
Modify the .gitignore so that the graphs
+directory is not version controlled.
+
+
+
+
+
+
+
+
+
+
This can be done in Rstudio:
+
+
R
+
+
+dir.create("./graphs")
+
+
Then open up the .gitignore file from the right-hand
+panel of Rstudio and add graphs/ to the list of files to
+ignore.
+
+
+
+
+
There are many more features in the RStudio Git menu, but these
+should be enough to get you started!
+
+
+
+
+
+
Key Points
+
+
+
Using RStudio’s Git integration allows you to version control a
+project over time.
Comment Changes in GitHub
+The Collaborator has some questions about one line change made by the +Owner and has some suggestions to propose.
+With GitHub, it is possible to comment on the diff of a commit. Over +the line of code to comment, a blue comment icon appears to open a +comment window.
+The Collaborator posts her comments and suggestions using the GitHub +interface.
+