You are previewing Git Pocket Guide.

Git Pocket Guide

Cover of Git Pocket Guide by Richard E. Silverman Published by O'Reilly Media, Inc.
  1. Special Upgrade Offer
  2. Preface
    1. What Is Git?
    2. Goals of This Book
    3. Conventions Used in This Book
      1. Unix
      2. Shell
      3. Command Syntax
      4. Typography
    4. Using Code Examples
    5. Safari® Books Online
    6. How to Contact Us
    7. Acknowledgments
  3. 1. Understanding Git
    1. Overview
      1. Terminology
      2. Branches
      3. Sharing Work
    2. The Object Store
      1. Blob
      2. Tree
      3. Commit
      4. Tag
    3. Object IDs and SHA-1
      1. Security
    4. Where Objects Live
    5. The Commit Graph
    6. Refs
      1. Related Commands
    7. Branches
    8. The Index
    9. Merging
      1. Merging Content
      2. Merging History
    10. Push and Pull
      1. Notes
  4. 2. Getting Started
    1. Basic Configuration
      1. Personal Identification
      2. Text Editor
      3. Commit ID Abbreviation
      4. Pagination
      5. Color
      6. Cryptographic Keys
      7. Command Aliases
      8. Getting Help
      9. References
    2. Creating a New, Empty Repository
      1. Selected Options
    3. Importing an Existing Project
    4. Ignoring Files
      1. Syntax of “Ignore Patterns”
  5. 3. Making Commits
    1. Changing the Index
      1. Adding a New File
      2. Adding the Changes to an Existing File
      3. Adding Partial Changes
      4. Shortcuts
      5. Removing a File
      6. Renaming a File
      7. Unstaging Changes
    2. Making a Commit
      1. Commit Messages
      2. What Makes a Good Commit?
      3. Shortcuts
      4. Empty Directories
      5. A Commit Workflow
  6. 4. Undoing and Editing Commits
    1. Changing the Last Commit
      1. Double Oops!
    2. Discarding the Last Commit
      1. Discarding Any Number of Commits
    3. Undoing a Commit
      1. Partial Undo
    4. Editing a Series of Commits
      1. Conflicts
      2. The exec Action
  7. 5. Branching
    1. The Default Branch, master
    2. Making a New Branch
    3. Switching Branches
      1. Uncommitted Changes
      2. Untracked Files
      3. Losing Your Head
    4. Deleting a Branch
    5. Renaming a Branch
  8. 6. Tracking Other Repositories
    1. Cloning a Repository
      1. Clones and Hard Links
      2. Bare Repositories
      3. Reference Repositories
    2. Local, Remote, and Tracking Branches
    3. Synchronization: Push and Pull
      1. Pulling
      2. Pushing
      3. Push Defaults
      4. Pull with Rebase
      5. Notes
    4. Access Control
  9. 7. Merging
    1. Merge Conflicts
      1. Resolving Merge Conflicts
      2. Notes
    2. Details on Merging
    3. Merge Tools
      1. Notes
    4. Custom Merge Tools
    5. Merge Strategies
    6. Why the Octopus?
    7. Reusing Previous Merge Decisions
  10. 8. Naming Commits
    1. Naming Individual Commits
      1. Commit ID
      2. Ref Name
      3. Names Relative to a Given Commit
      4. Names Relative to the Reflog
      5. The Upstream Branch
      6. Matching a Commit Message
      7. Following Chains
      8. Addressing Pathnames
    2. Naming Sets of Commits
  11. 9. Viewing History
    1. Command Format
    2. Output Formats
    3. Defining Your Own Formats
      1. Notes
    4. Limiting Commits to Be Shown
    5. Regular Expressions
    6. Reflog
    7. Decoration
    8. Date Style
    9. Listing Changed Files
    10. Showing and Following Renames or Copies
      1. Detecting Copies
    11. Rewriting Names and Addresses: The “mailmap”
      1. Shortening Names
    12. Searching for Changes: The “pickaxe”
    13. Showing Diffs
      1. Color
      2. Word Diff
    14. Comparing Branches
      1. Displaying Sides
    15. Showing Notes
    16. Commit Ordering
    17. History Simplification
    18. Related Commands
      1. git cherry
      2. git shortlog
  12. 10. Editing History
    1. Rebasing
      1. Undoing a Rebase
    2. Importing from One Repository to Another
      1. Importing Disconnected History
      2. Importing Linear History
      3. Importing Nonlinear History
    3. Commit Surgery: git replace
      1. Keeping It Real
    4. The Big Hammer: git filter-branch
      1. Examples
    5. Notes
  13. 11. Understanding Patches
    1. Applying Plain Diffs
    2. Patches with Commit Information
  14. 12. Remote Access
    1. SSH
    2. HTTP
    3. Storing Your Username
    4. Storing Your Password
    5. References
  15. 13. Miscellaneous
    1. git cherry-pick
    2. git notes
      1. git notes Subcommands
    3. git grep
      1. Combining Regular Expressions
      2. What to Search
      3. What to Show
      4. How to Match
    4. git rev-parse
    5. git clean
    6. git stash
      1. Subcommands
    7. git show
    8. git tag
      1. Deleting a Tag from a Remote
      2. Following Tags
      3. Backdating Tags
    9. git diff
      1. git diff
      2. git diff --staged
      3. git diff <commit>
      4. git diff <A> <B>
      5. Options and Arguments
    10. git instaweb
    11. Git Hooks
    12. Visual Tools
    13. Submodules
  16. 14. How Do I…?
    1. …Make and Use a Central Repository?
    2. …Fix the Last Commit I Made?
    3. …Edit the Previous n Commits?
    4. …Undo My Last n Commits?
    5. …Reuse the Message from an Existing Commit?
    6. …Reapply an Existing Commit from Another Branch?
    7. …List Files with Conflicts when Merging?
    8. …Get a Summary of My Branches?
    9. …Get a Summary of My Working Tree and Index State?
    10. …Stage All the Current Changes to My Working Files?
    11. …Show the Changes to My Working Files?
    12. …Save and Restore My Working Tree and Index Changes?
    13. …Add a Downstream Branch Without Checking It Out?
    14. …List the Files in a Specific Commit?
    15. …Show the Changes Made by a Commit?
    16. …Get Tab Completion of Branch Names, Tags, and So On?
    17. …List All Remotes?
    18. …Change the URL for a Remote?
    19. …Remove Old Remote-Tracking Branches?
    20. …Have git log:
      1. Find Commits I Made but Lost?
      2. Not Show the diffs for Root Commits?
      3. Show the Changes for Each Commit?
      4. Show the Committer as well as the Author?
  17. Index
  18. About the Author
  19. Special Upgrade Offer
  20. Copyright
