This chapter introduces you to using Git. Git is the most amazing source control versioning system (a source control system allows you to track the various versions and edits of all your code files) for files that I’ve ever used, and it’s the source control system the Drupal community has favored for a number of years. (drupal.org previously used svn and prior to that cvs.) In this chapter you’re also going to be looking at using github.com. Github is a vendor that hosts Git repositories. It is free for shared code (code that is made public to the world), but Git charges a fee for private repositories. As you probably know by now, the code for this book is kept at Github: https://github.com/barnettech/drupal8_book. You’ll practice managing your files using Github, and you’ll also learn several useful Git commands for working with your files.

Introducing Git

Git allows folks to work on the same project (code base) by managing versions of each file, including any conflicts that occur when users co-author a file.

Git allows you to easily create branches (versions of the code, essentially). That means you can safely set up a branch for development work, a branch for experimental coding and projects, a branch for production, and a branch for anything else you can think of. When you’re done developing a piece of code, you can merge it from the development branch into the production branch. Or maybe you also have a staging branch—when finished you can merge your code into that staging branch for your quality assurance (QA) team to evaluate the code to make sure there aren’t any bugs, to make sure your new feature is ready to rock in production. Then, once the QA team gives the green light to the code in your staging branch, you can merge the code into the production branch.

Once there’s a new version of the production branch ready to show on your live site, you can create a tag in Git, which is a non-editable snapshot of your code at that point in time. No commits (changes to the code) can be deleted or added to a tag. You will need to create a new tag to make any changes, and then the new tag can be put into place for the live web site to serve up pages.

There are lots of workflows on moving code from development to production utilizing Git as the center to manage files and keep your files versioned and backed up safely. I’ve seen many shops that have developers create a new temporary branch for each ticket they are working on; then, when they are done, they merge their branch back into the primary development branch.

Installing Git

First you’ll need to install Git on your machine. This chapter has installation instructions for Git on every platform: http://git-scm.com/book/en/Getting-Started-Installing-Git.

Installing Git on a Mac

Figure 15-1 shows the instructions for installing Git on a Mac. Basically, you can just go to https://code.google.com/p/git-osx-installer/ and download the OSX installer. Figure 15-1 shows the official Git documentation online e-book, which is really good and contains detailed instructions. I recommend looking at this free e-book for in-depth information about using Git.

Installing Git for Windows

Figure 15-2 shows instructions for installing Git on Windows, again from the official Git e-book. This chapter gives you the fast-track tour to getting up to speed in using Git for source control, but the e-book is great and serves as another great recourse to continue learning Git.

The installation process is straightforward—go to http://msysgit.github.com and download the installer. Note, however, that installing Git on Windows is a bit trickier than installing it on a Mac. On a Mac you install Git and then it’s ready to use in a Terminal window, but on Windows, Git will not be available from your regular command prompt. Follow these steps to get a command prompt in Windows that will accept Git commands (see Figure 15-3):

1. Click Start and then click All Programs. Click Git Bash.
2. Once the Git Bash program opens, use Linux commands to cd into the Drupal root directory.

   cd Sites/acquia-drupal/modules

Although the Git Bash program command window is small in Figure 15-3, basically, once you have the Git Bash command window open, you can enter Linux commands as usual. Now you’ll also be able to type in Git commands as well, and they will be accepted just as all the other basic Linux commands are (i.e., git status, git commit, git update).

Now you’re ready to create your custom and contrib directories (see the next section on downloading the book’s code). Please note that in the rest of the chapter if you’re running Windows you will need to be within this Git Bash program to issue your Git commands.

Installing Git with Linux

There are also instructions on http://git-scm.com/book/en/Getting-Started-Installing-Git to install Git on a non-OSX Linux box (see Figure 15-4). The following URL (uniform resource locator) has the files needed to install Git on non-OSX Linux machines: http://git-scm.com/download/linux:

Now that you’ve successfully installed Git on your machine, you’re ready to create an account on Github.

Creating an Account on Github and Downloading the Book’s Code

Once you have Git installed, create an account on https://github.com/. Then complete the following steps to use Git to download this book’s code onto your local machine:

