diff --git a/index.html b/index.html index 3ec416ba..115ccbe8 100644 --- a/index.html +++ b/index.html @@ -111,7 +111,8 @@

Command Line

Version Control

Other Useful Resources

diff --git a/version-control/command-line/tutorial.md b/version-control/command-line/tutorial.md index 06f21136..a7d6e1bc 100644 --- a/version-control/command-line/tutorial.md +++ b/version-control/command-line/tutorial.md @@ -3,42 +3,29 @@ layout: page title: Introduction to the Git command line --- -## Introduction to the Git command line - -**PREREQUISITE:** Basic understanding of the command line. - -Git is a tool that makes sharing code and collaborating with other developers really easy. It also keeps our code tracked and safe. The following examples will help you understand how to use this tool on a daily basis. - -## Before you begin -Install command line Git for your operating system ([OS X](https://sourceforge.net/projects/git-osx-installer/), [Windows](http://msysgit.github.io/) or [Linux](https://git-scm.com/download/linux)) and open your terminal / command prompt. - -Create a directory where you will be storing all your projects. You can call it `code` or `projects`. - -### Setup your Git details - -```bash -$ git config --global user.name "Your Name" -$ git config --global user.email "name@domain" -``` +**PREREQUISITES:** +- Basic understanding of the system command line ([Introduction to the Command Line](../../command-line/introduction/tutorial.html)) +- Git installed and GitHub account set-up ([Get set-up with Git and GitHub](../set-up/tutorial.html).) -### Setup an SSH key - -An SSH key is used to identify trusted computers, without entering a password. -[Instructions on how to generate an SSH key](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key) +## Introduction to the Git command line +The following set of examples will help you understand how to use Git via the command line, while carrying out common day-to-day tasks. ## Example 1: Everyday commands ### Create and add your project in Git +To start, let's make a directory to store our files and initialise the directory as a Git repository on our local system. This is the same as we did in the [Set-up tutorial]((../set-up/tutorial.html)) previously. ```bash $ mkdir practising-git $ cd practising-git $ git init ``` +> You may recall this will make the directory, change directory so we're located in it, then initialise it as an empty Git repository. -### Create a file +### Create a file. +We can create a new file in our local directory and add a line to it at the same time, with the below. ```bash $ echo "

Learning git

" > index.html @@ -46,15 +33,17 @@ $ echo "

Learning git

" > index.html > The above command will output `

Learning Git

