Skip to content

Commit

Permalink
use language-bash CSS class
Browse files Browse the repository at this point in the history
  • Loading branch information
fmichonneau committed Aug 3, 2020
1 parent eb76373 commit 6e53b6f
Show file tree
Hide file tree
Showing 4 changed files with 94 additions and 94 deletions.
66 changes: 33 additions & 33 deletions _episodes/02-getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,18 +18,18 @@ keypoints:

### Using Git

One of the main barriers to getting started with git is the language. Although some of the language used in git is
fairly self-explanatory, other terms are not so clear. The best way to get to learn the language - which consists of a
number of verbs such as `add`, `commit` and `push` (preceded by the word 'git') - is by using it, which is what we will be doing during this
lesson. These commands will be explained as we proceed from setting up a new version-controlled project to publishing
One of the main barriers to getting started with git is the language. Although some of the language used in git is
fairly self-explanatory, other terms are not so clear. The best way to get to learn the language - which consists of a
number of verbs such as `add`, `commit` and `push` (preceded by the word 'git') - is by using it, which is what we will be doing during this
lesson. These commands will be explained as we proceed from setting up a new version-controlled project to publishing
our own website.


### Creating a repository

A Git **repository** is a data structure used to track changes to a set of project files over time. Repositories are
stored within the same directory as these project files, in a hidden directory called `.git`. We can create a new git
repository either by using [GitHub's web interface](https://github.com/new), or via the command line. Let's use the command line to create a git
A Git **repository** is a data structure used to track changes to a set of project files over time. Repositories are
stored within the same directory as these project files, in a hidden directory called `.git`. We can create a new git
repository either by using [GitHub's web interface](https://github.com/new), or via the command line. Let's use the command line to create a git
repository for the experiments that we're going to do today.

First, we will create a new directory for our project and enter that directory.
Expand All @@ -39,29 +39,29 @@ First, we will create a new directory for our project and enter that directory.
$ mkdir hello-world
$ cd hello-world
~~~
{: .bash}
{: .language-bash }

We will now create an empty git repository to track changes to our project. To do this we will use the git **init** command,
We will now create an empty git repository to track changes to our project. To do this we will use the git **init** command,
which is simply short for *initialise*.

~~~
$ git init
~~~
{: .bash}
{: .language-bash }
~~~
Initialized empty Git repository in <your file path>/hello-world/.git/
~~~
{: .output}


The `hello-world` directory is now a git repository.
The `hello-world` directory is now a git repository.

If we run the `ls` command now (`ls` lists the content of the `hello-world`
directory), the repository might seem empty; however, adding the `-a` flag
for all files via `ls -a` will show all hidden files, which in this case
If we run the `ls` command now (`ls` lists the content of the `hello-world`
directory), the repository might seem empty; however, adding the `-a` flag
for all files via `ls -a` will show all hidden files, which in this case
includes the new hidden directory `.git`. Flags can simply be thought of as command line options that can be added to shell commands.

Note that whenever we use git via the command line, we need to preface each command (or verb) with `git`, so that the computer knows
Note that whenever we use git via the command line, we need to preface each command (or verb) with `git`, so that the computer knows
we are trying to get git to do something, rather than some other program.

### Displaying the current project's status
Expand All @@ -71,30 +71,30 @@ We can run the `git status` command to display the current state of a project. L
~~~
$ git status
~~~
{: .bash}
{: .language-bash }
~~~
On branch master
No commits yet
nothing to commit (create/copy files and use "git add" to track)
~~~
{: .output}

The output tells us that we are on the master branch (more on this later) and that we have nothing to commit (no
The output tells us that we are on the master branch (more on this later) and that we have nothing to commit (no
unsaved changes).


### Adding and committing

We will now create and save our first project file. This is a two-stage process. First, we **add** any files for which
we want to save the changes to a staging area, then we **commit** those changes to the repository. This two-stage
We will now create and save our first project file. This is a two-stage process. First, we **add** any files for which
we want to save the changes to a staging area, then we **commit** those changes to the repository. This two-stage
process gives us fine-grained control over what should and should not be included in a particular commit.

Let's create a new file using the `touch` command, which is a quick way to create an empty file.

~~~
$ touch index.md
~~~
{: .bash}
{: .language-bash }

The `.md` extension above signifies that we have chosen to use the Markdown format, a lightweight markup language with plain text formatting syntax. We will explore Markdown a bit later.

Expand All @@ -103,7 +103,7 @@ Let's check the status of our project again.
~~~
$ git status
~~~
{: .bash}
{: .language-bash }
~~~
On branch master
No commits yet
Expand All @@ -116,21 +116,21 @@ nothing added to commit but untracked files present (use "git add" to track)
~~~
{: .output}

This status is telling us that git has noticed a new file in our directory that we are not yet tracking. With colourised
output, the filename will appear in red. To change this, and to tell Git we want to track any changes we make to
This status is telling us that git has noticed a new file in our directory that we are not yet tracking. With colourised
output, the filename will appear in red. To change this, and to tell Git we want to track any changes we make to
index.md, we use `git add`.

~~~
$ git add index.md
~~~
{: .bash}
{: .language-bash }

This adds our Markdown file to the **staging area** (the area where git checks for file changes). To confirm this we want to use `git status` again.

~~~
$ git status
~~~
{: .bash}
{: .language-bash }
~~~
On branch master
Expand All @@ -153,7 +153,7 @@ has spotted the changes.
~~~
$ git status
~~~
{: .bash}
{: .language-bash }
~~~
On branch master
Expand All @@ -172,32 +172,32 @@ Changes not staged for commit:
~~~
{: .output}

This lets us know that git has indeed spotted the changes to our file, but that it hasn't yet staged them, so let's add
This lets us know that git has indeed spotted the changes to our file, but that it hasn't yet staged them, so let's add
the new version of the file to the staging area.

~~~
$ git add index.md
~~~
{: .bash}
{: .language-bash }

Now we are ready to **commit** our first changes.
Commit is similar to 'saving' a file to Git.
Now we are ready to **commit** our first changes.
Commit is similar to 'saving' a file to Git.
However, compared to saving, a commit provides a lot more information about the changes we have made,
and this information will remain visible to us later.


~~~
$ git commit -m 'Add index.md'
~~~
{: .bash}
{: .language-bash }
~~~
[master (root-commit) e9e8fd3] Add index.md
1 file changed, 1 insertion(+)
create mode 100644 index.md
~~~
{: .output}

We can see that one file has changed and that we made one insertion, which was a line with the text '#Hello, world!'.
We can see that one file has changed and that we made one insertion, which was a line with the text '#Hello, world!'.
We can
also see the commit message 'Add index.md', which we added by using the `-m` flag after `git commit`.
The commit message is used to record a short, descriptive, and specific summary of what we did to help us remember later on without having to look at the actual changes.
Expand Down Expand Up @@ -229,6 +229,6 @@ along with metadata about who made the commit and at what time.

![The Git Staging Area](../fig/git-staging-area.svg)

At the moment, our changes are only recorded locally, on our computer. If we wanted to
At the moment, our changes are only recorded locally, on our computer. If we wanted to
work collaboratively with someone else they would have no way of seeing what we've done.
We will fix that in the next episode by using GitHub to share our work.
66 changes: 33 additions & 33 deletions _episodes/03-sharing.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ to the GitHub repository:
~~~
$ git remote add origin https://github.com/some-librarian/hello-world.git
~~~
{: .bash}
{: .language-bash }

where `some-librarian` should be replaced with your own username.

Expand All @@ -88,7 +88,7 @@ We can check that it is set up correctly with the command:
~~~
$ git remote -v
~~~
{: .bash}
{: .language-bash }
~~~
origin https://github.com/<your_github_username>/hello-world (fetch)
origin https://github.com/<your_github_username>/hello-world (push)
Expand All @@ -105,7 +105,7 @@ will have to "push" our local changes to the GitHub repository. We do this using
~~~
$ git push -u origin master
~~~
{: .bash}
{: .language-bash }
~~~
Counting objects: 3, done.
Writing objects: 100% (3/3), 226 bytes | 0 bytes/s, done.
Expand All @@ -118,40 +118,40 @@ Branch master set up to track remote branch master from origin.

The nickname of our remote repository is "origin" and the default local branch name is "master".
The `-u` flag tells git to remember the parameters, so that next time we can simply run `git push`
and Git will know what to do.
and Git will know what to do.

Pushing our local changes to the Github repository is sometimes referred to as "pushing changes `upstream` to Github".
The word `upstream` here comes from the git flag we used earlier in the command `git push -u origin master`.
The flag `-u` refers to `-set-upstream`, so when we say pushing changes upstream, it refers to the remote repository.
Pushing our local changes to the Github repository is sometimes referred to as "pushing changes `upstream` to Github".
The word `upstream` here comes from the git flag we used earlier in the command `git push -u origin master`.
The flag `-u` refers to `-set-upstream`, so when we say pushing changes upstream, it refers to the remote repository.

You may be prompted to enter your GitHub username and password to complete the command.

When we do a `git push`, we will see Git 'pushing' changes upstream to GitHub. Because our file is very small, this
won't take long but if we had made a lot of changes or were adding a very large repository, we might have to wait a
little longer. We can check where we're at with `git status`.
When we do a `git push`, we will see Git 'pushing' changes upstream to GitHub. Because our file is very small, this
won't take long but if we had made a lot of changes or were adding a very large repository, we might have to wait a
little longer. We can check where we're at with `git status`.

~~~
$ git status
~~~
{: .bash}
{: .language-bash }
~~~
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working tree clean
~~~
{: .output}

This output lets us know where we are working (the master branch). We can also see that we have no changes to commit
This output lets us know where we are working (the master branch). We can also see that we have no changes to commit
and everything is in order.

We can use the `git diff` command to see changes we have made before making a commit. Open index.md with any text
We can use the `git diff` command to see changes we have made before making a commit. Open index.md with any text
editor and enter some text on a new line, for instance "A new line" or something else.
We will then use `git diff` to see the changes we made:

~~~
$ git diff
~~~
{: .bash}
{: .language-bash }
~~~
diff --git a/index.md b/index.md
index aed0629..989787e 100644
Expand All @@ -168,12 +168,12 @@ index aed0629..989787e 100644
The command produces lots of information and it can be a bit overwhelming at first,
but let's go through some key information here:

1. The first line tells us that Git is producing output similar to the Unix `diff` command, comparing the old and new
1. 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.
2. The second line tells exactly which versions of the file Git is comparing; `aed0629` and `989787e` are unique
2. The second line tells exactly which versions of the file Git is comparing; `aed0629` and `989787e` are unique
computer-generated identifiers for those versions.
3. The third and fourth lines once again show the name of the file being changed.
4. The remaining lines are the most interesting; they show us the actual differences and the lines on which they occur.
4. The remaining lines are the most interesting; they show us the actual differences and the lines on which they occur.
In particular, the + markers in the first column show where we have added lines.

We can now commit these changes:
Expand All @@ -182,16 +182,16 @@ We can now commit these changes:
$ git add index.md
$ git commit -m 'Add another line'
~~~
{: .bash}
{: .language-bash }

If we are very forgetful and have already forgotten what we changes we have made, `git log` allows us to look at what
If we are very forgetful and have already forgotten what we changes we have made, `git log` allows us to look at what
we have been doing with our git repository (in reverse chronological order, with the very latest changes first).


~~~
$ git log
~~~
{: .bash}
{: .language-bash }
~~~
commit 8e2eb9920eaa0bf18a4adfa12474ad58b765fd06
Author: Your Name <your_email>
Expand All @@ -207,9 +207,9 @@ Date: Fri Jun 2 18:15:43 2017 +0100
~~~
{: .output}

This shows us the two commits we have made and shows the messages we wrote. It is important to try to use meaningful
commit messages when we make changes. This is especially important when we are working with other people who might not
be able to guess as easily what our short cryptic messages might mean. Note that it is best practice to always write
This shows us the two commits we have made and shows the messages we wrote. It is important to try to use meaningful
commit messages when we make changes. This is especially important when we are working with other people who might not
be able to guess as easily what our short cryptic messages might mean. Note that it is best practice to always write
commit messages in the imperative (e.g. 'Add index.md', rather than 'Adding index.md').

## Pushing changes (again)
Expand All @@ -224,8 +224,8 @@ And if you click on `index.md` you will see that it contains the "Hello, world!"
but not the new line we just added.

This is because we haven't yet pushed our local changes to the remote repository.
This might seem like a mistake in design but it is
often useful to make a lot of commits for small changes so you are able to make careful revisions later and you don't
This might seem like a mistake in design but it is
often useful to make a lot of commits for small changes so you are able to make careful revisions later and you don't
necessarily want to push all these changes one by one.

Another benefit of this design is that you can make commits without being connected to internet.
Expand All @@ -235,7 +235,7 @@ But let's push our changes now, using the `git push` command:
~~~
$ git push
~~~
{: .bash}
{: .language-bash }
~~~
Counting objects: 3, done.
Writing objects: 100% (3/3), 272 bytes | 0 bytes/s, done.
Expand All @@ -250,16 +250,16 @@ And let's check on GitHub that we now have 2 commits there.
## Pulling changes

When working with others, or when we're making our own changes from different machines, we need a way of pulling those
remote changes back into our local copy. For now, we can see how this works by making a change on the GitHub website and
remote changes back into our local copy. For now, we can see how this works by making a change on the GitHub website and
then 'pulling' that change back to our computer.

Let's go to our repository in GitHub and make a change. Underneath where our index.md file is listed you will see a
button to 'Add a README'. Do this now, entering whatever you like, scrolling to the bottom and clicking 'Commit new
Let's go to our repository in GitHub and make a change. Underneath where our index.md file is listed you will see a
button to 'Add a README'. Do this now, entering whatever you like, scrolling to the bottom and clicking 'Commit new
file' (The default commit message will be 'Create README.md', which is fine for our purposes).

> ## The README file
> It is good practice to add a README file to each project to give a brief overview of what the project is about. If you
> put your README file in your repository's root directory, GitHub will recognize and automatically surface your README
> It is good practice to add a README file to each project to give a brief overview of what the project is about. If you
> put your README file in your repository's root directory, GitHub will recognize and automatically surface your README
> to repository visitors
{: .callout}

Expand All @@ -269,7 +269,7 @@ our local repository using the `git pull` command.
~~~
$ git pull
~~~
{: .bash}
{: .language-bash }
~~~
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (2/2), done.
Expand All @@ -288,6 +288,6 @@ Fast-forward
The above output shows that we have fast-forwarded our local repository to include the file README.md. We could confirm
this by entering the `ls` command.

When we begin collaborating on more complex projects, we may have to consider more aspects of git functionality, but
When we begin collaborating on more complex projects, we may have to consider more aspects of git functionality, but
this should be a good start. In the next section, we can look more closely at collaborating and using GitHub pages to
create a website for our project.
Loading

0 comments on commit 6e53b6f

Please sign in to comment.