In this chapter, you will learn how to create an account on GitHub, and how to create and clone your first repository so that you have a link between the repository on your computer and that on GitHub.

This chapter will cover:

• Creating your repository
• Git pull
• Push me, pull you
• Starting at the command line
• Commits – best practices

We'll start by creating your GitHub repository.

There are a number of different ways to create your repository. We'll cover creating a repository on GitHub and cloning it to your disk, as this is the most common way.

Creating your repository on GitHub first

Your first step is to register with GitHub. Go to http://github.com and click Sign Up. Fill in your username (it will tell you if the name is taken) and your email and it may ask you to verify that you are a human. Assuming you are, click Create Account.

Fill out their micro-survey and click Create Account. You will be asked to verify your email, and once you do, you'll see the (one-time) opening page asking what you want to do first. Choose Create a repository:

Figure 2.1: Getting started with GitHub

If you already have an account, sign in and press New Repository. You may not find this at first glance, in which case click the big plus sign in the corner.

Either way, you will be brought to the Create A New Repository page. The first job is to give your new repository a name. I'll use ProGitForProgrammers. Feel free to use any name you want as long as GitHub doesn't complain that the name is taken.

Now it is time to fill in the form:

Figure 2.2: Creating the repository

Start by entering a short description of your project. Next, and very importantly, choose whether you want this repository to be public (anyone can see it) or private (only people you invite can see it).

I strongly recommend checking Add a README file. This will be what is shown to users when they come to your repository. You can fix the file up later using Markdown.

Be sure to add a .gitignore file. This tells Git which files to ignore when checking your files into the repository. This can be very important so that you don't overwrite another programmer's metadata files. Click the dropdown and admire how many languages are supported; for C# I recommend you search for and choose Visual Studio.

If your repository is public, be certain to choose a license for the code. I chose the MIT License. You can learn more about this license at https://opensource.org/licenses/MIT.

That's it! You are ready to click Create repository. When you do, you'll be brought to the home page for your new GitHub repository:

Figure 2.3: Initial view of your repository

Notice that you have the three files you asked for, and that you can see a preview of the README as well as the description you entered.

Right now, this repository exists only on the server. You want to put a copy on your disk so that you can add code and use commands to keep them in sync. Therefore you will "clone" the repository; that is, you'll make an exact copy of the remote repository in your local repository.

How you will do this will depend on whether you are using the command line, Visual Studio, or a GUI.

Cloning to your computer – command line

Cloning to your local repository is easy. Open your terminal (or PowerShell) and change the directory to where you want the repository to go (in my case GitHub/the command line).

Switch back to your GitHub repo on GitHub.com, and see the green button in the upper right-hand corner marked Code. Click that button and a small dialog box will open. Choose HTTPS unless you know you have SSH (as I do). In either case, click on the clipboard icon to copy the address:

Figure 2.4: Copying the address of the repo

Return to the command line, enter git clone, and then paste in the address:

git clone [email protected]:JesseLiberty/ProGitForProgrammers.git

You should see something like this:

Figure 2.5: Cloning at the command line

Change the directory to ProGitForProgrammers and you'll see that the three files that were on the server are now here as well:

Figure 2.6: Files in the directory

Now let's take a look at how to do this in Visual Studio.

Cloning to your computer – visual studio

Go to your directory (in my case GitHub) and make a directory called VisualStudio.

Open Visual Studio with no project. Select File | Clone Repository. Fill in the fields and click Clone:

Figure 2.7: Cloning to your local repository using Visual Studio

A few seconds later you will see the three files, now shown in the Solution Explorer:

Figure 2.8: Cloned files in Visual Studio

There are a number of ways to clone from a GitHub repository to your own. One way is to use a dedicated GUI tool such as GitHub Desktop.

Cloning to your computer – GitHub for Desktop

Once again, return to your root directory (GitHub) and make a new directory. This time call it GitHubDesktop.

Now, return to GitHub and click Code:

Figure 2.9: Cloning directly through GitHub Desktop

Notice that one of the choices is Open with GitHub Desktop. Click on that. A dialog will open. The only field you need to fill in is the local path. Click Clone:

Figure 2.10: Cloning to GitHub Desktop using HTTP

You now have three copies of your original repository, each in its own directory: CommandLine, VisualStudio, and GitHubDesktop. These might represent three programmers working on the same solution, or various ways for one programmer to choose to clone their project.

Creating a project

We need a project. Using Visual Studio (or your favorite editor) create a project called ProGitForProgrammers in the CommandLine directory. When you are done, you should have the three original files and a folder for your program. In that folder will be the .sln file as well as a folder for the code.

Open the command line and navigate to the same directory. When you get there your command line should look something like this:

Figure 2.11: The command-line prompt

Look at the yellow, where you see +1 ~0 -0. The +1 means you've added a file or a directory; the ~0 indicates that no files have been modified; the -0 indicates that no files have been deleted. Let's see what was added. Enter:

git status

You should see something like this:

Figure 2.12: Untracked files