` and store it in `index.html`. Open up the file and have a look. -### Check the Git repository status. +### Check the Git repository status +To check the state of our working directory and the Staging area (where we hold files until we commit them), we use the following command. ```bash $ git status ``` -> The above command will tell you which files in the current directory have been changed, which files have not yet been added to the Git repository and so on. +> The above command will tell you which files in the current directory have been changed and staged, which haven't and which files aren't being tracked by Git. -### Add your file on the repository and commit your changes. +### Add your file to the local repository and commit your changes +When we create new files or change existing ones, we 'add' them to an index of items to be committed to the local repository. The 'commit' command saves our changes into the local repository. ```bash $ git add . @@ -62,29 +51,34 @@ $ git status $ git commit -m 'this is my first command-line commit!' ``` -> `.` will add all the files in the current directory and subdirectories. You should only use it when initialising your repository. Rest of the time you can specify the file names to be added. +> `.` will add **all** the files in the current directory and subdirectories. You should only use it when initialising your repository. The rest of the time it's recommended that you specify the individual file names to be added. -### Check the Git commit history. +### Check the Git commit history +To check a list of commits in a repository use the `log` command. ```bash $ git log ``` -### Transferring project repository to an online service +> Don't forget, you can hit `q` to quit out of a log if it's too long. -First you need to create an account to the service of your choice ([GitHub](https://github.com/join), [GitLab](https://gitlab.com/)). Then, create a new project (or repository). +### Transferring files from our local project repository to an online service -Copy the information about adding an existing project to the repository which should be something like the details below. +Before we can add files to a remote repository, we need to have created an account with a service that is hosting that repository. If you've not done that yet, head over to our tutorial: Get set-up with [Git and GitHub](../set-up/tutorial.html). +If you've already done that, then great - just run the commands below, adding in the correct remote repository URL, such as `https://github.com/codebar/tutorials.git`. ```bash $ git remote add origin $ git push -u origin master ``` -#### What is `remote` +> This is worth repeating: We first add the location of a remote repository, in our case the remote repo is on Github and we've callled it 'origin' as it's the original repository we cloned down to our system. Then we 'push' our changes to the origin's 'master' branch. When there, we can raise a new 'Pull Request' (PR) to get the changes 'merged' into the live code. Check out 'Get set-up with [Git and GitHub]'(../set-up/tutorial.html) tutorial for full details around this. + +#### What is `remote`? -`remote` is simply the URL of your repository in any online repository hosting services. The `git remote` lists all the remote repositories you have configured. You could have the same repository stored in many places like GitHub and GitLab or Heroku and in such cases you will have a remote configured for each of the remote repository you have. +`remote` is the URL of your repository in any online repository hosting service, such as GitHub. The command `git remote` lists all the remote repositories you have configured. You could have the same repository stored in many places like GitHub and GitLab or Heroku and in such cases you will add a remote repository reference to you local machine, as we did above, for each of the remote repositories you have. +`remote` is the URL of your repository in any online repository hosting service, such as GitHub. The command `git remote` lists all the remote repositories you have configured. You could have the same repository stored in many places like GitHub and GitLab or Heroku and in such cases you will add a remote repository reference to you local machine, as we did above, for each of the remote repositories you have. The structure of the command to add a new `remote` is `git remote `. @@ -158,7 +152,7 @@ $ git push origin master $ git log ``` -### Check your code online (from the GitHub or GitLab website). +### Check your code online (from the GitHub or GitLab website) # Example 3: Verifying changes before any commit @@ -276,7 +270,7 @@ $ git commit -m 'Oops, I just deleted my list' > Can you explain the commands you just used? -### Check the log history. +### Check the log history ```bash $ git log @@ -298,7 +292,7 @@ commit c0bb15bf9f75613930c66760b90b2ccc1af0d2d6 ... ``` -### Resetting the last commit. +### Resetting the last commit ```bash $ git reset HEAD^ @@ -327,7 +321,7 @@ $ git status > Do you remember how to discard the changes? Have a look earlier in the tutorial. -# Example 6: Revert committed and pushed changes. +# Example 6: Revert committed and pushed changes You can correct something you pushed accidentally by changing history. In the following example you will see how can you revert the last pushed commit. @@ -375,89 +369,141 @@ commit c0bb15bf9f75613930c66760b90b2ccc1af0d2d6 $ git revert f4d8d2c2ca851c73176641109172780487da9c1d ``` -After reverting the changes you have to push the code to the remote repo to apply them +After reverting the changes, you have to push the code to the remote repo to apply them ```bash -git push origin master +$ git push origin master ``` # Extras -Following are some good resources to to help you set up Git. -https://help.github.com/articles/set-up-git/ -## Configuring your Git environment +### Creating a Git Config file +Git allows us to define configuration settings that affect either just the repository we're working with, such as the URL of the remote repository location, or global settings such as Aliases for common commands (see below). There's a great example over at [https://gist.github.com/pksunkara/988716](https://gist.github.com/pksunkara/988716) + +Create a file called `.gitconfig` in the root directory (parent folder) of your local Git repo by typing `git touch .gitconfig` in the terminal window. Though it may look odd, this file doesn't have an extension such as `.txt` like typical files. Now let's practise modifying this file by adding the following configuration items. -Create the file `.gitconfig` in your root directory and add the following configuration +### User name and email +If you didn't add your name and email address in the Set-up tutorial, add them now. These are added to each Git commit so it's clear who made the commit to the repo. ```bash +$ git config --global user.name "Your Name" +$ git config --global user.email "name@domain" +``` + +If you want to just edit the `.gitconfig` file directly then look for it in your root folder, open in your favourite text editing software add the following: + +``` [user] - name = - email = + name = "Your Name" + email = "Your email address" ``` ### Creating shortcuts (aliases) +In order to save time and key strokes when working on the command line in a terminal window, you can create aliases for your most commonly used Git commands. Here are some examples. + +```bash +$ git config --global alias.cm 'commit -m' +$ git config --global alias.co checkout +$ git config --global alias.st status +```` + +To use them just type `git cm "Message here"` or `git st` for example. Simply put, use the alias in place of the full text Git command, then add any switches on the end (such as a commit message) as you would normally. If you want to just edit the `.gitconfig` file directly then you would add the following section: ``` [alias] - ci = commit - dc = diff --cached + cm = commit --message + co = checkout + st = status ``` > Can you think of another command that you would find handy to shorten down? ### Telling Git to try and fix whitespace issues before committing +A common issue when editing files, especially if the file has been worked on using both Mac and Windows systems, is having a) a trailing whitespace at the end of a line of code, b) a line that is entirely whitespace or c) having a leading whitespace before a tab. When performing a commit where a file has these, Git will prompt you about how (and if) you'd like to fix them. We can tell Git to always fix whitespace issues by adding the following to our `.gitconfig` file: + +```bash +$ git config --global apply.whitespace fix +``` + +If you prefer to just edit the `.gitconfig` file directly, then you would add the following section: ``` [apply] whitespace = fix ``` -### Ignoring files across directories +### Ignoring files across directories (.gitignore) +Very often you have certain types of files or directories in the folder where your code and other assets are. When we commit our code to the Git repository every file will be commited and added to the repository. If you want to exclude certain files on your system from being included in the Git repository, we can add a `.gitignore` file to do this. Make sure this file is included in your repo, to share the ignore rules with others. + +Firstly, look for the `.gitignore` file in the root of the directory you're working in. If you have one, skip to the next step, if not let's make one now. + +```bash +$ git touch .gitignore +``` + +To make a reference between the `.gitconfig` file we were working with and the `.gitignore` file we just made, execute the following command: +```bash +$ git config --global core.excludesfile ~/.gitignore +``` +If you prefer, to just edit the `.gitignore` file directly, then you would add the following section: ``` [core] excludesfile = ~/.gitignore ``` -To apply this you need to create a .gitignore file in your root path. There you can add either specific files or extensions that you always want excluded. This is a handy list to help you start +Within the `.gitignore` file you can add specific files or extensions that you always want excluded. Here's some common examples that you may want to exclude. ``` -*.DS_Store -*~ -*.log -*.zip -*.pkg -*.rar + *.DS_Store + *~ + *.log + *.zip + *.pkg + *.rar ``` > Do you know what these files are? You normally wouldn't want to commit logs or packages. +> For a more complete list of files you may want to exclude have a look at [https://gist.github.com/octocat/9257657](check out the list from Octocat). -### Pimping your log history +### Prettify your log history +It's possible to make your Git logs easier to read by changing the colour and style of them. -In your aliases add this as an alias for viewing Git logs +On the command line, run the following: + +```bash +$ git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative" +``` + +As previously, if you prefer to edit the `.gitconfig` file directly, add the following as an alias for viewing Git logs ``` lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative ``` -Try it out by running `git lg` +Try it out by running `git lg` in a terminal window. If the log is very long, you can quit out of the log by hitting `q` on the keyboard. + +## Bonus ### Store commands in your history -Add HISTSIZE and HISTFILESIZE to your .bashrc file. **HISTSIZE** is the number of commands stored in memory when you are using the terminal. **HISTFILESIZE** is the number of commands stored in memory when you are using the terminal +On the command line you can use the up and down arrows to cycle back over the Git commands you've typed before. This can save time when retrying certain commands or allow you to fix them without retyping the whole command. We can Add HISTSIZE and HISTFILESIZE to your `.bashrc` file to make sure plenty of commands are stored beyond the default 500. +- **HISTSIZE** is the number of commands stored in memory when you are using the terminal. +- **HISTFILESIZE** is the number of commands stored in memory for future sessions. ```bash HISTSIZE=10000 HISTFILESIZE=20000 ``` -After typing a couple of command in the terminal, try executing +After typing a couple of commands in the terminal to generate some history, try executing `Ctrl`+`R` followed by the command you want to run e.g. `git lg` or just use the arrows on the keyboard to cycle back through them. -Ctrl+R followed by the command you want to run e.g. `git lg` +> You can see the entire history by running `history` +## The next step -> You can see the entire history by running `history` +Get learning JavaScript, HTML, CSS, Ruby and more on [codebar](http://tutorials.codebar.io/). ---- -This ends **Git: Introduction to command line** tutorial. Is there something you don't understand? Try and go through the provided resources with your coach. If you have any feedback, or can think of ways to improve this tutorial [send us an email](mailto:feedback@codebar.io) and let us know. +----- +This ends **Introduction to the Git command line** tutorial. Is there something you don't understand? Try and go through the provided resources with your coach. If you have any feedback, or can think of ways to improve this tutorial [send us an email](mailto:feedback@codebar.io) and let us know. \ No newline at end of file diff --git a/version-control/introduction/images/more_detailed.png b/version-control/introduction/images/more_detailed.png index fcc3a27c..8c9df927 100644 Binary files a/version-control/introduction/images/more_detailed.png and b/version-control/introduction/images/more_detailed.png differ diff --git a/version-control/introduction/images/see_revision_history.png b/version-control/introduction/images/see_revision_history.png index f30beb89..7cee17fe 100644 Binary files a/version-control/introduction/images/see_revision_history.png and b/version-control/introduction/images/see_revision_history.png differ diff --git a/version-control/introduction/images/wikipedia-diff.png b/version-control/introduction/images/wikipedia-diff.png index a973b7bc..b0ba1625 100644 Binary files a/version-control/introduction/images/wikipedia-diff.png and b/version-control/introduction/images/wikipedia-diff.png differ diff --git a/version-control/introduction/images/wikipedia-view-history.png b/version-control/introduction/images/wikipedia-view-history.png index 0c9b908d..9fb64614 100644 Binary files a/version-control/introduction/images/wikipedia-view-history.png and b/version-control/introduction/images/wikipedia-view-history.png differ diff --git a/version-control/introduction/tutorial.md b/version-control/introduction/tutorial.md index 261ace40..3304a3d1 100644 --- a/version-control/introduction/tutorial.md +++ b/version-control/introduction/tutorial.md @@ -1,25 +1,25 @@ --- layout: page -title: Introduction to version control and git +title: Introduction to Version Control and Git --- ## What is version control? -Version control is a way to manage and track any changes you make to your files. If you've been using online services such as Google Docs or Wikipedia, then you'll already have been working with documents and pages that use a version control system. +Version control is a way to manage and track any changes you make to your files. If you've been using online services such as Google Docs or Wikipedia, then you'll already have been working with documents and pages that use a version control system. -### Google docs revision history +### Google Docs revision history -Google docs, for example, keeps a revision history of any document you create and modify. +Google Docs, for example, keeps a revision history of any document you create and modify. Have a look [at this Google document](https://docs.google.com/document/d/10kHJKXHLa-V8G6vVQoDiS6cTPvJoXnj_-SDvfQdziFk/edit?usp=sharing). - Select to see the revision history (you must be logged in with your Google account to do that!) -![](images/see_revision_history.png) +![See Revision History](images/see_revision_history.png) - And the more detailed version -![](images/more_detailed.png) +![More Detailed Revision History](images/more_detailed.png) Scroll through the revisions, from the bottom up. You should be able to see each set of changes highlighted in green. @@ -29,130 +29,108 @@ Wikipedia also holds a history of all changes. - Go to [this document](https://en.wikipedia.org/wiki/Women_in_computing) - Click **view history** -![](images/wikipedia-view-history.png) +![Wikipedia View History](images/wikipedia-view-history.png) - Try and have a look at the first revision of the page, by going back. It's dated back to 2005! - Click **curr**, that will show you the [differences between the first and the latest entry](https://en.wikipedia.org/w/index.php?title=Women_in_computing&diff=583521812&oldid=19298328) -![](images/wikipedia-diff.png) +![Wikipedia Diff Example](images/wikipedia-diff.png) ## Why do you need Version Control? - When used on a regular basis, version control helps you to store your files safely. It makes it easy to figure out what broke your code, as you can roll back to a previous version and work out when things last worked as expected. - - With no version control in place you'll only have one copy of your file, then when it breaks there's no way to get back to good code! + - With no version control in place you'll only have one copy of your file, then when it breaks there's likely no way to get back to working code! - It is also helpful when working with other people as it combines all the changes together and tracks who, why and when it changed. - In the work environment this may be essential to know for example, what issue the change fixes or customer requirement it relates to. ## Code version control systems -There are a number of different version control systems. The most popular ones are **svn** (or Subversion), **cvs**, **Mercurial** and **Git**. +There are a number of different version control systems. The most popular ones are **SVN** (or Subversion), **CVS**, **Mercurial** and **Git**. Some are paid for and others are free. -We will be using **Git**. +We will be using **Git** with **Github**: -### Why Git? +- **Git** is a tool that makes sharing code and collaborating with other developers easy. It also keeps our code tracked and safe. +- **Github** is the web based hosting service for our code repositories that we interact with through the Github web pages. -There are a number of reasons we chose Git, namely; +We'll use Git installed on our system to manage code we work on and then push our code to Github hosted repositories. -- A lot of learning resources are publicly available +### Why Git and Github? -- Does not require you to be connected to the internet to use +There are a number of reasons we chose Git and Github, namely; -- All your tracked changes stay on your machine until you are happy with them, and want to make them part of your codebase +- Lots of learning resources are publicly available -- Will tell you if someone has made changes since you last pushed code and urge you to update first and resolve issues - -- Github and online collaboration. Open source code is a big part of today's life. By being able to retrieve and help existing projects, you can also contribute to them - -Some popular projects using Git: - -- Android - -- Linux - -- Python - -- Ruby - -- PHP +- Git does not require you to be connected to the internet to use -# A bit more about Git +- All your tracked changes stay on your machine until you are happy with them, and want to make them part of your codebase on Github -## Terminology - -As with any technology and related tool, there's a lot of terminollgy used. Here's some of the most common terms and their definitions: +- Will tell you if someone has made changes since you last pushed code and urge you to update first and resolve issues -- **Repository**: A repository is where code is stored +- Github makes online collaboration easy. Open source code is a big part of today's life. By being able to retrieve and help existing projects, you can also contribute to them -- **Checkout**: When you retrieve code from a **repository**, to you local machine +### Projects on Github +Once you've worked through the Git and Github tutorials here at codebar, there are an incredible range of projects that you'll be able to access for free. These projects include operating systems, games, programming languages, books and more. -- **Commit**: Applying any changes you have made to the **repository** +- Go retro with a **Windows 95** simulation: [https://github.com/felixrieseberg/windows95](https://github.com/felixrieseberg/windows95) -#### Aim for small and focused changes +- Learn more with free **Programming Books**: [https://github.com/EbookFoundation/free-programming-books](https://github.com/EbookFoundation/free-programming-books) -When using version control, you should commit every time you do a small piece of work, rather than working for hours in a row, changing too many things and then committing them is a great way to introduce issues that are hard to track down. +- Grab some free **Games** kept on Github: [https://github.com/leereilly/games](https://github.com/leereilly/games) -For example, if you want to change the position of an element, the colour of all the links on your page and the font size dimensions of all paragraphs, you should do three commits, using messages that describe what you are doing each time. +- Amazing **Android Apps** and learning resources: [https://github.com/Mybridge/amazing-android-apps](https://github.com/Mybridge/amazing-android-apps) -### Write meaningful commit messages +- Ideas for **cool projects** you can build or contribute to [https://github.com/open-source-ideas/open-source-ideas](https://github.com/open-source-ideas/open-source-ideas) -Every time you commit a change use a message that describes your change clearly. In a few months time you will have difficulty remembering why you applied a change if your messages say _changing some CSS_, _another commit_ or _more changes_ +- Grab a copy of an extensive **Git Cheatsheet** for reference [https://github.com/arslanbilal/git-cheat-sheet](https://github.com/arslanbilal/git-cheat-sheet) -Try using messages such as _repositioned image to look better on page_ or _resolved positioning issue for Firefox_. +To find more projects, just enter a search in Github and see what comes back! -# The next step! -Sign up to [Github](https://github.com/) +## Key Terms and Definitions for Git -Download [Github Desktop](https://desktop.github.com/) (for Mac or Windows). +As with any technology and related tool, there's a lot of terminology related to Git and Github. Here's some of the most common terms and their definitions: -## Now what? +- **Repository**: A repository is where code is stored, it can be a local or remote repository. Also called a 'repo' -Now that you have the Github client setup on your machine, we will spend some time adding what you have created in the HTML & CSS lessons to an internet repository! Before you start make sure the Github client is running and you are signed in. +- **Clone**: Copy a repository so you can pull it down to your local machine and start editing the code -1. Create a new repository by clicking the `Create New Repository` button +- **Pull**: Get the latest version of code from a reposity - ![](images/create-new-repository.png) +- **Push**: Send your code changes to the remote repository -2. In your text editor, open the directory you just created and create a README.md file with the following content: +- **Add**: Adds your chosen changes to the local Stage area, ready for a commit and push - _This is where I store the work I have done at codebar._ +- **Stage**: An index of changes you are preparing to commit to the repository -3. Go back to the Github client and commit the file by filling out the `Summary` field and hitting the `Commit to master` button - - ![](images/add-readme.png) +- **Status**: Shows the state of the working directory and the Staging area -4. Now, create a new branch called **gh-pages** +- **Commit**: Applying any changes you have made into the repository - ![](images/create-new-branch.png) -5. In the directory, create a subdirectory **lesson1** and move the **html** file you created at the first session and all the other relevant files and directories (e.g. /images) -6. Now, link the file from the root of your project by creating an `index.html` file and adding a link to the page +## Good Practices when Working with Git - ``` - Lesson 1 - Introduction to HTML - ``` - > Don't forget to rename index to whatever you have named your file! +### Aim for small and focused changes -7. Commit your changes to the gh-pages branch +When using version control, you should commit every time you do a small piece of work, rather than working for hours in a row. Changing too many things and then committing them is a common way to introduce issues that are hard to track down. What's more, it makes it harder to review changes you made and need merging into the current code base. - ![](images/commit-changes.png) +For example, if you want to change the position of an element, the colour of all the links on your page and the font size dimensions of all paragraphs, you should do three commits, using messages that describe what you are doing each time. -8. Once you committed your changes publish your work by clicking the `Publish repository` button +### Write meaningful commit messages - ![](images/publish-repository.png) +Every time you commit a change use a message that describes your change clearly. In a few months time you will have difficulty remembering why you applied a change if your messages say _changing some CSS_, _another commit_ or _more changes_. -9. View your work on the web! +Try using messages such as _repositioned image to look better on page_ or _resolved positioning issue for Firefox_. - To access your work, go to `http://.github.io/codebar` +### Always check for updates by others +When you come back to coding, be sure to `pull` any changes into your local repository that others may have committed to the repository since you last worked on the code. If there are changes you don't pull in you can get **Merge Conflicts**, where two sets of changes, the ones from other people and yours, need to be worked through to decide which change is kept. Resolving merge conflicts is notoriously tricky - small, frequent commits followed by a pull are a great way to avoid merge conflicts. -10. Repeat the process to list the rest of the tutorials you have worked on on the page as well. -## Bonus +## The next step -This is your personal page. Use what you learned in the previous lessons to style it, make it look pretty, and what we learned today to commit and publish your changes. +Get set-up with [Git and GitHub](../set-up/tutorial.html). ----- -This ends our _Introduction to version control and git_ lesson. Is there something you don't understand? Try and go through the provided resources with your coach. If you have any feedback, or can think of ways to improve this tutorial [send us an email](mailto:feedback@codebar.io) and let us know. +This ends our **Introduction to version control with Git** lesson. Is there something you don't understand? Try and go through the provided resources with your coach. If you have any feedback, or can think of ways to improve this tutorial [send us an email](mailto:feedback@codebar.io) and let us know. diff --git a/version-control/set-up/images/git-and-github-logo.png b/version-control/set-up/images/git-and-github-logo.png deleted file mode 100644 index af9a4b05..00000000 Binary files a/version-control/set-up/images/git-and-github-logo.png and /dev/null differ diff --git a/version-control/set-up/images/setup-add-a-repository.png b/version-control/set-up/images/setup-add-a-repository.png new file mode 100644 index 00000000..f71c1855 Binary files /dev/null and b/version-control/set-up/images/setup-add-a-repository.png differ diff --git a/version-control/set-up/images/setup-add-new-ssh-key.png b/version-control/set-up/images/setup-add-new-ssh-key.png new file mode 100644 index 00000000..bfb3bbf9 Binary files /dev/null and b/version-control/set-up/images/setup-add-new-ssh-key.png differ diff --git a/version-control/set-up/images/setup-choose-pricing-plan.png b/version-control/set-up/images/setup-choose-pricing-plan.png new file mode 100644 index 00000000..7eb69005 Binary files /dev/null and b/version-control/set-up/images/setup-choose-pricing-plan.png differ diff --git a/version-control/set-up/images/setup-copy-a-repository-url.png b/version-control/set-up/images/setup-copy-a-repository-url.png new file mode 100644 index 00000000..f95c33db Binary files /dev/null and b/version-control/set-up/images/setup-copy-a-repository-url.png differ diff --git a/version-control/set-up/images/setup-get-a-github-account.png b/version-control/set-up/images/setup-get-a-github-account.png new file mode 100644 index 00000000..b5e5cd20 Binary files /dev/null and b/version-control/set-up/images/setup-get-a-github-account.png differ diff --git a/version-control/set-up/images/setup-github-settings.png b/version-control/set-up/images/setup-github-settings.png new file mode 100644 index 00000000..ae42d860 Binary files /dev/null and b/version-control/set-up/images/setup-github-settings.png differ diff --git a/version-control/set-up/images/setup-new-repository-details.png b/version-control/set-up/images/setup-new-repository-details.png new file mode 100644 index 00000000..fffeac6a Binary files /dev/null and b/version-control/set-up/images/setup-new-repository-details.png differ diff --git a/version-control/set-up/images/setup-paste-key-text.png b/version-control/set-up/images/setup-paste-key-text.png new file mode 100644 index 00000000..82b178bc Binary files /dev/null and b/version-control/set-up/images/setup-paste-key-text.png differ diff --git a/version-control/set-up/images/setup-pid-number.png b/version-control/set-up/images/setup-pid-number.png new file mode 100644 index 00000000..1931fa02 Binary files /dev/null and b/version-control/set-up/images/setup-pid-number.png differ diff --git a/version-control/set-up/images/setup-rsa-key-generated.png b/version-control/set-up/images/setup-rsa-key-generated.png new file mode 100644 index 00000000..1184c0f4 Binary files /dev/null and b/version-control/set-up/images/setup-rsa-key-generated.png differ diff --git a/version-control/set-up/images/setup-ssh-key-option.png b/version-control/set-up/images/setup-ssh-key-option.png new file mode 100644 index 00000000..4cfd6b79 Binary files /dev/null and b/version-control/set-up/images/setup-ssh-key-option.png differ diff --git a/version-control/set-up/images/setup-success-authenticating.png b/version-control/set-up/images/setup-success-authenticating.png new file mode 100644 index 00000000..e8d97978 Binary files /dev/null and b/version-control/set-up/images/setup-success-authenticating.png differ diff --git a/version-control/set-up/tutorial.md b/version-control/set-up/tutorial.md new file mode 100644 index 00000000..e66a1072 --- /dev/null +++ b/version-control/set-up/tutorial.md @@ -0,0 +1,165 @@ +--- +layout: page +title: Set-up Git and GitHub +--- + +**PREREQUISITES:** +- Understanding of version control ([Introduction to Version Control and Git](../introduction/tutorial.html)) + +## Introduction to Git and GitHub +----- +Now that we know what Version Control is, let's get set-up with Git and Github. By the end of this tutorial we'll have installed Git, set-up a Github account, created SSH keys that we can use to authenticate between the two, then finally created and cloned a repository for us to start working on our own projects and contributing to others. + +## Install and Set-up Git +Install command line Git for your operating system ([OS X](https://sourceforge.net/projects/git-osx-installer/), [Windows](http://msysgit.github.io/) or [Linux](https://git-scm.com/download/linux)) and open a terminal / command prompt. + +Once installed check Git commands works by typing the following in the terminal window. + +```bash +$ git --version +``` +This will return the version of Git you've installed and prove it's up and running correctly. + +### Create an empty Git repository +Now create a directory where you will be storing all your projects, by typing the following lines and hitting enter after each. You can call the directory whatever you prefer, such as `code` or `projects`. + +```bash +$ mkdir practising-git +$ cd practising-git +$ git init +``` + +> The first command above will make a new directory (`mkdir`) at the system location you're at within the terminal window. The second command will change directory (`cd`) into the new one you just made. The third command will call the Git program then initialise (`init`) your directory as a local Git repository + +### Set-up your Git account details +When we make a commit to a respository we need to associate it with ourselves. To do that we can tell Git our Github account username and email address. Type the following lines in the terminal window. + +```bash +$ git config --global user.name "Your Name" +$ git config --global user.email "name@domain" +``` + +### Set-up a SSH keys +In order to connect to and work with the host of a remote repository you'll need a way to prove who you are before a secure connection is allowed. If you think you may already have SSH keys set-up or just want to see what you have in place, use the following command. + +```bash +$ ls -al ~/.ssh +``` +> Notice this is a command line statement, not a Git statement. +> In the consoole window look for files named `id_rsa` and `id_rsa_pub` + +There are two files to be generated as one is the Private Key that resides on your system and the other is the Public Key that can be shared and added to various services, such as Github, as the other part to authenticate you with. + +**# Generate SSH Key Pairs** + +Open a terminal window and enter the following command. + +```bash +ssh-keygen -t rsa -b 4096 -C "your_email@here.com" +``` + +When prompted to `Enter file in which to save the key`, just hit `[ENTER]` on your keyboard to accept the location shown. If there are already keys in that location you'll be asked if you want to overwrite them. Hit `y` or `n` as appropriate. + +You'll then be asked to `Enter passphrase` and to reconfirm it - choose a secure one - then hit `[ENTER]` after each prompt and the keys will be generated, along with your password and email as a label. + +![RSA Keys Generated](images/setup-rsa-key-generated.png) + +**# Add SSH Keys to the ssh-agent** + +To avoid having to provide a password every time we connect to a service we can use the ssh-agent on our system. This agent handles passwords for ssh private keys and connections to the remote service we're logging into. This avoids having to send passwords over the network to the service. + +Check if the ssh-agent running by typing the following command + +```bash +eval "$(ssh-agent -s)" +``` +This should return the PID for the ssh-agent which means it has been started in the background. + +![PID Number](images/setup-pid-number.png) + +Now add the ssh keys to the ssh-agent by typing one of the following depending on your system. +```bash +Windows: ssh-add ~/.ssh/id_rsa + Mac: ssh-add -K ~/.ssh/id_rsa +``` +> The -K option is Apple's version of `ssh-add` which adds the passphrase to your keychain for when you add the key to the ssh-agent + +You can check what identities have been added to the ssh-agent by typing: +```bash +ssh-add -l +``` + +## Set-up and Connect to a Github Account +Now that we have Git working on our local system and the SSH keys we'll need in order to connect to a remote service, let's set-up the Github account so we can then finish connecting the two. + +### Sign-up for a Github Account +Navigate to [https://github.com/](https://github.com/) and from the home page sign-up for an account. + +![Sign-up for a Github account](images/setup-get-a-github-account.png) + +Be sure to choose the free pricing plan. + +![Github Free Pricing Plan](images/setup-choose-pricing-plan.png) + +Once you've verified your email address the account will be active and you can go back to edit your profile later on. + +### Add the SSH Key to Github + +Now we have both Git and the SSH keys set-up on our local system and a Github account created so we can have access to hosted repositories, we need to link them together using the SSH keys. + +Navigate back to github.com and ensure you're signed-in to your account. Then in the top right corner click on your profile photo and select `settings`. + +![Github Settings](images/setup-github-settings.png) + +In the Settings sidebar, select the `SSH and GPG Keys` option. + +![SSH option is Settings](images/setup-ssh-key-option.png) + +On the right hand side, select `New SSH Key` which will present you with an area to paste your public SSH key text into. + +![Add new SSH Key to Github](images/setup-add-new-ssh-key.png) + +We need to copy to the clipboard the contents of the `id_rsa_pub` file we created earlier. In a console window type the following command. +```bash +pbcopy < ~/.ssh/id_rsa.pub +``` +Now return back to the browser where your Github account is open. Give the SSH key a `Title` and paste the file contents into the `Key` field. When done, hit the `Add SSH Key` button. You may be prompted for your password, if so enter it and hit `Confirm Password` to complete this step. + +![Adding Key text and title](images/setup-paste-key-text.png) + +You can check your connection to Github is set-up correctly by typing the following command, which should give you the message in the console window shown below. + +```bash +ssh -T git@github.com +``` + +![Authentication success](images/setup-success-authenticating.png) + +## Create a Github Repository + +Now that we're all set-up with Git and Github, and we've set-up a folder on our local system that's been initiliased as a Git repository - we just need to add a remote repository on Github that we can commit our local files to. + +In your home page on Github, click on `Repository` and then `New` to start adding a new repository. + +![Add a respository](images/setup-add-a-repository.png) + +On the next page complete the details for the `Respository name` and a `Description`. Set the visibility to `Public` and initialise with a README file so you can easily add a description and notes about the repository. It's recommended that you choose a license type too, MIT License is fairly common for open source work. When you're done, hit the `Create Respository` button. + +![Set up new Respository details](images/setup-new-repository-details.png) + +The respository will now be set-up with your readme and license files. It will also have a Github URL available to copy and use in Git when making a commit. + +![Copy a respository URL](images/setup-copy-a-repository-url.png) + +For Git to know where we want files to go when we do a `git push` of items in our local respository, we need to add a reference to that repository. Enter the following command in a console window and be sure to add the URL you copied from Github. + +```bash +$ git remote add origin +``` +## The next step + +Learn more about the [Git Command Line](../command-line/tutorial.html). + +----- + +This ends our **Set-up Git and GitHub** lesson. Is there something you don't understand? Try and go through the provided resources with your coach. If you have any feedback or can think of ways to improve this tutorial [send us an email](mailto:feedback@codebar.io) and let us know. \ No newline at end of file