Operand Types

As referenced in Table 4.1, Git can take different kinds of operands, which are specifications of objects to operate on. The two most common operands are the SHA1 value of a commit (or a named branch or tag that refers to such a commit) and a path specification to a file or directory on the disk. For many commands, either or both of these value types may be specified—or neither. When neither operand is specified, the command will operate against all eligible items that it finds in the scope of the repository, staging area, or working directory tree.

The primary reason to specify both commit references and paths would be to select certain paths that are part of, or in the scope of, the snapshot associated with the commit. Because Git operates at the granularity of a snapshot (tree), you may not always want to do the operation against all items in the snapshot. However, that's what would happen if you just specified the commit | tag | branch. To indicate that the operation should only be done against certain files or paths in the scope of the snapshot, you need to add specific filenames or paths.

When both types are specified, if there is a possibility of Git not being able to tell the difference between a commit | branch | tag and one or more of the filenames or paths, then you can separate the two types using the special separation symbol “--”. Normally, this won't be needed if a commit is expressed as a SHA1 value, but it may be needed if branch or tag names could be mistaken as names for files or paths.

As an example, the command git <command> a1b2c3d4 file1.txt might be clear enough, but git <command> my-tag-name -- my-file-name could be ambiguous enough when parsed to require the “--” separator symbol.

Porcelain versus Plumbing Commands

In this section, command represents any of the commands available in Git, such as the ones I talked about for moving content between the levels of Git in Chapter 3 (add, commit, push, and so on). In Git, there are two categories for the types of commands: porcelain and plumbing. Those names may sound strange, but essentially, the porcelain commands are intended to be user-facing, more commonly used, and more convenient. They also typically provide a higher level of functionality. The commands that I previously mentioned in conjunction with the Git promotion model are examples of porcelain commands.

The plumbing commands function at a lower level and are not expected to be used by the average user. These commands are typically targeted at extracting or modifying content and information more directly from the repository. An example would be the git cat-file or git ls-files commands that provide a way to look at the contents of a file or directory within the repository if you know how to reference those elements.

Certain functionality in Git can be accomplished using either porcelain commands or plumbing commands. However, it would usually take several very specific plumbing commands to accomplish what one porcelain command can do. The porcelain commands are based on the plumbing commands. They aggregate the functionality of plumbing commands and certain options and sequences in order to make things simpler for the typical Git user.

Table 4.2 shows a categorization of the porcelain (user-friendly) commands that are available in Git.

Table 4.3 shows the same categorization for the plumbing commands. These commands have names that indicate an action and an object to operate against as opposed to the simpler naming of the porcelain commands.

The descriptions for the commands in these tables are taken directly from the Git help. Some of the terms are more Git-specific at this point. However, as I use commands through the remainder of this book, I'll simplify their definitions and the terminology so it all makes sense.

The point of this section is that unless you have a specific need to deep-dive into the repository, you can simply use the porcelain commands and accomplish what you need to in Git.

Specifying Arguments

Arguments supplied either to Git or to Git commands can be abbreviated as a single letter or spelled out as words. One important note here is that if the argument is spelled out, you must precede it with two hyphens, as in --global. If the argument is abbreviated, only one hyphen is required, as in -a. Abbreviated arguments may be passed together, as in -am instead of -a -m. When arguments are combined in this way, the ordering is important. If the first argument requires a value, then the second argument may be taken as the required value instead of an additional argument.

Auto-complete

When you start typing a command or an argument to a command, Git has a helpful auto-completion feature (if enabled) that can do two things:

• Provide valid values for the commands or arguments that could complete the text you're typing—if there is more than one valid option.
• Automatically complete the command or argument that you're typing—if there is only one valid option.

Following are a couple of examples. The first one is for a command. If you type git c and then press the Tab key, nothing happens because there's more than one command that starts with c.

If you press the Tab key a second time (before typing anything else in between), Git helpfully displays all of the commands that start with c. In this case, it also scrolls that list up and leaves you at a prompt where you can continue typing the chosen command.

$ git c
checkout      citool        commit
cherry        clean         config
cherry-pick   clone

$ git c

Here's another example, where you narrow the available commands with more letters.

$ git co <TAB><TAB>
commit   config

$ git c

If you type enough letters to uniquely identify only one possible choice, then pressing the Tab key auto-completes the command for you because there's only one option. For example, git con <TAB> yields git config.