O'Reilly logo

Chapter 12. Remote Access

As mentioned in Chapter 6, Git can access remote repositories for push and pull using different network protocols; the most common are HTTP(S), SSH, and the native Git protocol. Especially if the remote repository accepts push requests, the access protocol may require you to identify yourself in order to grant access; this is called “authentication,” and may be accomplished in various ways, such as by providing a username and password. The Git protocol does not support authentication, so this is usually done via HTTP or SSH; the native Git server, accessed on port 9418 with the URL scheme git://, is used almost exclusively for read-only access to repositories (for which it is a good choice, since it is fast and easy to set up).

The question of how to configure the server side for these protocols generally is well beyond the scope of this text; entire books have been written on SSH, the Apache web server, the Windows IIS web server, etc. However, we will touch on a few common cases from the client perspective, and on some Git features that help with this.


When you access a repository with a URL of the form:


Git runs ssh, or the program given by the environment variable GIT_SSH, to log into the remote host and access the repository by running the appropriate remote command: git upload-pack for pull, and git receive-pack for push. The local and remote Git programs then communicate over the SSH channel to perform the requested operation. For example, when asked to pull from the repository, Git runs this command:

ssh git-upload-pack dance/monkey

This logs into the host with the username dieter, and runs the remote command git-upload-pack dance/monkey. If the host is Unix, usually this means that there must be a user account named dieter on that host, git-upload-pack must be in the program-search path on the remote side (the PATH environment variable), and the remote repository must be in a subdirectory of the dieter account’s home directory named dance/monkey. You can refer to any directory to which the remote account has access by using a complete pathname with a leading slash (e.g., host:/var/lib/git/foo.git).

SSH will prompt you for a password if necessary, but it may be very inconvenient to do this repeatedly, so you may want some form of automatic authentication for this connection: a method by which you can type your passphrase just once and allow many subsequent Git commands. There are several different options for this, but the most common is SSH public-key authentication.