Git is telling you that you are on the branch main (the only branch for now) and that you have "untracked files" – that is, files that are in the directory but that are not being tracked by Git. If they are untracked, Git can't store them; in fact, Git knows nothing about them. Let's fix that. Enter these commands:

git add ProGitForProgrammers/
git commit -m "First commit – from command line"

add tells Git that this is a file it should pay attention to and commit brings it into the local repository.

Every commit must have a message, and if you don't provide one, you'll be prompted by Git to add one. Here I've added it by using the -m flag.

Once again, all this is happening locally and so GitHub doesn't know about it. We can fix that by pushing our commit up to the server:

git push

Now if you go to GitHub and refresh the page your project will be there. You can click your way down through the folders, and even into Program.cs, to see the code:

Figure 2.13: Viewing your code on GitHub

Notice in the upper left that it tells you that you are on the main branch. Next to that is the path to get to Program.cs. Below that is the message you added, and then the file itself.

Having pushed your commits to the server, other developers may want to pull them to their own directory, to keep in sync.

Pulling down using GitHub Desktop

Having put the project up on the server, we can simply pull it down into the other locations. For example, open GitHub Desktop. It will tell you that there have been changes in the repository and helpfully offer a button for you to update your local repo.

If you open a file explorer and navigate to the GitHubDesktop directory, you'll see that there is now a replica of the files you pushed from the command line.

Pulling down to Visual Studio

Click on the Git menu and choose Pull. Visual Studio is updated with the code from the server. Now all three repositories are up to date. This is the heart of Git:

• Save your files to a local repository
• Push your files to the remote repository
• Pull down any files that are on the remote repository but not on your local repository

Generally, you want to push your changes and pull down changes from other developers. Also, generally, you will not be working on the same files, and certainly not in main. We'll discuss how to avoid this in Chapter 4, Merging Branches. For now, we'll just be very careful.

Open Visual Studio in the directory GitHub/VisualStudio/ProGitForProgrammers. Add a line to Program.cs as shown here:

namespace ProGitForProgrammers
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
           Console.WriteLine("I just added this in Visual Studio");
        }
    }
}

Having made your change, you want to check it in. Since we are in the VisualStudio directory, we'll do the work right within Visual Studio. Click the Git menu and choose Commit or Stash. A Git window will open as a tab next to Solution Explorer. Enter a commit message and press Commit All:

Figure 2.14: Git window in Visual Studio

As you can see, and will see often in this book, you can do almost anything in Visual Studio that you can do at the command line.

Pushing to the server

You have now committed your changes to your local repository. The GitHub repository, however, doesn't know about your changes. (You can prove this to yourself by returning to GitHub and drilling down to Program.cs.)

The other programmers' repositories (for example, CommandLine and GitHubDesktop) are equally oblivious. To disseminate this change, you first push your changes up to the server (GitHub) and then pull them down to the other repositories.

From within Visual Studio's Git window, press Staged. This will stage your changes for committing. Next, click Commit. This will put your changes into your local repository (be sure to give the commit a meaningful message).

Examine the Git window; there is a lot of information:

Figure 2.15: The Git window in Visual Studio

You are told that the commit was created locally (and locally is the important part!). Below that is the status of your commit. You have one to push up to the server (outgoing) and none to bring down (incoming):

Figure 2.16: Uploading a commit from Visual Studio

Now, find the up-pointing arrow in the upper-right corner. Hover over it and you'll see that it says Push. Click that button to push your changes to the server. When it is done, it will give you a success message. Ignore the offer to create a pull request for now.

Look to the left of your Git menu and see the local history of your commits:

Figure 2.17: The history of commits

Each dot signals a commit, and next to each dot is your commit message (and now you can see why meaningful commit messages are both hard to write and worth the effort). There is also an indicator that main is pointing to your last commit.

If you check GitHub (remember to refresh the page) you will now see the line in Program.cs. Make sure you understand why: this is because after we committed the change, we pushed it to the remote repository.

Downloading the changes at the command line

We created the changes in the VisualStudio directory. CommandLine and GitHubDesktop know nothing of the changes, even though they are now on GitHub.

For these directories to know about the changes, you need to pull the changes down.

Change directories to CommandLine. Examine the contents of Program.cs; the new line is not there. Open your terminal and enter pull. This will pull any changes from the server to your local repository.

The result should look like this:

Figure 2.18: Pulling from the remote repository

Git is telling you that it formatted and compressed your files and passed them down to your repository. Toward the bottom it says that it used Fast-forward. We'll discuss this in Chapter 4, Merging, Pull Requests, and Handling Merge Conflicts.

Take a look at Program.cs now in your command directory; the new addition should now be there.

Downloading the changes using GitHub Desktop

Change directories to GitHubDesktop and open the GitHub Desktop program. It will give you a lot of information about the status of your repository (No Local Changes) and it will automatically check and inform you that there is one commit to update your local repository with:

Figure 2.19: The view from the remote repository