This also works for arguments to commands. Typing git config --l <TAB> <TAB> gives the suggestions: --list --local. Typing either git config --l or git config --li <TAB> yields git config --list.

$ source ~/git-completion.bash

Telling Git Who You Are

Referring to the two earlier examples, one of the first things that you need to configure in Git is who you are, in terms of the username and e-mail address. Git expects you to set these two values, regardless of what interface or version of Git you use. This is because Git is a source management system. Because its purpose is to track changes by users over time, it wants to know who is making those changes so that it can record them.

If you don't specify these values, then Git will interpolate them from the signed-on userid and machine name (user@system). Chances are this is not what you want to have the system ultimately use. If you forget to set these values initially on a new system, and commits are recorded with the interpolated values, there is a way to go back and correct this information, using the commit command with the --amend and --reset-author options.

The values can be set via the same commands as shown in the previous section: git config --global user.name <name> and git config --global user.email <email address>.

Configuration Scope

In the previous examples, I used the --global option as part of the configuration step. The global option is a way of telling Git how broadly this configuration setting should be used—which repositories it should apply to.

Recall that the Git model is designed for many, smaller repositories instead of fewer, monolithic ones. Because users may normally be working with multiple repositories, it would be inconvenient and subject to error to have to configure the same settings in each repository. As a result, Git provides options to simplify choosing the scope for configuration values. There are three levels available for configuration: system, global, and local.

Settings Hierarchy

When determining what configuration setting to use, Git uses a particular search order to find these settings. First, it looks for a setting in the local repository configuration, then in the global configuration, and finally in the system configuration. If a specific value is found in that search order, then that value is used. Beyond that, the union of all of the levels (unique local + unique global + unique system) forms the superset of configuration values used when working with a repository.

Figure 4.1 summarizes the different configuration scopes in Git and how to work with them.

$ git config --global user.name "Global user"
$ git config user.name 

$ git config user.name "Local user"
$ git config user.name 

$ git config --unset <other options> <value to remove>

$ git config --unset --global user.name
$ git config --global user.name

$ git config --list
…
user.name = global user
…
user.name = local user

$ git config --local --list
…
user.name = local user

Default Editor

The default editor is primarily used when you need to type in a message while making a commit into the repository. If you don't supply the message in the command line when you do the commit, Git will bring up the default editor on your system to allow you to type one in.

If you would rather use a different editor, you can use the following config command to specify which one to use: git config --global core.editor <editor name or path + name> <optional options for the editor>.

The --global option is not required, but most users want to use the same editor for all of their repositories. Here again, you can break down core.editor as the editor value in the core section of the configuration.

If the editor is already in the path that Git knows about, then the path isn't required. Here are some examples of configuring editors:

$ git config core.editor vim  (Linux)

$ git config --global core.editor "nano"  (OS X)

c:> git config core.editor "'C:Program Fileswindows ntaccessorieswordpad.exe'"  (Windows)

$ git config --global core.editor "'C:/Program Files
(x86)/Notepad++/notepad++.exe' -multiInst -noSession
-notabbar"  (Bash shell on Git for Windows)

Note the different uses for single quotes and double quotes in the respective examples. Also, in the last example, -multInst, -noSession, and -notabbar are all options to Notepad++ to make it simpler to use. (multInst tells Notepad++ to allow multiple instances to run; noSession tells it not to remember the session state—that is, not to load the last file you were working on; and notabbar just avoids displaying the tabbed selection bar at the top.)

End of Line Settings

Now, let's look at one of the key settings users need to manage with Git: handling end of line (EOL) values. Git manages the two types of line endings: carriage returns/line feeds (CRLF) for Windows and line feeds (LF) for OS X/Linux.

In the context of Git, there are two options that are controlled by the EOL setting:

• How line endings are stored in content when it is committed into the repository
• How line endings are updated (or not) when content is checked out of the repository onto a local disk

The first item refers to whether or not Git normalizes line endings in the repository. Normalizing refers to stripping out CRs and only storing files with LFs.

For the second item, when content is checked out of Git, Git can update line endings in text files. This option allows you to specify whether or not Git updates line endings in files after checkout, and, if it does, which type it sets them to.

At a user or repository level, how Git handles these options is controlled by a configuration setting named core.autocrlf. As before, the “.” is a separator, and you can think of the first part as the section of the configuration, and the second part as the specific value being set in that section. The crlf part here obviously stands for carriage return, line-feed—meaning the common EOL sequence for files on a Windows environment. The auto part refers to automatically inserting CRLF sequences in files when they are checked out.