1. Go to the root of your Drupal code. On my Mac, my Drupal 8 test installation root folder is located at /Users/jbarnett/Sites/drupal8/.
2. Next, type the following:

   cd modules

3. If you already have a custom and contrib directory within this modules directory, then you’re ready to proceed to step 4. Otherwise create these two directories now by typing

   mkdir custom
   mkdir contrib

4. Change directories to go into the custom directory.

   cd custom

5. Type the following, making sure to include the ending period:

   git clone https://github.com/barnettech/drupal8_book.

The preceding command will create the hello_world  directory from the examples in the custom directory. If you just type in the command without the period (.) at the end, the drupal8_book  directory will be created in your custom directory, and then within that directory, you’ll see the hello_world  module directory. Now go poke around—you’ll see you have all the files from the book.

You’ve now cloned (copied) the repository I’ve made for this book, called drupal8_for_absolute_beginners. A clone of a repository allows you to view all the source code within the repository, and it allows you—if you have the proper permissions—to add edit and add to the repository.

Now take a look at all the branches in this repository. I’ve used branches in this repository not to separate development, staging, and production code but to separate the code into different versions of the code as needed for different sections of this book. You can use branches for anything you deem fit. Take a look at Figure 15-5 and you can see in Github, which has a great interface for browsing Git repositories, all the different branches that currently exist for this repository.

The master branch is usually the base branch, and I’ve seen many people use it as their development branch. drupal.org does not use the master branch for any project because there is always a different version of Drupal like Drupal 6, Drupal 7, or Drupal 8, so using the master branch would have been confusing; it wouldn’t signify which branch (version) of Drupal you were in within Git.

In the repository I’ve set up for this book, I’ve made the branch names to be relatively telling of what the code covers. The with_js branch is the Hello World module but with the addition of showing how to add JavaScript to the module, the with_css branch is the basic Hello World module but with some basic code to show how to add CSS to the module, and so on.

So, at your command-line prompt where you did your clone of this book’s repository, type the following:

git branch

Now Git will tell you what branch you’re on by showing all the branches available on your local machine, including the current branch. The branch that is currently present in your directory will show with a little asterisk next to it (see Figure 15-6).

This is a list of all the branches currently in your local Git drupal8_for_absolute_beginners repository. Git is a decentralized system, which means your local repository could actually, if you chose it to, become the new primary “origin” which all other users check their code into. This is a central difference between Git and previous source control systems. The decentralized nature of Git means it’s easy to fork (split off projects). That means developers can share projects and fork projects to go in a different direction and create their own versions of the code.

If you type in

git remote show origin

you can see what the primary Git repository URL is, which is known as the “origin.” When you add to the code base, you will push (upload) your changes to the “origin” so that your co-developers can pull (download) your changes. This makes it so that you can collaborate on the project using the “origin” as the place where everyone shares his or her changes. Also, after running the command git remote show origin, you can see all the branches available on the “origin.” These branches didn’t show up when you did a git branch command in your machine’s file system.

Now let’s say I want to check out the code for branch with_css. I would type in the following:

git checkout with_css

Then when I type in git branch again. I will see two branches listed, both master and the with_css branch—but now the with_css branch has the asterisk next to it, meaning my current code reflects what’s in the with_css branch.

If you now poke around the hello_world directory on your local machine, you’ll see the code within the directory has changed. It now has the version of the Hello World module that demonstrates adding CSS to the module. See Figure 15-7 to see what this looks like in a Terminal window.

Now that you’ve created a Github account and learned to navigate the various branches of this book’s code repository, let’s take a look at how to create a Github repository and make changes to your code.

Using Git to Contribute to a Project

In this section we’ll cover how to edit code or add new code and add it or update the git repository both on your local machine and then also at the “origin” where you can push your code to and everyone can share changes to jointly collaborate on a project. Take a few minutes to work through the following exercise, which will walk you through the steps of creating your first Github repository and show you how to navigate through the various files and branches of the repository.

Creating a Github Repository

Before you can create a Github repository, you need to log in to your Github account. Then, complete the following steps:

1. Click the New repository button (see Figure 15-8).

   

   Figure 15-8. Creating a new Github repository

