gitremote-helpers

title: gitremote-helpers(7)

text:
# gitremote-helpers(7)

## NAME
gitremote-helpers - Helper programs to interact with remote repositories

## SYNOPSIS

```
git remote-<transport> <repository> [<URL>]
```

## DESCRIPTION
Remote helper programs are normally not used directly by end users, but they are invoked by Git when it needs to interact with remote repositories Git does not support natively. A given helper will implement a subset of the capabilities documented here. When Git needs to interact with a repository using a remote helper, it spawns the helper as an independent process, sends commands to the helper’s standard input, and expects results from the helper’s standard output. Because a remote helper runs as an independent process from Git, there is no need to re-link Git to add a new helper, nor any need to link the helper with the implementation of Git.

Every helper must support the "capabilities" command, which Git uses to determine what other commands the helper will accept. Those other commands can be used to discover and update remote refs, transport objects between the object database and the remote repository, and update the local object store.

Git comes with a "curl" family of remote helpers, that handle various transport protocols, such as git-remote-http, git-remote-https, git-remote-ftp and git-remote-ftps. They implement the capabilities fetch, option, and push.

## INVOCATION
Remote helper programs are invoked with one or (optionally) two arguments. The first argument specifies a remote repository as in Git; it is either the name of a configured remote or a URL. The second argument specifies a URL; it is usually of the form <transport>://<address>, but any arbitrary string is possible. The GIT_DIR environment variable is set up for the remote helper and can be used to determine where to store additional data or from which directory to invoke auxiliary Git commands.

When Git encounters a URL of the form <transport>://<address>, where <transport> is a protocol that it cannot handle natively, it automatically invokes git remote-<transport> with the full URL as the second argument. If such a URL is encountered directly on the command line, the first argument is the same as the second, and if it is encountered in a configured remote, the first argument is the name of that remote.

A URL of the form <transport>::<address> explicitly instructs Git to invoke git remote-<transport> with <address> as the second argument. If such a URL is encountered directly on the command line, the first argument is <address>, and if it is encountered in a configured remote, the first argument is the name of that remote.

Additionally, when a configured remote has remote.<name>.vcs set to <transport>, Git explicitly invokes git remote-<transport> with <name> as the first argument. If set, the second argument is remote.<name>.url; otherwise, the second argument is omitted.

## INPUT FORMAT
Git sends the remote helper a list of commands on standard input, one per line. The first command is always the capabilities command, in response to which the remote helper must print a list of the capabilities it supports (see below) followed by a blank line. The response to the capabilities command determines what commands Git uses in the remainder of the command stream.

The command stream is terminated by a blank line. In some cases (indicated in the documentation of the relevant commands), this blank line is followed by a payload in some other protocol (e.g., the pack protocol), while in others it indicates the end of input.

### Capabilities
Each remote helper is expected to support only a subset of commands. The operations a helper supports are declared to Git in the response to the capabilities command (see COMMANDS, below).

In the following, we list all defined capabilities and for each we list which commands a helper with that capability must provide.

Capabilities for Pushing

connect

Can attempt to connect to git receive-pack (for pushing), git upload-pack, etc for communication using git’s native packfile protocol. This requires a bidirectional, full-duplex connection. Supported commands: connect.

stateless-connect

Experimental; for internal use only. Can attempt to connect to a remote server for communication using git’s wire-protocol version 2. See the documentation for the stateless-connect command for more information. Supported commands: stateless-connect.

push

Can discover remote refs and push local commits and the history leading up to them to new or existing remote refs. Supported commands: list for-push, push.

export

Can discover remote refs and push specified objects from a fast-import stream to remote refs. Supported commands: list for-push, export.

If a helper advertises connect, Git will use it if possible and fall back to another capability if the helper requests so when connecting (see the connect command under COMMANDS). When choosing between push and export, Git prefers push. Other frontends may have some other order of preference.

no-private-update

When using the refspec capability, git normally updates the private ref on successful push. This update is disabled when the remote-helper declares the capability no-private-update.

Capabilities for Fetching

connect

Can try to connect to git upload-pack (for fetching), git receive-pack, etc for communication using the Git’s native packfile protocol. This requires a bidirectional, full-duplex connection. Supported commands: connect.

stateless-connect

Experimental; for internal use only. Can attempt to connect to a remote server for communication using git’s wire-protocol version 2. See the documentation for the stateless-connect command for more information. Supported commands: stateless-connect.

fetch

Can discover remote refs and transfer objects reachable from them to the local object store. Supported commands: list, fetch.

import

Can discover remote refs and output objects reachable from them as a stream in fast-import format. Supported commands: list, import.

check-connectivity

Can guarantee that when a clone is requested, the received pack is self contained and is connected.

get

Can use the get command to download a file from a given URI.

If a helper advertises connect, Git will use it if possible and fall back to another capability if the helper requests so when connecting (see the connect command under COMMANDS). When choosing between fetch and import, Git prefers fetch. Other frontends may have some other order of preference.

Miscellaneous capabilities

option

For specifying settings like verbosity (how much output to write to stderr) and depth (how much history is wanted in the case of a shallow clone) that affect how other commands are carried out.

refspec <refspec>