All the details we are about to give regarding SSH assume the simplest scenario: the Unix OpenSSH software on both client and server in the most usual, plain configuration. Although this is very common, any or all of these may be entirely different depending on the operating systems, SSH software, and system configurations involved. Similarly, SSH by itself and security in general are complex topics. There are many different ways of accomplishing even this simple task, with varying implications with regard to security, and this simple example is not meant to endorse any particular one. When in doubt, consult a security expert or the sysadmins of the hosts in question.

You can generate a new SSH public key thus if you don’t already have one:

$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in .ssh/id_rsa.
Your public key has been saved in .ssh/

The “passphrase” is just another name for a password, emphasizing the fact that you can use an entire phrase with spaces and punctuation, not just a single word. You should generally not just leave this blank; that means that anyone who gets hold of the private key file id_rsa will have access to any SSH accounts protected with this key. It’s like putting your password in a file; don’t do it unless you really know what you’re doing (or really don’t care about security).

You then send your public key—the contents of the file ~/.ssh/—to the server administrator, asking him to authorize your key for login to the remote account; this usually means placing it in ~/.ssh/authorized_keys in the home directory of the account, with appropriate ownership and permissions. When this is done, SSH will prompt you for the key passphrase instead:

$ git pull
Enter passphrase for key '/home/res/.ssh/id_rsa':

Enter your passphrase to test whether the setup is working correctly—though so far this is not much of an improvement in convenience; you’re still being prompted to enter something for every Git command accessing the remote repository. The final step is to use the SSH “agent” to get automatic authentication:

# Test whether you have a running agent.
$ ssh-add -l >& /dev/null; [ $? = 2 ] && echo no-agent
# If not, start one.
$ eval $(ssh-agent)
# Now, add your key to the agent.
$ ssh-add
Enter passphrase for /home/res/.ssh/id_rsa:
Identity added: /home/res/.ssh/id_rsa (.ssh/id_rsa)

On some modern Unix-based systems, you may not have to do any of this—for example, OS X starts an SSH agent for you when you log in, and SSH prompts you for your key passphrase with a graphical dialog box and automatically adds it to the agent on first use.

Once your key is loaded in the agent, you should be able to use Git to access this repository without giving your passphrase, for the duration of your current login session on the client computer.


You can also use this style of URL for SSH:


A distinction to keep in mind is that, unlike the earlier style, the path given here is not relative to the remote account’s home directory, but rather is absolute. You can get a relative path by prefixing the path with ~. For example:


although this may depend on the shell used by the remote account.


A web server providing access to a Git repository may also be set to require authentication. Although more sophisticated mechanisms are available, including Kerberos and public-key certificates, the most common approach with HTTP is still to require a simple username and password. This complicates automatic authentication, but Git has its own framework for managing and providing such credentials.

Storing Your Username

You can include the username in an HTTP URL in the same way as with SSH:

But you can also set it separately, like so:

$ git config --global
credential.''.username dieter

Storing Your Password

Git has a mechanism called “credential helpers,” which stores passwords in various ways for more convenient use. One such helper, named cache, is similar to ssh-agent and caches your password in memory for use by Git. It is not used by default; to enable it, do:

$ git config --global credential.helper cache

Once you do this, Git should prompt you only once in a given login session for the password associated with any particular URL; when you provide it, Git stores it in the running credential cache agent, and subsequent commands automatically obtain it from there. If you look, you can see the agent process:

$ ps -e | grep git-cred | grep -v grep
33078 ttys001    0:00.01 git-credential-cache--daemon /home/res/.git-credential-cache/socket

Git communicates with the agent via the socket shown on the agent command line.

There is another standard credential helper named store, which simply stores the password in a file on disk (~/.git-credentials). You shouldn’t do this for interactive use, but it is appropriate for automated processes that need to run Git and use password authentication, so long as adequate care is taken in protecting the host system and setting permissions on that file. You can also use the cache helper with automated processes if that level of security is not enough, but a human will have to enter the password once after the machine boots in order to add it to the cache, so this is not the right approach if the system in question must be able to start unattended.

The Git credential mechanism is extensible, and there are third-party helpers available that connect with platform-specific security features. For example, the helper osxkeychain stores passwords in the OS X “keychain,” the standard credential manager for the Mac. It is included with the versions of Git installed by the Apple Xcode developer tools or by MacPorts. Just enable it with:

$ git config --global credential.helper osxkeychain

and it should work automagically. You can use the Keychain application to verify that Git is indeed storing its credentials there.


For more detail, see:

  • gitcredentials(7)
  • git-credential-cache(1)
  • git-credential-store(1)

The best content for your career. Discover unlimited learning on demand for around $1/day.