There are three possible values for the core.autocrlf setting:

1. core.autocrlf=true. This value tells Git to normalize line endings to just LFs when storing files in the repository and to automatically insert CRLFs when files are checked out. If users are working on a Windows environment, this is the recommended value. It allows them to get CRLFs in files when checked out from Git, but doesn't store the CRs in the repository.
2. core.autocrlf=input. This value tells Git to normalize line endings to just LFs when storing files in the repository but not to change anything when files are checked out. If users are working in a Unix environment, this is the recommended value because Unix expects just LFs.
3. core.autocrlf=false. This default value tells Git not to change anything when files are being checked in or checked out. This is the primary value for the setting that can get users into trouble. Suppose you have two users working on code for the same repository, one in a Windows environment and one in a Unix environment. If both users have specified the core.autocrlf=false value in their configurations, then when they commit changes, the files from Windows will have CRLFs and those from Unix will have just LFs. If the respective users later each check out the other's files, then the files will have the wrong line endings for their system. For this reason, this value should not be used when mixed environments are being used in a project.

In general, it's a best practice to set the core.autocrlf setting to one of the values other than false, depending on which environment you're working in.

It should also be noted that there are other configuration settings that can contribute to how line endings are handled. However, these settings are more obscure and broader in terms of what they affect. Also, their default values generally work well for what most users need to do.

Aliases

Configuration in Git also supports the concept of configuring aliases for command strings. The format for defining an alias is git config <scope option> alias.<name> <command string>.

In this context:

• <scope option> can be one of --system, --global, or --local. (Or it can be omitted, to default to local.)
• <name> is the name you want to use for the alias. Once set, this can be used just like any other Git command.
• <command string> is the string of a command and any arguments that the alias will substitute for.

There are two main reasons that aliases are convenient to create and use:

• To save typing frequently used strings of commands and arguments
• To create a more familiar command for a Git command

As an example of the first case, the git log command displays history in Git and has many options. Here's an example log command:

$ git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short

Because this is a long command string, it can be difficult to type each time you want to use it. So, you can create an alias instead.

$ git config --global alias.hist git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short

With this alias in place, you can now just type git hist instead of the longer, complicated command.

As an example of the second use case, suppose a user is more accustomed to typing checkin from using other SCMs instead of commit. If they want, they can create an alias by using git config --global alias.checkin commit.