For remote helpers that implement import or export, this capability allows the refs to be constrained to a private namespace, instead of writing to refs/heads or refs/remotes directly. It is recommended that all importers providing the import capability use this. It’s mandatory for export. A helper advertising the capability refspec refs/heads/*:refs/svn/origin/branches/* is saying that, when it is asked to import refs/heads/topic, the stream it outputs will update the refs/svn/origin/branches/topic ref.

This capability can be advertised multiple times. The first applicable refspec takes precedence. The left-hand of refspecs advertised with this capability must cover all refs reported by the list command. If no refspec capability is advertised, there is an implied refspec *:*.

When writing remote-helpers for decentralized version control systems, it is advised to keep a local copy of the repository to interact with, and to let the private namespace refs point to this local repository, while the refs/remotes namespace is used to track the remote repository.

bidi-import

This modifies the import capability. The fast-import commands cat-blob and ls can be used by remote-helpers to retrieve information about blobs and trees that already exist in fast-import’s memory. This requires a channel from fast-import to the remote-helper. If it is advertised in addition to "import", Git establishes a pipe from fast-import to the remote-helper’s stdin. It follows that Git and fast-import are both connected to the remote-helper’s stdin. Because Git can send multiple commands to the remote-helper it is required that helpers that use bidi-import buffer all import commands of a batch before sending data to fast-import. This is to prevent mixing commands and fast-import responses on the helper’s stdin.

export-marks <file>

This modifies the export capability, instructing Git to dump the internal marks table to <file> when complete. For details, read up on --export-marks=<file> in git-fast-export(1).

import-marks <file>

This modifies the export capability, instructing Git to load the marks specified in <file> before processing any input. For details, read up on --import-marks=<file> in git-fast-export(1).

signed-tags

This modifies the export capability, instructing Git to pass --signed-tags=verbatim to git-fast-export(1). In the absence of this capability, Git will use --signed-tags=warn-strip.

object-format

This indicates that the helper is able to interact with the remote side using an explicit hash algorithm extension.

## COMMANDS
Commands are given by the caller on the helper’s standard input, one per line.

capabilities

Lists the capabilities of the helper, one per line, ending with a blank line. Each capability may be preceded with *, which marks them mandatory for Git versions using the remote helper to understand. Any unknown mandatory capability is a fatal error. Support for this command is mandatory.

list

Lists the refs, one per line, in the format "<value> <name> [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for a symref, ":<keyword> <value>" for a key-value pair, or "?" to indicate that the helper could not get the value of the ref. A space-separated list of attributes follows the name; unrecognized attributes are ignored. The list ends with a blank line. See REF LIST ATTRIBUTES for a list of currently defined attributes. See REF LIST KEYWORDS for a list of currently defined keywords.

Supported if the helper has the "fetch" or "import" capability.

list for-push

Similar to list, except that it is used if and only if the caller wants to the resulting ref list to prepare push commands. A helper supporting both push and fetch can use this to distinguish for which operation the output of list is going to be used, possibly reducing the amount of work that needs to be performed. Supported if the helper has the "push" or "export" capability.

option <name> <value>

Sets the transport helper option <name> to <value>. Outputs a single line containing one of ok (option successfully set), unsupported (option not recognized) or error <msg> (option <name> is supported but <value> is not valid for it). Options should be set before other commands, and may influence the behavior of those commands. See OPTIONS for a list of currently defined options.

Supported if the helper has the "option" capability.

fetch <sha1> <name>

Fetches the given object, writing the necessary objects to the database. Fetch commands are sent in a batch, one per line, terminated with a blank line. Outputs a single blank line when all fetch commands in the same batch are complete. Only objects which were reported in the output of list with a sha1 may be fetched this way. Optionally may output a lock <file> line indicating the full path of a file under $GIT_DIR/objects/pack which is keeping a pack until refs can be suitably updated. The path must end with .keep. This is a mechanism to name a <pack,idx,keep> tuple by giving only the keep component. The kept pack will not be deleted by a concurrent repack, even though its objects may not be referenced until the fetch completes. The .keep file will be deleted at the conclusion of the fetch.

If option check-connectivity is requested, the helper must output connectivity-ok if the clone is self-contained and connected.

Supported if the helper has the "fetch" capability.

push +<src>:<dst>

Pushes the given local <src> commit or branch to the remote branch described by <dst>. A batch sequence of one or more push commands is terminated with a blank line (if there is only one reference to push, a single push command is followed by a blank line). For example, the following would be two batches of push, the first asking the remote-helper to push the local ref master to the remote ref master and the local HEAD to the remote branch, and the second asking to push ref foo to ref bar (forced update requested by the +).

```
push refs/heads/master:refs/heads/master
push HEAD:refs/heads/branch
\n
push +refs/heads/foo:refs/heads/bar
\n
```

Zero or more protocol options may be entered after the last push command, before the batch’s terminating blank line.

When the push is complete, outputs one or more ok <dst> or error <dst> <why>? lines to indicate success or failure of each pushed ref. The status report output is terminated by a blank line. The option field <why> may be quoted in a C style string if it contains an LF.

Supported if the helper has the "push" capability.

import <name>

Produces a fast-import stream which imports the current value of the named ref. It may additionally import other refs as needed to construct the history efficiently. The script writes to a helper-specific private namespace. The value of the named ref should be written to a location in this namespace derived by applying the refspecs from the "refspec" capability to the name of the ref. Especially useful for interoperability with a foreign versioning system.

Just like push, a batch sequence of one or more import is terminated with a blank line. For each batch of import, the remote helper should produce a fast-import stream terminated by a done command.

Note that if the bidi-import capability is used the complete batch sequence has to be buffered before starting to send data to fast-import to prevent mixing of commands and fast-import responses on the helper’s stdin.

Supported if the helper has the "import" capability.

export

Instructs the remote helper that any subsequent input is part of a fast-import stream (generated by git fast-export) containing objects which should be pushed to the remote. Especially useful for interoperability with a foreign versioning system.

The export-marks and import-marks capabilities, if specified, affect this command in so far as they are passed on to git fast-export, which then will load/store a table of marks for local objects. This can be used to implement for incremental operations.

Supported if the helper has the "export" capability.

connect <service>

Connects to given service. Standard input and standard output of helper are connected to specified service (git prefix is included in service name so e.g. fetching uses git-upload-pack as service) on remote side. Valid replies to this command are empty line (connection established), fallback (no smart transport support, fall back to dumb transports) and just exiting with error message printed (can’t connect, don’t bother trying to fall back). After line feed terminating the positive (empty) response, the output of service starts. After the connection ends, the remote helper exits. Supported if the helper has the "connect" capability.

stateless-connect <service>

Experimental; for internal use only. Connects to the given remote service for communication using git’s wire-protocol version 2. Valid replies to this command are empty line (connection established), fallback (no smart transport support, fall back to dumb transports) and just exiting with error message printed (can’t connect, don’t bother trying to fall back). After line feed terminating the positive (empty) response, the output of the service starts. Messages (both request and response) must consist of zero or more PKT-LINEs, terminating in a flush packet. Response messages will then have a response end packet after the flush packet to indicate the end of a response. The client must not expect the server to store any state in between request-response pairs. After the connection ends, the remote helper exits. Supported if the helper has the "stateless-connect" capability.

get <uri> <path>

Downloads the file from the given <uri> to the given <path>. If <path>.temp exists, then Git assumes that the .temp file is a partial download from a previous attempt and will resume the download from that position.

If a fatal error occurs, the program writes the error message to stderr and exits. The caller should expect that a suitable error message has been printed if the child closes the connection without completing a valid response for the current command.

Additional commands may be supported, as may be determined from capabilities reported by the helper.

## REF LIST ATTRIBUTES
The list command produces a list of refs in which each ref may be followed by a list of attributes. The following ref list attributes are defined.

unchanged

This ref is unchanged since the last import or fetch, although the helper cannot necessarily determine what value that produced.

## REF LIST KEYWORDS
The list command may produce a list of key-value pairs. The following keys are defined.

object-format

The refs are using the given hash algorithm. This keyword is only used if the server and client both support the object-format extension.

## OPTIONS
The following options are defined and (under suitable circumstances) set by Git if the remote helper has the option capability.

option verbosity <n>

Changes the verbosity of messages displayed by the helper. A value of 0 for <n> means that processes operate quietly, and the helper produces only error output. 1 is the default level of verbosity, and higher values of <n> correspond to the number of -v flags passed on the command line.

option progress {true|false}

Enables (or disables) progress messages displayed by the transport helper during a command.

option depth <depth>

Deepens the history of a shallow repository.

option deepen-since <timestamp>

Deepens the history of a shallow repository based on time.

option deepen-not <ref>

Deepens the history of a shallow repository excluding ref. Multiple options add up.

option deepen-relative {true|false}

Deepens the history of a shallow repository relative to current boundary. Only valid when used with "option depth".

option followtags {true|false}

If enabled the helper should automatically fetch annotated tag objects if the object the tag points at was transferred during the fetch command. If the tag is not fetched by the helper a second fetch command will usually be sent to ask for the tag specifically. Some helpers may be able to use this option to avoid a second network connection.

option dry-run {true|false}: If true, pretend the operation completed successfully, but don’t actually change any repository data. For most helpers this only applies to the push, if supported.

option servpath <c-style-quoted-path>

Sets service path (--upload-pack, --receive-pack etc.) for next connect. Remote helper may support this option, but must not rely on this option being set before connect request occurs.

option check-connectivity {true|false}

Request the helper to check connectivity of a clone.

option force {true|false}

Request the helper to perform a force update. Defaults to false.

option cloning {true|false}

Notify the helper this is a clone request (i.e. the current repository is guaranteed empty).

option update-shallow {true|false}

Allow to extend .git/shallow if the new refs require it.

option pushcert {true|false}

GPG sign pushes.

option push-option <string>

Transmit <string> as a push option. As the push option must not contain LF or NUL characters, the string is not encoded.

option from-promisor {true|false}

Indicate that these objects are being fetched from a promisor.

option no-dependents {true|false}

Indicate that only the objects wanted need to be fetched, not their dependents.

option atomic {true|false}

When pushing, request the remote server to update refs in a single atomic transaction. If successful, all refs will be updated, or none will. If the remote side does not support this capability, the push will fail.

option object-format true

Indicate that the caller wants hash algorithm information to be passed back from the remote. This mode is used when fetching refs.

## SEE ALSO
git-remote(1)

git-remote-ext(1)

git-remote-fd(1)

git-fast-import(1)

## GIT
Part of the git(1) suite


gitrevisions

package: git-core

title: gitrevisions(7)

summary: Specifying revisions and ranges for Git

text:
# gitrevisions(7)

## NAME
gitrevisions - Specifying revisions and ranges for Git

## SYNOPSIS
gitrevisions

## DESCRIPTION
Many Git commands take revision parameters as arguments. Depending on the command, they denote a specific commit or, for commands which walk the revision graph (such as git-log(1)), all commits which are reachable from that commit. For commands that walk the revision graph one can also specify a range of revisions explicitly.

In addition, some Git commands (such as git-show(1) and git-push(1)) can also take revision parameters which denote other objects than commits, e.g. blobs ("files") or trees ("directories of files").

## SPECIFYING REVISIONS
A revision parameter <rev> typically, but not necessarily, names a commit object. It uses what is called an extended SHA-1 syntax. Here are various ways to spell object names. The ones listed near the end of this list name trees and blobs contained in a commit.

Note This document shows the "raw" syntax as seen by git. The shell and other UIs might require additional quoting to protect special characters and to avoid word splitting.

<sha1>, e.g. dae86e1950b1277e545cee180551750029cfe735, dae86e

The full SHA-1 object name (40-byte hexadecimal string), or a leading substring that is unique within the repository. E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the same commit object if there is no other object in your repository whose object name starts with dae86e.

<describeOutput>, e.g. v1.7.4.2-679-g3bee7fb

Output from git describe; i.e. a closest tag, optionally followed by a dash and a number of commits, followed by a dash, a g, and an abbreviated object name.

<refname>, e.g. master, heads/master, refs/heads/master

A symbolic ref name. E.g. master typically means the commit object referenced by refs/heads/master. If you happen to have both heads/master and tags/master, you can explicitly say heads/master to tell Git which one you mean. When ambiguous, a <refname> is disambiguated by taking the first match in the following rules:

1.If $GIT_DIR/<refname> exists, that is what you mean (this is usually useful only for HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD, REBASE_HEAD, REVERT_HEAD, CHERRY_PICK_HEAD, BISECT_HEAD and AUTO_MERGE);

2.otherwise, refs/<refname> if it exists;

3.otherwise, refs/tags/<refname> if it exists;

4.otherwise, refs/heads/<refname> if it exists;

5.otherwise, refs/remotes/<refname> if it exists;

6.otherwise, refs/remotes/<refname>/HEAD if it exists.

HEAD

names the commit on which you based the changes in the working tree.

FETCH_HEAD

records the branch which you fetched from a remote repository with your last git fetch invocation.

ORIG_HEAD

is created by commands that move your HEAD in a drastic way (git am, git merge, git rebase, git reset), to record the position of the HEAD before their operation, so that you can easily change the tip of the branch back to the state before you ran them.

MERGE_HEAD

records the commit(s) which you are merging into your branch when you run git merge.

REBASE_HEAD

during a rebase, records the commit at which the operation is currently stopped, either because of conflicts or an edit command in an interactive rebase.

REVERT_HEAD

records the commit which you are reverting when you run git revert.

CHERRY_PICK_HEAD

records the commit which you are cherry-picking when you run git cherry-pick.

BISECT_HEAD

records the current commit to be tested when you run git bisect --no-checkout.

AUTO_MERGE

records a tree object corresponding to the state the ort merge strategy wrote to the working tree when a merge operation resulted in conflicts.

Note that any of the refs/* cases above may come either from the $GIT_DIR/refs directory or from the $GIT_DIR/packed-refs file. While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8.

@

@ alone is a shortcut for HEAD.

[<refname>]@{<date>}, e.g. master@{yesterday}, HEAD@{5 minutes ago}

A ref followed by the suffix @ with a date specification enclosed in a brace pair (e.g. {yesterday}, {1 month 2 weeks 3 days 1 hour 1 second ago} or {1979-02-26 18:30:00}) specifies the value of the ref at a prior point in time. This suffix may only be used immediately following a ref name and the ref must have an existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state of your local ref at a given time; e.g., what was in your local master branch last week. If you want to look at commits made during certain times, see --since and --until.

<refname>@{<n>}, e.g. master@{1}

A ref followed by the suffix @ with an ordinal specification enclosed in a brace pair (e.g. {1}, {15}) specifies the n-th prior value of that ref. For example master@{1} is the immediate prior value of master while master@{5} is the 5th prior value of master. This suffix may only be used immediately following a ref name and the ref must have an existing log ($GIT_DIR/logs/<refname>).

@{<n>}, e.g. @{1}

You can use the @ construct with an empty ref part to get at a reflog entry of the current branch. For example, if you are on branch blabla then @{1} means the same as blabla@{1}.

@{-<n>}, e.g. @{-1}

The construct @{-<n>} means the <n>th branch/commit checked out before the current one.

[<branchname>]@{upstream}, e.g. master@{upstream}, @{u}

A branch B may be set up to build on top of a branch X (configured with branch.<name>.merge) at a remote R (configured with the branch X taken from remote R, typically found at refs/remotes/R/X.

[<branchname>]@{push}, e.g. master@{push}, @{push}

The suffix @{push} reports the branch "where we would push to" if git push were run while branchname was checked out (or the current HEAD if no branchname is specified). Like for @{upstream}, we report the remote-tracking branch that corresponds to that branch at the remote. Here’s an example to make it more clear:

```
$ git config push.default current
$ git config remote.pushdefault myfork
$ git switch -c mybranch origin/master
$ git rev-parse --symbolic-full-name @{upstream}
refs/remotes/origin/master
$ git rev-parse --symbolic-full-name @{push}
refs/remotes/myfork/mybranch
```

Note in the example that we set up a triangular workflow, where we pull from one location and push to another. In a non-triangular workflow, @{push} is the same as @{upstream}, and there is no need for it.

This suffix is also accepted when spelled in uppercase, and means the same thing no matter the case.

<rev>^[<n>], e.g. HEAD^, v1.5.1^0

A suffix ^ to a revision parameter means the first parent of that commit object. ^<n> means the <n>th parent (i.e. <rev>^ is equivalent to <rev>^1). As a special rule, <rev>^0 means the commit itself and is used when <rev> is the object name of a tag object that refers to a commit object.

<rev>~[<n>], e.g. HEAD~, master~3

A suffix ~ to a revision parameter means the first parent of that commit object. A suffix ~<n> to a revision parameter means the commit object that is the <n>th generation ancestor of the named commit object, following only the first parents. I.e. <rev>~3 is equivalent to <rev>^^^ which is equivalent to <rev>^1^1^1. See below for an illustration of the usage of this form.

<rev>^{<type>}, e.g. v0.99.8^{commit}

A suffix ^ followed by an object type name enclosed in brace pair means dereference the object at <rev> recursively until an object of type <type> is found or the object cannot be dereferenced anymore (in which case, barf). For example, if <rev> is a commit-ish, <rev>^{commit} describes the corresponding commit object. Similarly, if <rev> is a tree-ish, <rev>^{tree} describes the corresponding tree object. <rev>^0 is a short-hand for <rev>^{commit}. <rev>^{object} can be used to make sure <rev> names an object that exists, without requiring <rev> to be a tag, and without dereferencing <rev>; because a tag is already an object, it does not have to be dereferenced even once to get to an object.

<rev>^{tag} can be used to ensure that <rev> identifies an existing tag object.

<rev>^{}, e.g. v0.99.8^{}

A suffix ^ followed by an empty brace pair means the object could be a tag, and dereference the tag recursively until a non-tag object is found.

<rev>^{/<text>}, e.g. HEAD^{/fix nasty bug}

A suffix ^ to a revision parameter, followed by a brace pair that contains a text led by a slash, is the same as the :/fix nasty bug syntax below except that it returns the youngest matching commit which is reachable from the <rev> before ^.

:/<text>, e.g. :/fix nasty bug

A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit which is reachable from any ref, including HEAD. The regular expression can match any part of the commit message. To match messages starting with a string, one can use e.g. :/^foo. The special sequence :/! is reserved for modifiers to what is matched. :/!-foo performs a negative match, while :/!!foo matches a literal ! character, followed by foo. Any other sequence beginning with :/! is reserved for now. Depending on the given text, the shell’s word splitting rules might require additional quoting.

<rev>:<path>, e.g. HEAD:README, master:./README

A suffix : followed by a path names the blob or tree at the given path in the tree-ish object named by the part before the colon. A path starting with ./ or ../ is relative to the current working directory. The given path will be converted to be relative to the working tree’s root directory. This is most useful to address a blob or tree from a commit or tree that has the same tree structure as the working tree.

:[<n>:]<path>, e.g. :0:README, :README

A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path, names a blob object in the index at the given path. A missing stage number (and the colon that follows it) names a stage 0 entry. During a merge, stage 1 is the common ancestor, stage 2 is the target branch’s version (typically the current branch), and stage 3 is the version from the branch which is being merged.

Here is an illustration, by Jon Loeliger. Both commit nodes B and C are parents of commit node A. Parent commits are ordered left-to-right.

```
G   H   I   J

 \ /     \ /

  D   E   F

   \  |  / \

    \ | /   |

     \|/    |

      B     C

       \   /

        \ /

         A
```

```
A =      = A^0
B = A^   = A^1     = A~1
C =      = A^2
D = A^^  = A^1^1   = A~2
E = B^2  = A^^2
F = B^3  = A^^3
G = A^^^ = A^1^1^1 = A~3
H = D^2  = B^^2    = A^^^2  = A~2^2
I = F^   = B^3^    = A^^3^
J = F^2  = B^3^2   = A^^3^2
```

## SPECIFYING RANGES
History traversing commands such as git log operate on a set of commits, not just a single commit.

For these commands, specifying a single revision, using the notation described in the previous section, means the set of commits reachable from the given commit.

Specifying several revisions means the set of commits reachable from any of the given commits.

A commit’s reachable set is the commit itself and the commits in its ancestry chain.

There are several notations to specify a set of connected commits (called a "revision range"), illustrated below.

### Commit Exclusions
^<rev> (caret) Notation

To exclude commits reachable from a commit, a prefix ^ notation is used. E.g. ^r1 r2 means commits reachable from r2 but exclude the ones reachable from r1 (i.e. r1 and its ancestors).

### Dotted Range Notations
The .. (two-dot) Range Notation

The ^r1 r2 set operation appears so often that there is a shorthand for it. When you have two commits r1 and r2 (named according to the syntax explained in SPECIFYING REVISIONS above), you can ask for commits that are reachable from r2 excluding those that are reachable from r1 by ^r1 r2 and it can be written as r1..r2.

The ... (three-dot) Symmetric Difference Notation

A similar notation r1...r2 is called symmetric difference of r1 and r2 and is defined as r1 r2 --not $(git merge-base --all r1 r2). It is the set of commits that are reachable from either one of r1 (left side) or r2 (right side) but not from both.

In these two shorthand notations, you can omit one end and let it default to HEAD. For example, origin.. is a shorthand for origin..HEAD and asks "What did I do since I forked from the origin branch?" Similarly, ..origin is a shorthand for HEAD..origin and asks "What did the origin do since I forked from them?" Note that .. would mean HEAD..HEAD which is an empty range that is both reachable and unreachable from HEAD.

Commands that are specifically designed to take two distinct ranges (e.g. "git range-diff R1 R2" to compare two ranges) do exist, but they are exceptions. Unless otherwise noted, all "git" commands that operate on a set of commits work on a single revision range. In other words, writing two "two-dot range notation" next to each other, e.g.

```
$ git log A..B C..D
```

does not specify two revision ranges for most commands. Instead it will name a single connected set of commits, i.e. those that are reachable from either B or D but are reachable from neither A or C. In a linear history like this:

```
---A---B---o---o---C---D
```

because A and B are reachable from C, the revision range specified by these two dotted ranges is a single commit D.

### Other <rev>^ Parent Shorthand Notations
Three other shorthands exist, particularly useful for merge commits, for naming a set that is formed by a commit and its parent commits.

The r1^@ notation means all parents of r1.

The r1^! notation includes commit r1 but excludes all of its parents. By itself, this notation denotes the single commit r1.

The <rev>^-[<n>] notation includes <rev> but excludes the <n>th parent (i.e. a shorthand for <rev>^<n>..<rev>), with <n> = 1 if not given. This is typically useful for merge commits where you can just pass <commit>^- to get all the commits in the branch that was merged in merge commit <commit> (including <commit> itself).

While <rev>^<n> was about specifying a single commit parent, these three notations also consider its parents. For example you can say HEAD^2^@, however you cannot say HEAD^@^2.

## REVISION RANGE SUMMARY
<rev>

Include commits that are reachable from <rev> (i.e. <rev> and its ancestors).

^<rev>

Exclude commits that are reachable from <rev> (i.e. <rev> and its ancestors).

<rev1>..<rev2>

Include commits that are reachable from <rev2> but exclude those that are reachable from <rev1>. When either <rev1> or <rev2> is omitted, it defaults to HEAD.

<rev1>...<rev2>

Include commits that are reachable from either <rev1> or <rev2> but exclude those that are reachable from both. When either <rev1> or <rev2> is omitted, it defaults to HEAD.

<rev>^@, e.g. HEAD^@

A suffix ^ followed by an at sign is the same as listing all parents of <rev> (meaning, include anything reachable from its parents, but not the commit itself).

<rev>^!, e.g. HEAD^!

A suffix ^ followed by an exclamation mark is the same as giving commit <rev> and all its parents prefixed with ^ to exclude them (and their ancestors).

<rev>^-<n>, e.g. HEAD^-, HEAD^-2

Equivalent to <rev>^<n>..<rev>, with <n> = 1 if not given.

Here are a handful of examples using the Loeliger illustration above, with each step in the notation’s expansion and selection carefully spelt out:

```
   Args   Expanded arguments    Selected commits

   D                            G H D

   D F                          G H I J D F

   ^G D                         H D

   ^D B                         E I J F B

   ^D B C                       E I J F B C

   C                            I J F C

   B..C   = ^B C                C

   B...C  = B ^F C              G H D E B C

   B^-    = B^..B

          = ^B^1 B              E I J F B

   C^@    = C^1

          = F                   I J F

   B^@    = B^1 B^2 B^3

          = D E F               D G H E F I J

   C^!    = C ^C^@

          = C ^C^1

          = C ^F                C

   B^!    = B ^B^@

          = B ^B^1 ^B^2 ^B^3

          = B ^D ^E ^F          B

   F^! D  = F ^I ^J D           G H D F
```

## SEE ALSO
git-rev-parse(1)

## GIT
Part of the git(1) suite


gitsubmodules

title: gitsubmodules(7)

summary: Mounting one repository inside another

text:
# gitsubmodules(7)

## NAME
gitsubmodules - Mounting one repository inside another

## SYNOPSIS

```
.gitmodules, $GIT_DIR/config
```

```
git submodule
git <command> --recurse-submodules
```

## DESCRIPTION
A submodule is a repository embedded inside another repository. The submodule has its own history; the repository it is embedded in is called a superproject.

On the filesystem, a submodule usually (but not always - see FORMS below) consists of (i) a Git directory located under the $GIT_DIR/modules/ directory of its superproject, (ii) a working directory inside the superproject’s working directory, and a .git file at the root of the submodule’s working directory pointing to (i).

Assuming the submodule has a Git directory at $GIT_DIR/modules/foo/ and a working directory at path/to/bar/, the superproject tracks the submodule via a gitlink entry in the tree at path/to/bar and an entry in its .gitmodules file (see gitmodules(5)) of the form submodule.foo.path = path/to/bar.

The gitlink entry contains the object name of the commit that the superproject expects the submodule’s working directory to be at.

The section submodule.foo.* in the .gitmodules file gives additional hints to Git’s porcelain layer. For example, the submodule.foo.url setting specifies where to obtain the submodule.

Submodules can be used for at least two different use cases:

1.Using another project while maintaining independent history. Submodules allow you to contain the working tree of another project within your own working tree while keeping the history of both projects separate. Also, since submodules are fixed to an arbitrary version, the other project can be independently developed without affecting the superproject, allowing the superproject project to fix itself to new versions only when desired.

2.Splitting a (logically single) project into multiple repositories and tying them back together. This can be used to overcome current limitations of Git’s implementation to have finer grained access:

•Size of the Git repository: In its current form Git scales up poorly for large repositories containing content that is not compressed by delta computation between trees. For example, you can use submodules to hold large binary assets and these repositories can be shallowly cloned such that you do not have a large history locally.

•Transfer size: In its current form Git requires the whole working tree present. It does not allow partial trees to be transferred in fetch or clone. If the project you work on consists of multiple repositories tied together as submodules in a superproject, you can avoid fetching the working trees of the repositories you are not interested in.

•Access control: By restricting user access to submodules, this can be used to implement read/write policies for different users.

## THE CONFIGURATION OF SUBMODULES
Submodule operations can be configured using the following mechanisms (from highest to lowest precedence):

•The command line for those commands that support taking submodules as part of their pathspecs. Most commands have a boolean flag --recurse-submodules which specifies whether to recurse into submodules. Examples are grep and checkout. Some commands take enums, such as fetch and push, where you can specify how submodules are affected.

•The configuration inside the submodule. This includes $GIT_DIR/config in the submodule, but also settings in the tree such as a .gitattributes or .gitignore files that specify behavior of commands inside the submodule. For example an effect from the submodule’s .gitignore file would be observed when you run git status --ignore-submodules=none in the superproject. This collects information from the submodule’s working directory by running status in the submodule while paying attention to the .gitignore file of the submodule.

The submodule’s $GIT_DIR/config file would come into play when running git push --recurse-submodules=check in the superproject, as this would check if the submodule has any changes not published to any remote. The remotes are configured in the submodule as usual in the $GIT_DIR/config file.

•The configuration file $GIT_DIR/config in the superproject. Git only recurses into active submodules (see "ACTIVE SUBMODULES" section below). If the submodule is not yet initialized, then the configuration inside the submodule does not exist yet, so where to obtain the submodule from is configured here for example.

•The .gitmodules file inside the superproject. A project usually uses this file to suggest defaults for the upstream collection of repositories for the mapping that is required between a submodule’s name and its path. This file mainly serves as the mapping between the name and path of submodules in the superproject, such that the submodule’s Git directory can be located.

If the submodule has never been initialized, this is the only place where submodule configuration is found. It serves as the last fallback to specify where to obtain the submodule from.

## FORMS
Submodules can take the following forms:

•The basic form described in DESCRIPTION with a Git directory, a working directory, a gitlink, and a .gitmodules entry.

•"Old-form" submodule: A working directory with an embedded .git directory, and the tracking gitlink and .gitmodules entry in the superproject. This is typically found in repositories generated using older versions of Git. It is possible to construct these old form repositories manually.

When deinitialized or deleted (see below), the submodule’s Git directory is automatically moved to $GIT_DIR/modules/<name>/ of the superproject.

•Deinitialized submodule: A gitlink, and a .gitmodules entry, but no submodule working directory. The submodule’s Git directory may be there as after deinitializing the Git directory is kept around. The directory which is supposed to be the working directory is empty instead. A submodule can be deinitialized by running git submodule deinit. Besides emptying the working directory, this command only modifies the superproject’s $GIT_DIR/config file, so the superproject’s history is not affected. This can be undone using git submodule init.

•Deleted submodule: A submodule can be deleted by running git rm <submodule-path> && git commit. This can be undone using git revert. The deletion removes the superproject’s tracking data, which are both the gitlink entry and the section in the .gitmodules file. The submodule’s working directory is removed from the file system, but the Git directory is kept around as it to make it possible to checkout past commits without requiring fetching from another repository.

To completely remove a submodule, manually delete $GIT_DIR/modules/<name>/.

## ACTIVE SUBMODULES
A submodule is considered active,

1.if submodule.<name>.active is set to true or

2.if the submodule’s path matches the pathspec in submodule.active or

3.if submodule.<name>.url is set.

and these are evaluated in this order.

For example:

```
[submodule "foo"]

  active = false

  url = https://example.org/foo
[submodule "bar"]

  active = true

  url = https://example.org/bar
[submodule "baz"]

  url = https://example.org/baz
```

In the above config only the submodules bar and baz are active, bar due to (1) and baz due to (3). foo is inactive because (1) takes precedence over (3)

Note that (3) is a historical artefact and will be ignored if the (1) and (2) specify that the submodule is not active. In other words, if we have a submodule.<name>.active set to false or if the submodule’s path is excluded in the pathspec in submodule.active, the url doesn’t matter whether it is present or not. This is illustrated in the example that follows.

```
[submodule "foo"]

  active = true

  url = https://example.org/foo
[submodule "bar"]

  url = https://example.org/bar
[submodule "baz"]

  url = https://example.org/baz
[submodule "bob"]

  ignore = true
[submodule]

  active = b*

  active = :(exclude) baz
```

In here all submodules except baz (foo, bar, bob) are active. foo due to its own active flag and all the others due to the submodule active pathspec, which specifies that any submodule starting with b except baz are also active, regardless of the presence of the .url field.

## WORKFLOW FOR A THIRD PARTY LIBRARY

```
# Add a submodule
git submodule add <URL> <path>
```

```
# Occasionally update the submodule to a new version:
git -C <path> checkout <new-version>
git add <path>
git commit -m "update submodule to new version"
```

```
# See the list of submodules in a superproject
git submodule status
```

```
# See FORMS on removing submodules
```

## WORKFLOW FOR AN ARTIFICIALLY SPLIT REPO

```
# Enable recursion for relevant commands, such that
# regular commands recurse into submodules by default
git config --global submodule.recurse true
```

```
# Unlike most other commands below, clone still needs
# its own recurse flag:
git clone --recurse <URL> <directory>
cd <directory>
```

```
# Get to know the code:
git grep foo
git ls-files --recurse-submodules
```

Note git ls-files also requires its own --recurse-submodules flag.

```
# Get new code
git fetch
git pull --rebase
```

```
# Change worktree
git checkout
git reset
```

## IMPLEMENTATION DETAILS
When cloning or pulling a repository containing submodules the submodules will not be checked out by default; you can instruct clone to recurse into submodules. The init and update subcommands of git submodule will maintain submodules checked out and at an appropriate revision in your working tree. Alternatively you can set submodule.recurse to have checkout recurse into submodules (note that submodule.recurse also affects other Git commands, see git-config(1) for a complete list).

## SEE ALSO
git-submodule(1), gitmodules(5).

## GIT
Part of the git(1) suite


gittutorial

title: gittutorial(7)

summary: A tutorial introduction to Git

text:
# gittutorial(7)

## NAME
gittutorial - A tutorial introduction to Git

## SYNOPSIS

```
git *
```

## DESCRIPTION
This tutorial explains how to import a new project into Git, make changes to it, and share changes with other developers.

If you are instead primarily interested in using Git to fetch a project, for example, to test the latest version, you may prefer to start with the first two chapters of The Git User’s Manual[1].

First, note that you can get documentation for a command such as git log --graph with:

```
$ man git-log
```

or:

```
$ git help log
```

With the latter, you can use the manual viewer of your choice; see git-help(1) for more information.

It is a good idea to introduce yourself to Git with your name and public email address before doing any operation. The easiest way to do so is:

```
$ git config --global user.name "Your Name Comes Here"
$ git config --global user.email you@yourdomain.example.com
```

## IMPORTING A NEW PROJECT
Assume you have a tarball project.tar.gz with your initial work. You can place it under Git revision control as follows.

```
$ tar xzf project.tar.gz
$ cd project
$ git init
```

Git will reply

```
Initialized empty Git repository in .git/
```

You’ve now initialized the working directory—you may notice a new directory created, named .git.

Next, tell Git to take a snapshot of the contents of all files under the current directory (note the .), with git add:

```
$ git add .
```

This snapshot is now stored in a temporary staging area which Git calls the "index". You can permanently store the contents of the index in the repository with git commit:

```
$ git commit
```

This will prompt you for a commit message. You’ve now stored the first version of your project in Git.

## MAKING CHANGES
Modify some files, then add their updated contents to the index:

```
$ git add file1 file2 file3
```

You are now ready to commit. You can see what is about to be committed using git diff with the --cached option:

```
$ git diff --cached
```

(Without --cached, git diff will show you any changes that you’ve made but not yet added to the index.) You can also get a brief summary of the situation with git status:

```
$ git status
On branch master
Changes to be committed:

  (use "git restore --staged <file>..." to unstage)

        modified:   file1

        modified:   file2

        modified:   file3
```

If you need to make any further adjustments, do so now, and then add any newly modified content to the index. Finally, commit your changes with:

```
$ git commit
```

This will again prompt you for a message describing the change, and then record a new version of the project.

Alternatively, instead of running git add beforehand, you can use

```
$ git commit -a
```

which will automatically notice any modified (but not new) files, add them to the index, and commit, all in one step.

A note on commit messages: Though not required, it’s a good idea to begin the commit message with a single short (no more than 50 characters) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.

## GIT TRACKS CONTENT NOT FILES
Many revision control systems provide an add command that tells the system to start tracking changes to a new file. Git’s add command does something simpler and more powerful: git add is used both for new and newly modified files, and in both cases it takes a snapshot of the given files and stages that content in the index, ready for inclusion in the next commit.

## VIEWING PROJECT HISTORY
At any point you can view the history of your changes using

```
$ git log
```

If you also want to see complete diffs at each step, use

```
$ git log -p
```

Often the overview of the change is useful to get a feel of each step

```
$ git log --stat --summary
```

## MANAGING BRANCHES
A single Git repository can maintain multiple branches of development. To create a new branch named experimental, use

```
$ git branch experimental
```

If you now run

```
$ git branch
```

you’ll get a list of all existing branches:

```
  experimental
* master
```

The experimental branch is the one you just created, and the master branch is a default branch that was created for you automatically. The asterisk marks the branch you are currently on; type

```
$ git switch experimental
```

to switch to the experimental branch. Now edit a file, commit the change, and switch back to the master branch:

```
(edit file)
$ git commit -a
$ git switch master
```

Check that the change you made is no longer visible, since it was made on the experimental branch and you’re back on the master branch.

You can make a different change on the master branch:

```
(edit file)
$ git commit -a
```

at this point the two branches have diverged, with different changes made in each. To merge the changes made in experimental into master, run

```
$ git merge experimental
```

If the changes don’t conflict, you’re done. If there are conflicts, markers will be left in the problematic files showing the conflict;

```
$ git diff
```

will show this. Once you’ve edited the files to resolve the conflicts,

```
$ git commit -a
```

will commit the result of the merge. Finally,

```
$ gitk
```

will show a nice graphical representation of the resulting history.

At this point you could delete the experimental branch with

```
$ git branch -d experimental
```

This command ensures that the changes in the experimental branch are already in the current branch.

If you develop on a branch crazy-idea, then regret it, you can always delete the branch with

```
$ git branch -D crazy-idea
```

Branches are cheap and easy, so this is a good way to try something out.

## USING GIT FOR COLLABORATION
Suppose that Alice has started a new project with a Git repository in /home/alice/project, and that Bob, who has a home directory on the same machine, wants to contribute.

Bob begins with:

```
bob$ git clone /home/alice/project myrepo
```

This creates a new directory myrepo containing a clone of Alice’s repository. The clone is on an equal footing with the original project, possessing its own copy of the original project’s history.

Bob then makes some changes and commits them:

```
(edit files)
bob$ git commit -a
(repeat as necessary)
```

When he’s ready, he tells Alice to pull changes from the repository at /home/bob/myrepo. She does this with:

```
alice$ cd /home/alice/project
alice$ git pull /home/bob/myrepo master
```

This merges the changes from Bob’s master branch into Alice’s current branch. If Alice has made her own changes in the meantime, then she may need to manually fix any conflicts.

The pull command thus performs two operations: it fetches changes from a remote branch, then merges them into the current branch.

Note that in general, Alice would want her local changes committed before initiating this pull. If Bob’s work conflicts with what Alice did since their histories forked, Alice will use her working tree and the index to resolve conflicts, and existing local changes will interfere with the conflict resolution process (Git will still perform the fetch but will refuse to merge — Alice will have to get rid of her local changes in some way and pull again when this happens).

Alice can peek at what Bob did without merging first, using the fetch command; this allows Alice to inspect what Bob did, using a special symbol FETCH_HEAD, in order to determine if he has anything worth pulling, like this:

```
alice$ git fetch /home/bob/myrepo master
alice$ git log -p HEAD..FETCH_HEAD
```

This operation is safe even if Alice has uncommitted local changes. The range notation HEAD..FETCH_HEAD means "show everything that is reachable from the FETCH_HEAD but exclude anything that is reachable from HEAD". Alice already knows everything that leads to her current state (HEAD), and reviews what Bob has in his state (FETCH_HEAD) that she has not seen with this command.

If Alice wants to visualize what Bob did since their histories forked she can issue the following command:

```
$ gitk HEAD..FETCH_HEAD
```

This uses the same two-dot range notation we saw earlier with git log.

Alice may want to view what both of them did since they forked. She can use three-dot form instead of the two-dot form:

```
$ gitk HEAD...FETCH_HEAD
```

This means "show everything that is reachable from either one, but exclude anything that is reachable from both of them".

Please note that these range notations can be used with both gitk and git log.

After inspecting what Bob did, if there is nothing urgent, Alice may decide to continue working without pulling from Bob. If Bob’s history does have something Alice would immediately need, Alice may choose to stash her work-in-progress first, do a pull, and then finally unstash her work-in-progress on top of the resulting history.

When you are working in a small closely knit group, it is not unusual to interact with the same repository over and over again. By defining remote repository shorthand, you can make it easier:

```
alice$ git remote add bob /home/bob/myrepo
```

With this, Alice can perform the first part of the pull operation alone using the git fetch command without merging them with her own branch, using:

```
alice$ git fetch bob
```

Unlike the longhand form, when Alice fetches from Bob using a remote repository shorthand set up with git remote, what was fetched is stored in a remote-tracking branch, in this case bob/master. So after this:

```
alice$ git log -p master..bob/master
```

shows a list of all the changes that Bob made since he branched from Alice’s master branch.

After examining those changes, Alice could merge the changes into her master branch:

```
alice$ git merge bob/master
```

This merge can also be done by pulling from her own remote-tracking branch, like this:

```
alice$ git pull . remotes/bob/master
```

Note that git pull always merges into the current branch, regardless of what else is given on the command line.

Later, Bob can update his repo with Alice’s latest changes using

```
bob$ git pull
```

Note that he doesn’t need to give the path to Alice’s repository; when Bob cloned Alice’s repository, Git stored the location of her repository in the repository configuration, and that location is used for pulls:

```
bob$ git config --get remote.origin.url
/home/alice/project
```

(The complete configuration created by git clone is visible using git config -l, and the git-config(1) man page explains the meaning of each option.)

Git also keeps a pristine copy of Alice’s master branch under the name origin/master:

```
bob$ git branch -r

  origin/master
```

If Bob later decides to work from a different host, he can still perform clones and pulls using the ssh protocol:

```
bob$ git clone alice.org:/home/alice/project myrepo
```

Alternatively, Git has a native protocol, or can use http; see git-pull(1) for details.

Git can also be used in a CVS-like mode, with a central repository that various users push changes to; see git-push(1) and gitcvs-migration(7).

## EXPLORING HISTORY
Git history is represented as a series of interrelated commits. We have already seen that the git log command can list those commits. Note that first line of each git log entry also gives a name for the commit:

```
$ git log
commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
Author: Junio C Hamano <junkio@cox.net>
Date:   Tue May 16 17:18:22 2006 -0700

    merge-base: Clarify the comments on post processing.
```

We can give this name to git show to see the details about this commit.

```
$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
```

But there are other ways to refer to commits. You can use any initial part of the name that is long enough to uniquely identify the commit:

```
$ git show c82a22c39c   # the first few characters of the name are

                        # usually enough
$ git show HEAD         # the tip of the current branch
$ git show experimental # the tip of the "experimental" branch
```

Every commit usually has one "parent" commit which points to the previous state of the project:

```
$ git show HEAD^  # to see the parent of HEAD
$ git show HEAD^^ # to see the grandparent of HEAD
$ git show HEAD~4 # to see the great-great grandparent of HEAD
```

Note that merge commits may have more than one parent:

```
$ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)
$ git show HEAD^2 # show the second parent of HEAD
```

You can also give commits names of your own; after running

```
$ git tag v2.5 1b2e1d63ff
```

you can refer to 1b2e1d63ff by the name v2.5. If you intend to share this name with other people (for example, to identify a release version), you should create a "tag" object, and perhaps sign it; see git-tag(1) for details.

Any Git command that needs to know a commit can take any of these names. For example:

```
$ git diff v2.5 HEAD     # compare the current HEAD to v2.5
$ git branch stable v2.5 # start a new branch named "stable" based

                         # at v2.5
$ git reset --hard HEAD^ # reset your current branch and working

                         # directory to its state at HEAD^
```

Be careful with that last command: in addition to losing any changes in the working directory, it will also remove all later commits from this branch. If this branch is the only branch containing those commits, they will be lost. Also, don’t use git reset on a publicly-visible branch that other developers pull from, as it will force needless merges on other developers to clean up the history. If you need to undo changes that you have pushed, use git revert instead.

The git grep command can search for strings in any version of your project, so

```
$ git grep "hello" v2.5
```

searches for all occurrences of "hello" in v2.5.

If you leave out the commit name, git grep will search any of the files it manages in your current directory. So

```
$ git grep "hello"
```

is a quick way to search just the files that are tracked by Git.

Many Git commands also take sets of commits, which can be specified in a number of ways. Here are some examples with git log:

```
$ git log v2.5..v2.6            # commits between v2.5 and v2.6
$ git log v2.5..                # commits since v2.5
$ git log --since="2 weeks ago" # commits from the last 2 weeks
$ git log v2.5.. Makefile       # commits since v2.5 which modify

                                # Makefile
```

You can also give git log a "range" of commits where the first is not necessarily an ancestor of the second; for example, if the tips of the branches stable and master diverged from a common commit some time ago, then

```
$ git log stable..master
```

will list commits made in the master branch but not in the stable branch, while

```
$ git log master..stable
```

will show the list of commits made on the stable branch but not the master branch.

The git log command has a weakness: it must present commits in a list. When the history has lines of development that diverged and then merged back together, the order in which git log presents those commits is meaningless.

Most projects with multiple contributors (such as the Linux kernel, or Git itself) have frequent merges, and gitk does a better job of visualizing their history. For example,

```
$ gitk --since="2 weeks ago" drivers/
```

allows you to browse any commits from the last 2 weeks of commits that modified files under the drivers directory. (Note: you can adjust gitk’s fonts by holding down the control key while pressing "-" or "+".)

Finally, most commands that take filenames will optionally allow you to precede any filename by a commit, to specify a particular version of the file:

```
$ git diff v2.5:Makefile HEAD:Makefile.in
```

You can also use git show to see any such file:

```
$ git show v2.5:Makefile
```

## NEXT STEPS
This tutorial should be enough to perform basic distributed revision control for your projects. However, to fully understand the depth and power of Git you need to understand two simple ideas on which it is based:

•The object database is the rather elegant system used to store the history of your project—files, directories, and commits.

•The index file is a cache of the state of a directory tree, used to create commits, check out working directories, and hold the various trees involved in a merge.

Part two of this tutorial explains the object database, the index file, and a few other odds and ends that you’ll need to make the most of Git. You can find it at gittutorial-2(7).

If you don’t want to continue with that right away, a few other digressions that may be interesting at this point are:

•git-format-patch(1), git-am(1): These convert series of git commits into emailed patches, and vice versa, useful for projects such as the Linux kernel which rely heavily on emailed patches.

•git-bisect(1): When there is a regression in your project, one way to track down the bug is by searching through the history to find the exact commit that’s to blame. git bisect can help you perform a binary search for that commit. It is smart enough to perform a close-to-optimal search even in the case of complex non-linear history with lots of merged branches.

•gitworkflows(7): Gives an overview of recommended workflows.

•giteveryday(7): Everyday Git with 20 Commands Or So.

•gitcvs-migration(7): Git for CVS users.

## SEE ALSO
gittutorial-2(7), gitcvs-migration(7), gitcore-tutorial(7), gitglossary(7), git-help(1), gitworkflows(7), giteveryday(7), The Git User’s Manual[1]

## GIT
Part of the git(1) suite

## NOTES
1.

The Git User’s Manual

file:///usr/share/doc/git/user-manual.html


title: gittutorial-2(7)

text:
# gittutorial-2(7)

## NAME
gittutorial-2 - A tutorial introduction to Git: part two

## SYNOPSIS

```
git *
```

## DESCRIPTION
You should work through gittutorial(7) before reading this tutorial.

The goal of this tutorial is to introduce two fundamental pieces of Git’s architecture—the object database and the index file—and to provide the reader with everything necessary to understand the rest of the Git documentation.

## THE GIT OBJECT DATABASE
Let’s start a new project and create a small amount of history:

```
$ mkdir test-project
$ cd test-project
$ git init
Initialized empty Git repository in .git/
$ echo 'hello world' > file.txt
$ git add .
$ git commit -a -m "initial commit"
[master (root-commit) 54196cc] initial commit

 1 file changed, 1 insertion(+)

 create mode 100644 file.txt
$ echo 'hello world!' >file.txt
$ git commit -a -m "add emphasis"
[master c4d59f3] add emphasis

 1 file changed, 1 insertion(+), 1 deletion(-)
```

What are the 7 digits of hex that Git responded to the commit with?

We saw in part one of the tutorial that commits have names like this. It turns out that every object in the Git history is stored under a 40-digit hex name. That name is the SHA-1 hash of the object’s contents; among other things, this ensures that Git will never store the same data twice (since identical data is given an identical SHA-1 name), and that the contents of a Git object will never change (since that would change the object’s name as well). The 7 char hex strings here are simply the abbreviation of such 40 character long strings. Abbreviations can be used everywhere where the 40 character strings can be used, so long as they are unambiguous.

It is expected that the content of the commit object you created while following the example above generates a different SHA-1 hash than the one shown above because the commit object records the time when it was created and the name of the person performing the commit.

We can ask Git about this particular object with the cat-file command. Don’t copy the 40 hex digits from this example but use those from your own version. Note that you can shorten it to only a few characters to save yourself typing all 40 hex digits:

```
$ git cat-file -t 54196cc2
commit
$ git cat-file commit 54196cc2
tree 92b8b694ffb1675e5975148e1121810081dbdffe
author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
initial commit
```

A tree can refer to one or more "blob" objects, each corresponding to a file. In addition, a tree can also refer to other tree objects, thus creating a directory hierarchy. You can examine the contents of any tree using ls-tree (remember that a long enough initial portion of the SHA-1 will also work):

```
$ git ls-tree 92b8b694
100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad    file.txt
```

Thus we see that this tree has one file in it. The SHA-1 hash is a reference to that file’s data:

```
$ git cat-file -t 3b18e512
blob
```

A "blob" is just file data, which we can also examine with cat-file:

```
$ git cat-file blob 3b18e512
hello world
```

Note that this is the old file data; so the object that Git named in its response to the initial tree was a tree with a snapshot of the directory state that was recorded by the first commit.

All of these objects are stored under their SHA-1 names inside the Git directory:

```
$ find .git/objects/
.git/objects/
.git/objects/pack
.git/objects/info
.git/objects/3b
.git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad
.git/objects/92
.git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe
.git/objects/54
.git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7
.git/objects/a0
.git/objects/a0/423896973644771497bdc03eb99d5281615b51
.git/objects/d0
.git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59
.git/objects/c4
.git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241
```

and the contents of these files is just the compressed data plus a header identifying their length and their type. The type is either a blob, a tree, a commit, or a tag.

The simplest commit to find is the HEAD commit, which we can find from .git/HEAD:

```
$ cat .git/HEAD
ref: refs/heads/master
```

As you can see, this tells us which branch we’re currently on, and it tells us this by naming a file under the .git directory, which itself contains a SHA-1 name referring to a commit object, which we can examine with cat-file:

```
$ cat .git/refs/heads/master
c4d59f390b9cfd4318117afde11d601c1085f241
$ git cat-file -t c4d59f39
commit
$ git cat-file commit c4d59f39
tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59
parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7
author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
add emphasis
```

The "tree" object here refers to the new state of the tree:

```
$ git ls-tree d0492b36
100644 blob a0423896973644771497bdc03eb99d5281615b51    file.txt
$ git cat-file blob a0423896
hello world!
```

and the "parent" object refers to the previous commit:

```
$ git cat-file commit 54196cc2
tree 92b8b694ffb1675e5975148e1121810081dbdffe
author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
initial commit
```

The tree object is the tree we examined first, and this commit is unusual in that it lacks any parent.

Most commits have only one parent, but it is also common for a commit to have multiple parents. In that case the commit represents a merge, with the parent references pointing to the heads of the merged branches.

Besides blobs, trees, and commits, the only remaining type of object is a "tag", which we won’t discuss here; refer to git-tag(1) for details.

So now we know how Git uses the object database to represent a project’s history:

•"commit" objects refer to "tree" objects representing the snapshot of a directory tree at a particular point in the history, and refer to "parent" commits to show how they’re connected into the project history.

•"tree" objects represent the state of a single directory, associating directory names to "blob" objects containing file data and "tree" objects containing subdirectory information.

•"blob" objects contain file data without any other structure.

•References to commit objects at the head of each branch are stored in files under .git/refs/heads/.

•The name of the current branch is stored in .git/HEAD.

Note, by the way, that lots of commands take a tree as an argument. But as we can see above, a tree can be referred to in many different ways—by the SHA-1 name for that tree, by the name of a commit that refers to the tree, by the name of a branch whose head refers to that tree, etc.--and most such commands can accept any of these names.

In command synopses, the word "tree-ish" is sometimes used to designate such an argument.

## THE INDEX FILE
The primary tool we’ve been using to create commits is git-commit -a, which creates a commit including every change you’ve made to your working tree. But what if you want to commit changes only to certain files? Or only certain changes to certain files?

If we look at the way commits are created under the cover, we’ll see that there are more flexible ways creating commits.

Continuing with our test-project, let’s modify file.txt again:

```
$ echo "hello world, again" >>file.txt
```

but this time instead of immediately making the commit, let’s take an intermediate step, and ask for diffs along the way to keep track of what’s happening:

```
$ git diff
--- a/file.txt
+++ b/file.txt
@@ -1 +1,2 @@

 hello world!
+hello world, again
$ git add file.txt
$ git diff
```

The last diff is empty, but no new commits have been made, and the head still doesn’t contain the new line:

```
$ git diff HEAD
diff --git a/file.txt b/file.txt
index a042389..513feba 100644
--- a/file.txt
+++ b/file.txt
@@ -1 +1,2 @@

 hello world!
+hello world, again
```

So git diff is comparing against something other than the head. The thing that it’s comparing against is actually the index file, which is stored in .git/index in a binary format, but whose contents we can examine with ls-files:

```
$ git ls-files --stage
100644 513feba2e53ebbd2532419ded848ba19de88ba00 0       file.txt
$ git cat-file -t 513feba2
blob
$ git cat-file blob 513feba2
hello world!
hello world, again
```

So what our git add did was store a new blob and then put a reference to it in the index file. If we modify the file again, we’ll see that the new modifications are reflected in the git diff output:

```
$ echo 'again?' >>file.txt
$ git diff
index 513feba..ba3da7b 100644
--- a/file.txt
+++ b/file.txt
@@ -1,2 +1,3 @@

 hello world!

 hello world, again
+again?
```

With the right arguments, git diff can also show us the difference between the working directory and the last commit, or between the index and the last commit:

```
$ git diff HEAD
diff --git a/file.txt b/file.txt
index a042389..ba3da7b 100644
--- a/file.txt
+++ b/file.txt
@@ -1 +1,3 @@

 hello world!
+hello world, again
+again?
$ git diff --cached
diff --git a/file.txt b/file.txt
index a042389..513feba 100644
--- a/file.txt
+++ b/file.txt
@@ -1 +1,2 @@

 hello world!
+hello world, again
```

At any time, we can create a new commit using git commit (without the "-a" option), and verify that the state committed only includes the changes stored in the index file, not the additional change that is still only in our working tree:

```
$ git commit -m "repeat"
$ git diff HEAD
diff --git a/file.txt b/file.txt
index 513feba..ba3da7b 100644
--- a/file.txt
+++ b/file.txt
@@ -1,2 +1,3 @@

 hello world!

 hello world, again
+again?
```

So by default git commit uses the index to create the commit, not the working tree; the "-a" option to commit tells it to first update the index with all changes in the working tree.

Finally, it’s worth looking at the effect of git add on the index file:

```
$ echo "goodbye, world" >closing.txt
$ git add closing.txt
```

The effect of the git add was to add one entry to the index file:

```
$ git ls-files --stage
100644 8b9743b20d4b15be3955fc8d5cd2b09cd2336138 0       closing.txt
100644 513feba2e53ebbd2532419ded848ba19de88ba00 0       file.txt
```

And, as you can see with cat-file, this new entry refers to the current contents of the file:

```
$ git cat-file blob 8b9743b2
goodbye, world
```

The "status" command is a useful way to get a quick summary of the situation:

```
$ git status
On branch master
Changes to be committed:

  (use "git restore --staged <file>..." to unstage)

        new file:   closing.txt
Changes not staged for commit:

  (use "git add <file>..." to update what will be committed)

  (use "git restore <file>..." to discard changes in working directory)

        modified:   file.txt
```

Since the current state of closing.txt is cached in the index file, it is listed as "Changes to be committed". Since file.txt has changes in the working directory that aren’t reflected in the index, it is marked "changed but not updated". At this point, running "git commit" would create a commit that added closing.txt (with its new contents), but that didn’t modify file.txt.

Also, note that a bare git diff shows the changes to file.txt, but not the addition of closing.txt, because the version of closing.txt in the index file is identical to the one in the working directory.

In addition to being the staging area for new commits, the index file is also populated from the object database when checking out a branch, and is used to hold the trees involved in a merge operation. See gitcore-tutorial(7) and the relevant man pages for details.

## WHAT NEXT?
At this point you should know everything necessary to read the man pages for any of the git commands; one good place to start would be with the commands mentioned in giteveryday(7). You should be able to find any unknown jargon in gitglossary(7).

The Git User’s Manual[1] provides a more comprehensive introduction to Git.

gitcvs-migration(7) explains how to import a CVS repository into Git, and shows how to use Git in a CVS-like way.

For some interesting examples of Git use, see the howtos[2].

For Git developers, gitcore-tutorial(7) goes into detail on the lower-level Git mechanisms involved in, for example, creating a new commit.

## SEE ALSO
gittutorial(7), gitcvs-migration(7), gitcore-tutorial(7), gitglossary(7), git-help(1), giteveryday(7), The Git User’s Manual[1]

## GIT
Part of the git(1) suite

## NOTES
1.

Git User’s Manual

file:///usr/share/doc/git/user-manual.html

2.

howtos

file:///usr/share/doc/git/howto-index.html


gitworkflows

title: gitworkflows(7)

text:
# gitworkflows(7)

## NAME
gitworkflows - An overview of recommended workflows with Git

## SYNOPSIS

```
git *
```

## DESCRIPTION
This document attempts to write down and motivate some of the workflow elements used for git.git itself. Many ideas apply in general, though the full workflow is rarely required for smaller projects with fewer people involved.

We formulate a set of rules for quick reference, while the prose tries to motivate each of them. Do not always take them literally; you should value good reasons for your actions higher than manpages such as this one.

## SEPARATE CHANGES
As a general rule, you should try to split your changes into small logical steps, and commit each of them. They should be consistent, working independently of any later commits, pass the test suite, etc. This makes the review process much easier, and the history much more useful for later inspection and analysis, for example with git-blame(1) and git-bisect(1).

To achieve this, try to split your work into small steps from the very beginning. It is always easier to squash a few commits together than to split one big commit into several. Don’t be afraid of making too small or imperfect steps along the way. You can always go back later and edit the commits with git rebase --interactive before you publish them. You can use git stash push --keep-index to run the test suite independent of other uncommitted changes; see the EXAMPLES section of git-stash(1).

## MANAGING BRANCHES
There are two main tools that can be used to include changes from one branch on another: git-merge(1) and git-cherry-pick(1).

Merges have many advantages, so we try to solve as many problems as possible with merges alone. Cherry-picking is still occasionally useful; see "Merging upwards" below for an example.

Most importantly, merging works at the branch level, while cherry-picking works at the commit level. This means that a merge can carry over the changes from 1, 10, or 1000 commits with equal ease, which in turn means the workflow scales much better to a large number of contributors (and contributions). Merges are also easier to understand because a merge commit is a "promise" that all changes from all its parents are now included.

There is a tradeoff of course: merges require a more careful branch management. The following subsections discuss the important points.

### Graduation
As a given feature goes from experimental to stable, it also "graduates" between the corresponding branches of the software. git.git uses the following integration branches:

•maint tracks the commits that should go into the next "maintenance release", i.e., update of the last released stable version;

•master tracks the commits that should go into the next release;

•next is intended as a testing branch for topics being tested for stability for master.

There is a fourth official branch that is used slightly differently:

•seen (patches seen by the maintainer) is an integration branch for things that are not quite ready for inclusion yet (see "Integration Branches" below).

Each of the four branches is usually a direct descendant of the one above it.

Conceptually, the feature enters at an unstable branch (usually next or seen), and "graduates" to master for the next release once it is considered stable enough.

### Merging upwards
The "downwards graduation" discussed above cannot be done by actually merging downwards, however, since that would merge all changes on the unstable branch into the stable one. Hence the following:

Example 1. Merge upwards

Always commit your fixes to the oldest supported branch that requires them. Then (periodically) merge the integration branches upwards into each other.

This gives a very controlled flow of fixes. If you notice that you have applied a fix to e.g. master that is also required in maint, you will need to cherry-pick it (using git-cherry-pick(1)) downwards. This will happen a few times and is nothing to worry about unless you do it very frequently.

### Topic branches
Any nontrivial feature will require several patches to implement, and may get extra bugfixes or improvements during its lifetime.

Committing everything directly on the integration branches leads to many problems: Bad commits cannot be undone, so they must be reverted one by one, which creates confusing histories and further error potential when you forget to revert part of a group of changes. Working in parallel mixes up the changes, creating further confusion.

Use of "topic branches" solves these problems. The name is pretty self explanatory, with a caveat that comes from the "merge upwards" rule above:

Example 2. Topic branches

Make a side branch for every topic (feature, bugfix, ...). Fork it off at the oldest integration branch that you will eventually want to merge it into.

Many things can then be done very naturally:

•To get the feature/bugfix into an integration branch, simply merge it. If the topic has evolved further in the meantime, merge again. (Note that you do not necessarily have to merge it to the oldest integration branch first. For example, you can first merge a bugfix to next, give it some testing time, and merge to maint when you know it is stable.)

•If you find you need new features from the branch other to continue working on your topic, merge other to topic. (However, do not do this "just habitually", see below.)

•If you find you forked off the wrong branch and want to move it "back in time", use git-rebase(1).

Note that the last point clashes with the other two: a topic that has been merged elsewhere should not be rebased. See the section on RECOVERING FROM UPSTREAM REBASE in git-rebase(1).

We should point out that "habitually" (regularly for no real reason) merging an integration branch into your topics — and by extension, merging anything upstream into anything downstream on a regular basis — is frowned upon:

Example 3. Merge to downstream only at well-defined points

Do not merge to downstream except with a good reason: upstream API changes affect your branch; your branch no longer merges to upstream cleanly; etc.

Otherwise, the topic that was merged to suddenly contains more than a single (well-separated) change. The many resulting small merges will greatly clutter up history. Anyone who later investigates the history of a file will have to find out whether that merge affected the topic in development. An upstream might even inadvertently be merged into a "more stable" branch. And so on.

### Throw-away integration
If you followed the last paragraph, you will now have many small topic branches, and occasionally wonder how they interact. Perhaps the result of merging them does not even work? But on the other hand, we want to avoid merging them anywhere "stable" because such merges cannot easily be undone.

The solution, of course, is to make a merge that we can undo: merge into a throw-away branch.

Example 4. Throw-away integration branches

To test the interaction of several topics, merge them into a throw-away branch. You must never base any work on such a branch!

If you make it (very) clear that this branch is going to be deleted right after the testing, you can even publish this branch, for example to give the testers a chance to work with it, or other developers a chance to see if their in-progress work will be compatible. git.git has such an official throw-away integration branch called seen.

### Branch management for a release
Assuming you are using the merge approach discussed above, when you are releasing your project you will need to do some additional branch management work.

A feature release is created from the master branch, since master tracks the commits that should go into the next feature release.

The master branch is supposed to be a superset of maint. If this condition does not hold, then maint contains some commits that are not included on master. The fixes represented by those commits will therefore not be included in your feature release.

To verify that master is indeed a superset of maint, use git log:

Example 5. Verify master is a superset of maint

git log master..maint

This command should not list any commits. Otherwise, check out master and merge maint into it.

Now you can proceed with the creation of the feature release. Apply a tag to the tip of master indicating the release version:

Example 6. Release tagging

git tag -s -m "Git X.Y.Z" vX.Y.Z master

You need to push the new tag to a public Git server (see "DISTRIBUTED WORKFLOWS" below). This makes the tag available to others tracking your project. The push could also trigger a post-update hook to perform release-related items such as building release tarballs and preformatted documentation pages.

Similarly, for a maintenance release, maint is tracking the commits to be released. Therefore, in the steps above simply tag and push maint rather than master.

### Maintenance branch management after a feature release
After a feature release, you need to manage your maintenance branches.

First, if you wish to continue to release maintenance fixes for the feature release made before the recent one, then you must create another branch to track commits for that previous release.

To do this, the current maintenance branch is copied to another branch named with the previous release version number (e.g. maint-X.Y.(Z-1) where X.Y.Z is the current release).

Example 7. Copy maint

git branch maint-X.Y.(Z-1) maint

The maint branch should now be fast-forwarded to the newly released code so that maintenance fixes can be tracked for the current release:

Example 8. Update maint to new release

•git checkout maint

•git merge --ff-only master

If the merge fails because it is not a fast-forward, then it is possible some fixes on maint were missed in the feature release. This will not happen if the content of the branches was verified as described in the previous section.

### Branch management for next and seen after a feature release
After a feature release, the integration branch next may optionally be rewound and rebuilt from the tip of master using the surviving topics on next:

Example 9. Rewind and rebuild next

•git switch -C next master

•git merge ai/topic_in_next1

•git merge ai/topic_in_next2

•...

The advantage of doing this is that the history of next will be clean. For example, some topics merged into next may have initially looked promising, but were later found to be undesirable or premature. In such a case, the topic is reverted out of next but the fact remains in the history that it was once merged and reverted. By recreating next, you give another incarnation of such topics a clean slate to retry, and a feature release is a good point in history to do so.

If you do this, then you should make a public announcement indicating that next was rewound and rebuilt.

The same rewind and rebuild process may be followed for seen. A public announcement is not necessary since seen is a throw-away branch, as described above.

## DISTRIBUTED WORKFLOWS
After the last section, you should know how to manage topics. In general, you will not be the only person working on the project, so you will have to share your work.

Roughly speaking, there are two important workflows: merge and patch. The important difference is that the merge workflow can propagate full history, including merges, while patches cannot. Both workflows can be used in parallel: in git.git, only subsystem maintainers use the merge workflow, while everyone else sends patches.

Note that the maintainer(s) may impose restrictions, such as "Signed-off-by" requirements, that all commits/patches submitted for inclusion must adhere to. Consult your project’s documentation for more information.

### Merge workflow
The merge workflow works by copying branches between upstream and downstream. Upstream can merge contributions into the official history; downstream base their work on the official history.

There are three main tools that can be used for this:

•git-push(1) copies your branches to a remote repository, usually to one that can be read by all involved parties;

•git-fetch(1) that copies remote branches to your repository; and

•git-pull(1) that does fetch and merge in one go.

Note the last point. Do not use git pull unless you actually want to merge the remote branch.

Getting changes out is easy:

Example 10. Push/pull: Publishing branches/topics

git push <remote> <branch> and tell everyone where they can fetch from.

You will still have to tell people by other means, such as mail. (Git provides the git-request-pull(1) to send preformatted pull requests to upstream maintainers to simplify this task.)

If you just want to get the newest copies of the integration branches, staying up to date is easy too:

Example 11. Push/pull: Staying up to date

Use git fetch <remote> or git remote update to stay up to date.

Then simply fork your topic branches from the stable remotes as explained earlier.

If you are a maintainer and would like to merge other people’s topic branches to the integration branches, they will typically send a request to do so by mail. Such a request looks like

```
Please pull from

    <URL> <branch>
```

In that case, git pull can do the fetch and merge in one go, as follows.

Example 12. Push/pull: Merging remote topics

git pull <URL> <branch>

Occasionally, the maintainer may get merge conflicts when they try to pull changes from downstream. In this case, they can ask downstream to do the merge and resolve the conflicts themselves (perhaps they will know better how to resolve them). It is one of the rare cases where downstream should merge from upstream.

### Patch workflow
If you are a contributor that sends changes upstream in the form of emails, you should use topic branches as usual (see above). Then use git-format-patch(1) to generate the corresponding emails (highly recommended over manually formatting them because it makes the maintainer’s life easier).

Example 13. format-patch/am: Publishing branches/topics

•git format-patch -M upstream..topic to turn them into preformatted patch files

•git send-email --to=<recipient> <patches>

See the git-format-patch(1) and git-send-email(1) manpages for further usage notes.

If the maintainer tells you that your patch no longer applies to the current upstream, you will have to rebase your topic (you cannot use a merge because you cannot format-patch merges):

Example 14. format-patch/am: Keeping topics up to date

git pull --rebase <URL> <branch>

You can then fix the conflicts during the rebase. Presumably you have not published your topic other than by mail, so rebasing it is not a problem.

If you receive such a patch series (as maintainer, or perhaps as a reader of the mailing list it was sent to), save the mails to files, create a new topic branch and use git am to import the commits:

Example 15. format-patch/am: Importing patches

git am < patch

One feature worth pointing out is the three-way merge, which can help if you get conflicts: git am -3 will use index information contained in patches to figure out the merge base. See git-am(1) for other options.

## SEE ALSO
gittutorial(7), git-push(1), git-pull(1), git-merge(1), git-rebase(1), git-format-patch(1), git-send-email(1), git-am(1)

## GIT
Part of the git(1) suite


gnupg

title: gnupg(7)

summary: The GNU Privacy Guard suite of programs

text:
# gnupg(7)

## NAME
GnuPG - The GNU Privacy Guard suite of programs

## DESCRIPTION
GnuPG is a set of programs for public key encryption and digital signatures. The program most users will want to use is the OpenPGP command line tool, named gpg2. gpgvis a stripped down version of gpg2 with no encryption functionality, used only to verify signatures against a trusted keyring. gpgsm is the X.509/CMS (for S/MIME) counterpart of gpg2. gpg-agent is a passphrase and private key daemon which may also emulate the ssh-agent.

## SEE ALSO
gpg(1), gpg2(1), gpgv(1), gpgsm(1), gpg-agent(1), dirmngr(8), scdaemon(1)

The full documentation for this tool is maintained as a Texinfo manual. If GnuPG and the info program are properly installed at your site, the command

```
info gnupg
```

should give you access to the complete manual including a menu structure and an index.