Gitting Started (Part III): Committing Your First Files

In this post, I’ll walk you through committing your first files to the Git repository you created in Part II of this series. (If you need an overview of what Git is or how it works, please read Part I.) To follow along, you’ll need the empty Git repository you’ve created in Part II.

This post will cover three Git commands:

• git status
• git add
• git commit

Each of these commands is very flexible and has a number of options you can choose. However, since this is a guide for beginners, I will only cover a few of them here. For more information about all the options available, you can use the man page for each command by running man git-<command>, for example:

$ man git-commit

Like the other posts in this series, this post assumes you are using a Linux or other UNIX-based operating system (including Mac OS X) and have basic familiarity with using the command line on your system. The non-Git commands you’ll use to follow along with this post are:

• ls: Lists the contents of the present working directory or other directory if one is specified.
• cd: Changes the present working directory to the directory specified. If no directory is specified, changes the present working directory to the logged-in user’s home directory.
• echo: Prints the specified text to a file indicated with >, or to the console if no file is specified. (For example, echo "foo" > foo.txt writes the text foo to a file called foo.txt. The file will be created if it does not already exist. If it does exist, its contents will be overwritten.)

Viewing New Files with git status

In order to track revisions with Git, you need to give Git some revisions to track! Start by running this to change the present working directory to your repository:

$ cd my_repo

Replace my_repo with the name or path of your repository. Next, create a file for Git to track by running:

$ echo "puts 'Hello World!'" > hello_world.rb

You now have a file, written in the Ruby language, that prints the words Hello World! to the console. To test it out, you can run:

$ ruby hello_world.rb

Now that you have your new file, you can see it by running

$ git status

Your output will look something like this:

On branch master
No commits yet
Untracked files:
  (use "git add <file>..." to include in what will be committed)
      hello_world.rb
nothing added to commit but untracked files present (use "git add" to track)

Notice that your new file is listed under Untracked files. Files listed under Untracked files are files that you haven’t yet told git to track. Whenever you create a new file, you need to explicitly tell Git that you want it tracked.

If you want more information about the git status command, run man git-status (don’t forget the hyphen!).

Staging a New File with git add

In order for git to track your file, you need to first stage it by running:

$ git add hello_world.rb

Now run git status again. You should see the following output:

On branch master
No commits yet
Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
      new file:  hello_world.rb

Notice that your file is now listed under Changes to be committed. As the command output indicates, if you have staged the file in error, you can undo the action by running:

$ git rm --cached hello_world.rb

Suppose you have multiple files you want to git add all at once. You can do this by specifying multiple files with a space in between, such as:

$ git add hello_world.rb goodbye_cruel_world.rb

You can also run this to stage all new or changed files in the repo:

$ git add .

However, this is not recommended as it can lead to committing things you didn’t intend! Best to carefully review the files to make sure you’re only staging the ones you want to commit.

I’ll go into a bit more detail about the git add command and its options in future posts. In the meantime, if you want to read ahead, check out the man page by running man git-add.

Committing Your Staged File

Now that your file is staged, you can commit. Running this command will commit all files that are currently staged:

$ git commit

Once committed, the file will be permanently* added to git history in its current form. The changes made in this revision will still be available to view or revert to in the future, even if you commit other changes subsequently. Files that have been changed or added but haven’t been staged yet will not be committed. That’s the reason you have to stage files before committing them — sometimes you’ll want to commit different changes separately so that each revision represents a particular logical set of changes.

When you run git commit, by default, vim will open up. vim is a text editor that runs in the terminal. (You can configure git to use the text editor of your choice as well, but for now we’ll stick to vim.) It opens so that you can write a commit message. Your commit message should be a brief explanation of why you made the changes you did. You can also explain what the changes are if that might not be obvious to you or someone else looking at the commit history in the future. Git saves the commit message along with the revision so people reading git history in the future can see what the change was and why it was made.

To type your commit message in vim, first press I, which is how you tell vim that you want to enter text. Type your commit message, then press Esc. To save your commit message, type :wq and press Enter. Congratulations, you have made your first commit!

There is quicker way to add a commit message as well: the -m flag, followed by your message. For the hello_world.rb file, you might run:

$ git commit -m "Print 'Hello World' to the console"

Note that there need to be quotes around the message.

If all goes well, you should see the following output (commit SHAs will be different):

[master (root-commit) 106b5ea] Print 'Hello World' to the console
 1 file changed, 1 insertion(+)
 create mode 100644 hello_world.rb

This output tells you, among other things, what branch you’re on (master), the commit SHA (106b5ea), what files were changed and whether you added or removed something from that file (if you change a line in a file, Git will interpret that as your having deleted the original line and inserted a new line).

Conclusion

Congratulations, you have made your first Git commit, ensuring that the changes, you’ve made will be preserved as a revision in Git history in case you need to look at them or revert to them in the future. In the next post, I’ll cover creating a new branch in Git so you can make additional changes in your repository.

— — — — — — —

* There are certain cases where commit history can be modified or removed, but we’ll talk about those later. You won’t be able to modify or remove existing commits using the commands you’ve learnt so far.