After this, the user can type git checkin instead of git commit. (Note that, while this sort of alias can be created, it is not recommended because it is not universal and obscures Git's native commands.)

The format of the command to create an alias is consistent with the other config syntax. When you see alias.<name>, you can think of this as creating a value in the alias section of the configuration file. The alias information is stored in the configuration file for the specified scope.

Windows Filesystem Cache

The underlying filesystem layer on Windows is fundamentally different from the filesystem layer on Linux. Git's filesystem access is optimized for the Linux filesystem, and in the past, some operations on Git for Windows were noticeably slower. To compensate, Git has added a filesystem cache that does bulk reads of file system data and stores it in memory. This speeds up many operations, once the cache is initially populated. In recent versions of the install for Git for Windows, this option is turned on by default. To set it manually, you change the core.fscache value to true via git config --global core.fscache true.

Git Init

The git init command is used for creating a new, empty Git repository in the local directory. The syntax for the command is shown below.

git init [-q | --quiet] [--bare] [--template=<template_directory>]
    [--separate-git-dir <git dir>]
    [--shared[=<permissions>]] [directory]

When this command is run, a new subdirectory named .git is created in the directory where the command was run, and populated with a skeleton repository. (Like many open-source applications, Git stores metadata in a subdirectory named for the tool and preceded by a dot.) This local environment is now ready for tracking and storing new content. Note that this command can be run at any time in a directory that does not already have a Git environment associated with it to create one, no matter how many or what types of files are already in the directory.

The basic syntax for invoking init is git init. Before running git init, you should be at the top level of the tree you want to put under Git control. You also want to make sure this is done at an appropriate level of granularity. Recall that Git is intended to work with multiple, smaller repositories, not very large ones. So, running git init at your home directory level, for example, is not usually a good idea because this sets Git up to try and act on all files and subdirectories under your home directory for future operations—which is probably beyond the scope you intended.

Git Clone

Whereas the init command is used when you want to create a new, empty repository and begin adding content, the clone command is used to populate a local repository from an existing remote repository. The syntax for the command is shown below.

git clone [--template=<template_directory>]
       [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
       [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
       [--dissociate] [--separate-git-dir <git dir>]
       [--depth <depth>] [--[no-]single-branch]
       [--recursive | --recurse-submodules] [--] <repository>
       [<directory>]

To use the clone command, you specify a remote repository location to clone from and Git does the following:

• Creates a local directory with the same name as the last component of the remote repository's path
• Within that directory, creates a .git subdirectory and copies the appropriate parts of the remote repository down to that .git directory
• Checks out the most recent version of a branch (usually the default master branch) into the local directory. This checked-out version with the flat files is what the user usually sees and works with immediately after the clone.

The basic syntax for cloning a repository is git clone <url> where <url> is a path to a remote repository. Here's an example:

$ git clone ssh://[email protected]:path-to-repo.git 

I will discuss this command more in Chapter 12.

What's in the Repository

Whether the local environment is created by a git init or git clone command, the structure within the .git subdirectory is the same. Essentially, a Git repository is a content-addressable data store. That is, you put something into the repository, Git calculates a hash value (SHA1) for the content, and you can then use that value later to get something out. Figure 4.2 shows an outline of a .git repository on disk.

The HEAD file keeps track of which branch the user is currently working with. The description file is used by GitWeb, a browser application to view Git repositories. The config file is the local repository's configuration file. The object and pack directories are the areas where content is actually stored. You can find more information about the files and content stored in the local repository in the optional steps of Connected Lab 2.

Git Init Demystified

If you're wondering how git init gets the initial content for the skeleton repository, the answer is that there's a template area containing the repository skeleton. This is installed when you install Git. If you're interested in looking at it, you can search for git-core on your filesystem in the area where you installed Git. On Windows, this is usually in a location such as C:Program FilesGitmingw64sharegit-core emplates (if you installed the Git for Windows package). On a Linux system, it may be in a location such as /usr/share/git-core/templates.

On some installations, you may also see a contrib folder in the same area with items such as hooks that users have contributed over time that are now included as optional pieces that can be put in place as desired. I'll talk more about setting up hooks in Chapter 15.

Looking Further into a Git Repository

As I've previously mentioned, a local Git repository is housed in the .git directory of the working directory. It is essentially a content-addressable database, meaning you supply a value (typically a SHA1) and you get content back out.

Figure 4.3 shows the relationship and transformation of content from the working directory into the Git repository.

Starting at the left side of the figure, files and directories first exist as normal OS items on the disk in the working directory. Git does not know anything about them. It does not track them until the user adds them to the staging area. Once they are tracked by Git, a new snapshot is created with metadata in the form of a commit record. Once committed, the pieces are stored in their respective areas in the underlying repository.

As shown in the middle section of the figure, the pieces that Git stores are defined as one of three types: blob, tree, or commit. Blobs are essentially anonymous containers for files—anonymous in the sense that they don't contain filenames. Trees can be thought of as containers for directories that point to blobs for files and contain the filenames. Commits can be thought of as the header records with meta-information that Git uses for tracking.

Internally, Git computes SHA1 checksums for each of these pieces and stores them referenced by those checksums. The checksums can be seen in the parts of the middle section and then in the tree view of the actual repository directory on the right side of the figure.

As shown in that view, Git stores these internal objects in directories that start with the first two characters of the checksum. The filename is made up of the remaining characters. The files may be changed over time when certain events trigger Git to do further compression and rearrange content to efficiently store very similar versions.

The only checksum those commands are concerned with (and the only one you need to be concerned with) is the checksum that is specifically associated with the commit record, not the ones for trees or blobs.

By referencing that one checksum for the commit record, Git pulls in the underlying tree and blob content.

Once you actually have a repository with content stored in it, you can change into the repository directories to see the stored objects or use this shortcut (on Linux systems): find .git/objects -type f.

From there, you can use the cat-file plumbing command to examine objects. As an example git cat-file -p <sha1 or branch name or reference> tells Git to figure out the type of object and neatly display its contents. A similar command, git cat-file -t <sha1 or branch name or reference> returns the type of an object: commit, tree, or blob.

Connected Lab 2 contains several optional steps that you can work through to understand what's happening in the underlying repository during an init, add, and commit sequence. It also further explains the files that are in the underlying repository tree at various points.

Mapping Config Commands to Configuration Files

In this chapter, I described the various configuration files that Git uses, as well as how to set values via the git config command. If you see something in a config file that you want to emulate or use, it can be helpful to understand how the config commands map to the file structure. This section will explain that.

Suppose you configure a two-part value such as user.name in your local configuration with a command like git conig --local user.name "Git User".

This translates into setting the name value of the user section, written into the .git/config file as follows:

 [user]
         name = Git User

If you need to configure a given value for a named section, you can use a three-part value such as the following:

$ git config --local remote.myremote.url http://github.com/brentlaster/calc2

$ cat .git/config
…
[remote "myremote"]
             url = http://github.com/brentlaster/calc2

Anything beyond three parts is still treated as three parts, with the extra pieces at the front just made part of the named section.

$ git config --local remote.myremote.new.url http://github.com/brentlaster/calc2

$ cat .git/config

…
[remote "myremote.new"]
               url = http://github.com/brentlaster/calc2

Note that the git config operation also takes a --file option instead of --local, --global, or --system. This allows for writing configuration options to a file in a different location, such as for test purposes.

$ git config --file test.config remote.myremote.test
        http://github.com/brentlaster/calc2git
	
$ cat test.config
[remote "myremote"]
                  test = http://github.com/brentlaster/calc2git

As one last tip, git config includes a --get-regexp option to find configuration values matching a specified pattern. I'll use this option in the next section so you can see how it works.

Creating Parameterized Aliases

Earlier in this chapter, I showed how to create simple aliases for specific Git command lines, such as git config alias.ci commit. It is certainly userful to alias fixed command strings, but only to the extent that arguments and options included in the alias never change.

What if you want to create an alias that takes a parameter that is not normally part of a command? Or that may change over time? Or that may perform extra steps or processing—especially with system commands?

As it turns out, on Linux systems you can do this with Git fairly easily. You just need to have your alias string take this form:

"! f() { do some processing }; f"

The ! at the beginning tells Git you are going to the shell. The “f() {}; f” allows you to define a function as part of the alias and then run that function when the alias is invoked.

Values that you pass in as arguments are treated as positional parameters (for example, $1, $2, and so on). When including these parameters in the alias definition, a backslash needs to precede the $, as in “$”. This is to ensure the parameter is included as part of the definition and not interpreted when you are defining the alias.

Let's work through a couple of examples. First, I'll create a simple alias that takes an argument and lists out any matching global and local settings prefixed by an appropriate header for each section. The config command is used in this example. What I am doing in this command line is defining a local alias named scopelist, which does the following:

1. Echoes out a global settings header
2. Uses git config's --get-regexp option with a global qualifier to search for the value that is passed in
3. Echoes out a local settings header
4. Uses git config's --get-regexp option with a local qualifier to search for the values that are passed in

Here's the command. (Pay attention to the quotes, semicolons, double hyphens, and backslashes.)

$ git config --local alias.scopelist "! f() { echo 'global settings'; git config --global --get-regexp $1; echo 'local settings'; git config --get-regexp $1; }; f"

Here is an example of running the alias:

$ git scopelist name
global settings
user.name Git User (global)
local settings
user.name Git User (local)

The following example will show you a simple way to dump out the contents of a particular scope into a file. This illustrates having two positional parameters. In this case, the alias will do the following:

1. Echo out a header.
2. Issue a git config command at the appropriate scope.
3. Dump the values from step 2 into a separate file.

Here's the command to define this alias. (Again, pay attention to the punctuation characters that are used.)

$ git config --local alias.dumpvalues "! f() { echo 'copying config' $1; git config --list --$1 > $2; }; f"

Here is an example of running this alias and looking at the results:

         $ git dumpvalues global global_values.out
         copying config global
	 
         $ cat global_values.out
         alias.hist=log --pretty=format:"%h %ad | %s%d [%an]" --
graph --date=short
         push.default=simple
         core.autocrlf=false
         core.editor='C:/Program Files
(x86)/Notepad++/notepad++.exe' -multiInst -noSession -notabbar
         gitreview.remote=origin
         user.name=Git User (global)
         [email protected]

Obviously, these examples don't cover all the possibilities of bad or missing input. However, they'll give you an idea of how to use this functionality if you ever need it.