2. Clone the repository to your local machine by typing in the following command. I called my new repository git_playgound so on my local machine I typed the following (see Figure 15-9):

   git clone https://github.com/barnettech/git_playground

   

   Figure 15-9. Clone of the repository git_playgound from my Github account

3. Type in git branch. You’ll see you’re on the master branch (the asterisk is next to the word “master”). We haven’t added any branches yet.
4. To create a new branch based on the master, type

   git checkout –b testbranch

   This will create a new branch called testbranch. Initially, it will be identical to the branch you were within when you issued the command, in this case the master branch.

5. Now type git branch. You’ll see the two branches: master and testbranch. Notice that testbranch now has the asterisk next to it. When you create a branch this way, it automatically switches you to the newly created branch.
6. Switch back to the master branch:

   git checkout master

7. Create a new file called firstfile.txt and add to the file whatever text you like with vi or your favorite text editor.
8. Add the following file to your local Git repository:

   git add firstfile.txt

9. Now type in

   git status

The git status command will show which files have been added or modified and are ready to commit (ready to save to the Git repository) (see Figure 15-10).

I did this Git status after modifying firstfile.txt. If I had done it right after first issuing the command git add firstfile.txt, it would have reported new file: firstfile.txt. The git status command can show you what files are ready to commit, or maybe if you were just experimenting, it can be a warning to you to be careful not to commit these experiments.

Now the file is a part of the repo (repository).

Navigating Your Github Repository

Earlier you staged the content you wanted to add to the repository with the Git add command. Now you’ll type in the Git commit command to actually record the snapshot of the changes to the repository. The commit command will record (save) any files added to the repo and/or any changes made to existing files in the repo.

 git commit –m "this is my first commit, I am adding
firstfile.txt to the repo" firstfile.txt

Now you’ve added firstfile.txt to the repository and you added a commit log message with the –m argument. If you omit the –m argument, you will be prompted to add a commit log message, which you can then do. Afterward the commit will finish and succeed. Figure 15-11 shows the Git commit.

Now when you go to Github, the file firstfile.txt will not be in the list of files. The file still exists only on your local machine, in your local Git instance of the git_playground repository.

1. To “push” the file to the “origin” machine, which in this case is a machine at Github, type the following:

   git push origin master

   This command will push all changes committed in the local repository you’re within, from master to the origin. If you were within another branch, like testbranch, you would have typed git push origin testbranch, which would push your changes to testbranch up to origin. At the origin (source), other developers will also be pushing files. Now when you go to Github, the file firstfile.txt will be there, as seen in Figure 15-12.

   In my example, you’ll notice that others committed to this test repository as well. You can see their commits in Figure 15-12.

   

   Figure 15-12. The newly added file showing in the remote repository (at Github)

2. In order to get changes and additions that others make to the repository on the command line where you cloned the repository, type the following:

   git pull

   After issuing this command, all the files changed (by other people) will be updated on your local machine and all new files added to the repo at Github will be brought into the local repository on your local machine.

   If there are any merge conflicts (conflicts with what another developer committed to the repository) that cannot be resolved by the computer, you will be alerted to the conflict. At this point, you would need to resolve any merge conflicts.

    Note  Github has some great documentation on how to resolve merge conflicts: https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line.

3. After you’ve safely committed all your new files to the “origin” computer (the remote computer—which in this case is at Github), you can actually within your repository type in

   rm *

    Caution  Make sure you are in the correct directory when you do perform this action.

   This action will delete all files in the present directory.

   Ok, so you just deleted all your files in your local repository. But fear not. Everything is safely stored and versioned in the Git repository.

4. To reset and bring all your files back to the most recent state with the latest commits, type

   git reset –hard head

   Now if you issue the command ls to list the files in your directory, they will all be there. You forced a reset of the repository back to “head,” which is what you call the “tip” of the branch you are on with the latest changes (the latest commits).

5. To create a tag, which is an unmodifiable snapshot of your code, type

   git tag tagname

To push your tag to origin, you could type git push –tags, which would push up all new tags to origin (to Github in this case), which you created in your local repository.

