Creating Local Repositories

Create an example project

Now let's create a new directory called git_basics and add a few files to it.

$ mkdir git_basics
$ cd git_basics
git_basics/ $ echo '# README #' > README.md
git_basics/ $ echo '# LICENSE #' > LICENSE.md

The files above, README.md and LICENSE.md, are for demonstration purposes only, though they are included in the root directory of many open source projects. These particular files use the markdown format. We are using markdown here because it is readable as plain text and will render nicely when we share our repository on github.com in the next section.

git init

Before we start learning more about working with repositories, we need to create one. On the command line, from within the new directory we just created, type the following:

git_basics/ $ git init

You should see something like this:

Initialized empty Git repository in git_basics/.git/

As the message says, you have "initialized", or created, a new repository in your current directory. Technically, the only thing that changed was a .git directory was added to the git_basics directory, but conceptually, you can think about it as turning that directory into a git repository. After you initialize a directory as a git repository, you can then start issuing other git commands.

Warning:   Do not nest your repositories. That means that if ~/dev/project is a repository, ~/dev/project/other_project should not be another repository. You need to move other_project to ~/dev/other_project.

It's important to only issue the git init command from within the directory that you wish to turn into a git repository. If you've accidentally typed that command in a directory that you didn't want to turn into a git repository, all you have to do is delete the .git directory within that directory. Deleting the .git directory doesn't uninstall the git application or affect the other git repositories on your computer. It only removes the git repository from the current directory.

.git Directory

After you type git init, a directory named .git is added to the current directory. This directory will contain all of the configuration and metadata necessary for git to keep track of our files and the changes that we make to them. The directory name starts with a . to signify that it's a hidden file. Hidden files are normally not shown to the user by the operating system. Your operating system uses many hidden files for system configuration purposes and the .git directory is a configuration file for git.

Use the terminal to display the .git directory with the command ls -a. The ls command lists the current directory contents and by default will not show hidden files. If you pass it the -a flag, it will display hidden files. You can navigate into the .git directory like any other normal directory. Go ahead and poke around the .git directory to take a look at its files. Take a peek at the .git/config file in particular. No need to do anything or make any changes, just take a look at it. You'll want to peek at this file periodically after you make changes to your git repository configuration.

The config File

There are three places on your system where git keeps its configuration information.

Location Description
/etc/gitconfig Contains settings that are system-wide and apply to all users and all of their repositories.
~/.gitconfig Configuration that is specific to your user account. This file overrides /etc/gitconfig.
<repository>/.git/config Configuration that is specific to a repository. This file overrides both of the other files.

Usually you'll want to store your identity information, like name and email, in the ~/.gitconfig file, which tells all git repositories in your system your name and email address, which will be applied to each commit. There are many other configuration settings that can be set, including colors for git's output. Where those configuration settings go will depend on whether you want them to be global settings or just for a particular repository.

Hello git, nice to meet you!

Since we are already on this subject, let's configure your identity now.

Type the following into the command line, replacing the fake identity with your own:

git_basics/ $ git config --global user.name "Maya Angelou"
git_basics/ $ git config --global user.email MayaAngelou@poets.com

Using the --global flag tells git to save the configuration in the user-wide configuration file, ~/.gitconfig. If you were to use the --system flag, the configuration would be saved in /etc/gitconfig, thereby applying to all users on this computer. And if you do not pass the git config command any flags, it will save the name and email in the current repo's config file, git_basics/.git/config.

.gitignore

Most git repositories will have private data that you do not want shared, such as local databases, log files or personal credentials. That is what the .gitignore file is for (note the ., which means it's a hidden file). This file is a list of files and/or directories that you do not want included in your repository. Git will not allow you to add any of the files referenced in .gitignore to your repository. The .gitignore file lives in the current git repo's directory and paths to ignored files and directories should be relative from that directory.

Implementing .gitignore

Let's create a dummy database file which we do not want to allow into our repository.

In the command line, type:

git_basics/ $ mkdir db
git_basics/ $ touch db/development.sqlite3

Now we need to make sure our database cannot be committed to our repository. In your console, type:

git_basics/ $ touch .gitignore

Next, open ~/git_basics/.gitignore in your text editor. Add the following:

# Ignore all SQLite databases
db/*.sqlite3

You can see that lines that start with # are ignored and act as comments. The * acts as a wildcard, so our .gitignore file ignores all files with the extension sqlite3 in the db directory. If you put this in a global ignore file, the same would apply to all git repositories on your computer. We won't talk about global git ignore files, but the concept is the same. For now, just use the .gitignore file in the repo you're working with. Remember to create a .gitignore file for every git repo you're working with.

Summary

In this chapter, we learned how to turn any directory into a git repository just by using the git init command. All the git init command does is add a .git folder to the current directory, and that enables the directory to be a git repository. We also talked about how to configure your git repository, and the very important concept of never nesting your git repositories.