Go ahead and click Pull origin. It does the pull, and the button disappears. Check your code; the change should now be in your Program.cs (and is recorded in your local repository).

You can start the process at any of our repositories. Last time we started in the VisualStudio repository and then pulled the changes down to the CommandLine and GitDesktop repos. This time, let's start at the command line.

Open Visual Studio and point it to the project in your CommandLine directory. Just to be certain, right-click on Solution, select Open Folder in File Explorer, and make sure you are in the right directory.

To keep this example very simple, we'll just add another line to Program.cs:

class Program
{
    static void Main(string[] args)
    {
        Console.WriteLine("Hello World!");
        Console.WriteLine("I just added this in Visual Studio");
        Console.WriteLine("I just added this in the command line repo");
    }
}

Normally you would make many more changes before checking in, but again, this is a demo and we're more interested in using Git than we are in fussing with this silly program. Save all your files and at the command line get the status by entering:

git status

This will give you output that looks like this:

Figure 2.20: The command line indicating one file has been modified

The key piece of information is the modified file. That is just as it should be, as that is the file we modified. You can now add it to the index and then commit it:

git add ProGitForProgrammers/ProGitForProgrammers/Program.cs
git commit -m "Add writeline indicating we are in command line"

On the other hand, you can combine these two steps with the -a flag:

git commit -a -m "Add writeline indicating we are in command line"

You will want to draw a distinction between untracked files and modified files. Untracked files are outside of Git and cannot be manipulated inside Git until they are added; modified files are tracked by Git but have changed since the last commit.

If we are happy with the commit we've added, we can (optionally) push it to the server:

Figure 2.21: Pushing our commit to the remote repository

We'll want to do that because we want to share this code with the other programmers.

Pulling to GitHub Desktop

Switching to GitHub Desktop, we see that it already knows there is something to pull, as we saw last time. (If it doesn't, push the Fetch button, which will go to the server to see if there is anything to bring back.)

That's two repos that are identical, but the VisualStudio repo is not yet up to date. Let's return to Visual Studio in the VisualStudio folder.

Pulling to Visual Studio

Open the Git menu item, and select Pull. Watch your source code and see the third line pop into existence. Once again, the three local repositories and the remote repo are all in sync.

Like everything else in programming, best practices in commits are, to some degree, controversial. The first issue is frequency.

How often should I commit?

There are those who say a commit should be atomic: representing exactly one unit of work (one task, one bug fix). No more and no less. So, according to this line of thought, if you are in the middle of work and you get called away, you should not commit, but you should use the stash. The stash is an area where you can put files that you want to come back to later. You can name sets of files that you stash, and then pick the one you want to restore by name.

This is a defensible position, but I hold the opposite: commit early and commit often.

Commits are cheap and fast in Git, and interactive rebase (see Chapter 6, Interactive Rebasing) allows you to "squash" commits together. Therefore, if you are working on a feature and you make five interim commits before you are done, you'll have the opportunity to squash them into a single commit with a single message. This is the best of both worlds: you secure your interim work with a commit, and you present only one commit (rather than five) to the server.

Keep your commit history clean

The first way that a programmer reviews your code is to look at the list of commits and then dive into those that are interesting. A good history of commits with well-written messages is a delight to review. A long, tedious history with meaningless messages is only slightly more fun than eating glass.

A note on commit messages

As you will see later in this book, commit messages are very important for anyone (including you) reviewing your commit history. By convention, commit messages should be in the imperative, and should tell you exactly what is in that commit.

Fixing some files                        // bad
Fix WriteLine in helloworld.cs           // good

In practice you'll often find comments in the past tense:

Fixed WriteLine in helloworld.cs         // good enough

"In theory, theory and practice are the same; in practice, they never are." -- Pat Johnson

It pays to get into the habit of writing good messages in the right format. Your teammates will thank you.

When the title isn't enough

The message title should be kept to 50 characters. Most of the time this is enough, but if it isn't, leave the -m message off and let Git open your editor. There you can add additional information. Skip a line after the header and consider using bullet points or other ways of making the things you want to convey easy to read.

Important: By default Git uses vi (a Unix editor). You'll want to enter:

git config ––global core editor "code -w"

This ensures that Visual Studio Code is your default editor:

Figure 2.22: Editing in Visual Studio Code

Note that # is the comment character, and all lines that begin with # will be ignored.

When you use log (see Chapter 9, Using the Log) to see your history (or view history in Visual Studio, etc.) you'll see the entire message:

Figure 2.23: The output of the log command

You can see just the headers if you want, using git log -–oneline, but we'll leave the details for Chapter 9, Using the Log:

Figure 2.24: log using the oneline flag

In this chapter, we have covered a number of topics relating to creating and interacting with your repository. We discussed:

• Creating your repository
• The relationship between your local and remote repositories
• Git pull
• Git push
• Starting at the command line
• Using Visual Studio
• Commits: best practices

In the next chapter, we'll take a look at the various places Git keeps your files, and the relationship between adding an untracked file and committing a tracked file.