Often a production Drupal site is running off the code in a tag. It is safer to run production off a tag, because no one can modify it by mistake. And even if a new tag is put in place with changed code, you can always revert to using the old tag if there’s a problem. You can be safe in knowing that the old tag is there, unmodified, and can be used at any time.

Now that you’ve worked through quite a few of the essential Git commands, you’re well on your way to being well versed in Git usage. In the next section, I’m going to introduce you to some bonus commands that I find extremely useful.

More Great Git Commands

This section will introduce you to some other great Git commands I wouldn’t want to do without. First, trying typing in

git log

This command will show all of your previous commits as well as others’ commits (see Figure 15-13). The commits made to the system are listed in chronological order, with the newest commits listed first. When you see the colon (:), that means you can press the spacebar to see more commits.

Notice that each commit shows the commit, the commit unique id known as the “sha,” the author, and the date, followed by the commit log message. So in the commit shown in Figure 15-13 you see

commit 9c924a782214139e5a57cc056ea9539d80bd8e0f
Author: Barnett, James <[email protected]>
Date:   Thu Dec 5 10:17:15 2013 -0500

The sha in this case is the really long string of letters and numbers: 9c924a782214139e5a57cc056ea9539d80bd8e0f. You can do a lot knowing this sha. For example, type in the following:

git show 9c924a782214139e5a57cc056ea9539d80bd8e0f

This command shows you what exactly has changed in this particular commit (see Figure 15-14).

You’ll notice that the results in Figure 15-13 are really a “diff” of what has changed in this commit versus the previous version. A diff is just what it sounds like—a list of differences of what has changed.

Notice the “+” sign next to the text “This is a first file to test adding to the repository.” The “+” sign signifies this line as been added in this version. A “-” sign would indicate that the line had been deleted in this commit.

The git show command can be very useful in tracking down what changed, in what commit, and who made the change, so you can consult the individual on any problems that may have occurred after his or her commit. Or maybe you just have questions for whoever made the commit.

You can also revert a commit (reverse the commit) if you know the sha. You can type

git revert 9c924a782214139e5a57cc056ea9539d80bd8e0f

The preceding command would remove the changes made within this Git’s sha. This makes it easy to revert problems with a given commit (remove the problematic commit).

You can also create a branch based on that particular commit using the sha. Say a commit is a day old and you want to create a branch based on that old sha. You would type in

git checkout sha-of-commit -b new-branch-name

So let’s say we have two branches and I’ve made a commit in master but also want to bring the branch over to the second branch, which I’ve called branch2. First I grab the sha of the commit while still in the master branch by typing in git log. Then I see the following:

commit 5a1220d7fa3030bd89a4d7f33ec136b4983f9f54
Author: Barnett, James <[email protected]>
Date:   Thu Dec 5 11:49:22 2013 -0500

    adding change to bring over to show a cherry-pick

So I see that the sha of this commit is 5a1220d7fa3030bd89a4d7f33ec136b4983f9f54. Then I switch over to branch2 by typing in git checkout branch2 (see Figure 15-15).

Then, knowing the sha of the commit I want to bring over into branch2, I type in

git cherry-pick 5a1220d7fa3030bd89a4d7f33ec136b4983f9f54

Figure 15-15 shows the result.

Then the change is in my local repository, and I can proceed to do a

git push origin branch2

to push the changes to Github to be shared with my other coworkers (other developers on my project). For others to see your commits, remember you need to push them to the remote repository; if you don’t they’ll just be on your local machine. In this case the git push origin branch2 command pushes your changes to branch2 to the remote server for your coworkers to then be able to pull your changes, so they then can continue to modify the code, or they can just view what you’ve done. If you do a Git log in branch2, you’ll see the first log message is the same as it is in the master branch now.

commit 265d82d6f381540a8a672bb8c7ff77066e5cd3ef
Author: Barnett, James <[email protected]>
Date:   Thu Dec 5 11:49:22 2013 -0500
    adding change to bring over to show a cherry-pick

You can also move over a file or directory to another branch by using the checkout command. So if I’m in branch2 and I do an ls, I can see the testdir directory. If I want to bring over the testdir directory from master to overwrite what I have in the branch2 directory I can, within the branch2 branch, type in

git checkout master testdir

This will overwrite what I have in the testdir directory. If I then do a cd testdir, I will now be able to see that the files are the same as they are in the master branch. I can now, if I choose, commit this directory by going to the directory just above the testdir directory.

git commit testdir

This will commit the changes to the testdir directory to the local branch2 branch. Then I can type

git push origin branch2

This will push up my changes to Github. In the same way you can check out a whole directory, you can also just check out an individual file from another branch. So if I do an ls and see the file testfile_abcde.txt and want the version from master to overwrite the one in the branch2 branch I can type in

git checkout master testfile_abcde.txt

This technique is different from cherry-pick in that it pulls in a whole directory or whole file, and that file or directory may have a whole bunch of commits that differ from the branch’s version of the directory or file I’m overwriting. I find this useful sometimes to quickly bring over changes and I want to make sure the file on one branch matches the other branch. Although you do lose the commit log message when you do this, you can always refer back to the master branch where the original development and changes occurred to see the Git log history of how these changes were committed.

Checking Differences Between Branches and HEAD

It’s often useful to use commands to see the difference between files on one branch or another, or maybe just to check exactly what changes you’ve made before you commit them. I often use the following command:

git diff .

This command will show all changes made within the present directory and all subdirectories (see Figure 15-16).

Unlike a git status command, which just shows a list of files that have been added or modified, this command shows what files changed and the exact changes made. So in this case, there’s a -abcde  fghij, which means this line is now gone, but then there’s a +abcde fghij klmnop, which shows this line was added in its stead. This command can be very useful to make sure you’re committing exactly what you think you want to commit and not some other experiments you meant to delete before doing a git push and forcing others to share your code, which may not be ready for prime time.

To compare two branches you can type

git diff --name-status master branch2

You can see the output in Figure 15-17, which shows that compared to master, branch2 has added a file, hello.txt. In the line A testdir/hello.txt, the A denotes that a file was added. You can also see M testdir/testfile_abcde.txt. The M denotes that the file was modified. In this case we modified testfile_abcde.txt.

You can diff one single file between the present branch and another branch with a command, as follows (see Figure 15-18):

git diff master -- testfile_abcde.txt

If I’m in the branch2 branch and run the preceding command, it will show the difference between my present branch and master for file testfile_abcde.txt.

This section has gone over quite a few of the commands needed for working effectively with Git. There are also a few graphical user interfaces for using Git. The next section introduces you to my favorite tool.

Using a GUI for Git

There are several graphical user interfaces (GUIs) for Git, and my current favorite is Sourcetree, which is made by Atlassian (www.atlassian.com/software/sourcetree/overview?_mid=e6152f8f6dcf6b760e82656a0d7bde7a&gclid=CIvzrfvVmbsCFTRo7AodUyMAfA). Sourcetree allows you to visually look at Git commits in your different branches (see Figure 15-19). It even allows you to do Git pulls, make branches, make commits, and so on. I still prefer to use the command line for writing to the repository and doing anything complex, but for browsing commits and getting a bird’s-eye view of everything going on in the repository, this is a great tool.

I think Sourcetree or another tool like it is a must-have for tech leads or managers of a bunch of developers so they can get to know what all the developers are up to. Even for an individual developer, it can help you keep up with the changes being made to the repository that you will have to integrate with.

Summary

In this chapter you learned how to use Git to manage your code. Git is a code repository that allows for versioning of your code; it ends up backing up your code and all different iterations of it. Git allows you to safely collaborate on the same code base, and it merges changes to the same file. If there is a conflict the computer can’t figure out, Git will point you to the conflict for you to manually merge and resolve the conflict. We also learned about Git branches and how one branch might be for development work and another branch—“stage,” for instance—might be where your finished code goes when it is ready for the QA team to look at. We learned about tags, which, unlike a branch, are a snapshot of your code that cannot be altered. Often a tag will be what your production site will point to serve up files. With a version control system like Git, you can easily revert code, share code, and collaborate. drupal.org has thousands of developers, and Git helps us manage this collaboration with a lot of grace.