summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/config.txt6
-rw-r--r--Documentation/diff-format.txt57
-rw-r--r--Documentation/git-branch.txt18
-rw-r--r--Documentation/git-clone.txt24
-rw-r--r--Documentation/git-diff.txt6
-rw-r--r--Documentation/git-merge.txt18
-rw-r--r--Documentation/git-shortlog.txt1
-rw-r--r--Documentation/git-svn.txt40
-rw-r--r--Documentation/git-symbolic-ref.txt29
-rw-r--r--Documentation/git.txt32
-rw-r--r--Documentation/tutorial.txt41
11 files changed, 147 insertions, 125 deletions
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 9d3c71c3b8..9090762819 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -219,6 +219,12 @@ i18n.commitEncoding::
browser (and possibly at other places in the future or in other
porcelains). See e.g. gitlink:git-mailinfo[1]. Defaults to 'utf-8'.
+log.showroot::
+ If true, the initial commit will be shown as a big creation event.
+ This is equivalent to a diff against an empty tree.
+ Tools like gitlink:git-log[1] or gitlink:git-whatchanged[1], which
+ normally hide the root commit will now show it. True by default.
+
merge.summary::
Whether to include summaries of merged commits in newly created
merge commit messages. False by default.
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index e4520e28e5..883c1bb0a6 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -65,62 +65,17 @@ Generating patches with -p
When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
with a '-p' option, they do not produce the output described above;
-instead they produce a patch file.
+instead they produce a patch file. You can customize the creation
+of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS
+environment variables.
-The patch generation can be customized at two levels.
-
-1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set,
- these commands internally invoke "diff" like this:
-
- diff -L a/<path> -L b/<path> -pu <old> <new>
-+
-For added files, `/dev/null` is used for <old>. For removed
-files, `/dev/null` is used for <new>
-+
-The "diff" formatting options can be customized via the
-environment variable 'GIT_DIFF_OPTS'. For example, if you
-prefer context diff:
-
- GIT_DIFF_OPTS=-c git-diff-index -p HEAD
-
-
-2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
- program named by it is called, instead of the diff invocation
- described above.
-+
-For a path that is added, removed, or modified,
-'GIT_EXTERNAL_DIFF' is called with 7 parameters:
-
- path old-file old-hex old-mode new-file new-hex new-mode
-+
-where:
-
- <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
- contents of <old|new>,
- <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
- <old|new>-mode:: are the octal representation of the file modes.
-
-+
-The file parameters can point at the user's working file
-(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
-when a new file is added), or a temporary file (e.g. `old-file` in the
-index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
-temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
-
-For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
-parameter, <path>.
-
-
-git specific extension to diff format
--------------------------------------
-
-What -p option produces is slightly different from the
-traditional diff format.
+What the -p option produces is slightly different from the traditional
+diff format.
1. It is preceded with a "git diff" header, that looks like
this:
- diff --git a/file1 b/file2
+ diff --git a/file1 b/file2
+
The `a/` and `b/` filenames are the same unless rename/copy is
involved. Especially, even for a creation or a deletion,
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index d43ef1dec4..4f5b5d5028 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -8,14 +8,16 @@ git-branch - List, create, or delete branches.
SYNOPSIS
--------
[verse]
-'git-branch' [-r]
+'git-branch' [-r] [-a] [-v] [--abbrev=<length>]
'git-branch' [-l] [-f] <branchname> [<start-point>]
'git-branch' (-d | -D) <branchname>...
DESCRIPTION
-----------
-With no arguments given (or just `-r`) a list of available branches
+With no arguments given a list of existing branches
will be shown, the current branch will be highlighted with an asterisk.
+Option `-r` causes the remote-tracking branches to be listed,
+and option `-a` shows both.
In its second form, a new branch named <branchname> will be created.
It will start out with a head equal to the one given as <start-point>.
@@ -45,7 +47,17 @@ OPTIONS
a branch that already exists with the same name.
-r::
- List only the "remote" branches.
+ List the remote-tracking branches.
+
+-a::
+ List both remote-tracking branches and local branches.
+
+-v::
+ Show sha1 and subject message for each head.
+
+--abbrev=<length>::
+ Alter minimum display length for sha1 in output listing,
+ default value is 7.
<branchname>::
The name of the branch to create or delete.
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 86060472ad..d5efa00dea 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -11,7 +11,8 @@ SYNOPSIS
[verse]
'git-clone' [--template=<template_directory>] [-l [-s]] [-q] [-n] [--bare]
[-o <name>] [-u <upload-pack>] [--reference <repository>]
- [--use-separate-remote] <repository> [<directory>]
+ [--use-separate-remote | --no-separate-remote] <repository>
+ [<directory>]
DESCRIPTION
-----------
@@ -71,9 +72,13 @@ OPTIONS
Make a 'bare' GIT repository. That is, instead of
creating `<directory>` and placing the administrative
files in `<directory>/.git`, make the `<directory>`
- itself the `$GIT_DIR`. This implies `-n` option. When
- this option is used, neither the `origin` branch nor the
- default `remotes/origin` file is created.
+ itself the `$GIT_DIR`. This obviously implies the `-n`
+ because there is nowhere to check out the working tree.
+ Also the branch heads at the remote are copied directly
+ to corresponding local branch heads, without mapping
+ them to `refs/remotes/origin/`. When this option is
+ used, neither the `origin` branch nor the default
+ `remotes/origin` file is created.
--origin <name>::
-o <name>::
@@ -97,8 +102,15 @@ OPTIONS
--use-separate-remote::
Save remotes heads under `$GIT_DIR/remotes/origin/` instead
- of `$GIT_DIR/refs/heads/`. Only the master branch is saved
- in the latter.
+ of `$GIT_DIR/refs/heads/`. Only the local master branch is
+ saved in the latter. This is the default.
+
+--no-separate-remote::
+ Save remotes heads in the same namespace as the local
+ heads, `$GIT_DIR/refs/heads/'. In regular repositories,
+ this is a legacy setup git-clone created by default in
+ older Git versions, and will be removed before the next
+ major release.
<repository>::
The (possibly remote) repository to clone from. It can
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 228c4d95bd..3144864d85 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -22,8 +22,10 @@ the number of trees given to the command.
* When one <tree-ish> is given, the working tree and the named
tree are compared, using `git-diff-index`. The option
- `--cached` can be given to compare the index file and
+ `--index` can be given to compare the index file and
the named tree.
+ `--cached` is a deprecated alias for `--index`. It's use is
+ discouraged.
* When two <tree-ish>s are given, these two trees are compared
using `git-diff-tree`.
@@ -47,7 +49,7 @@ Various ways to check your working tree::
+
------------
$ git diff <1>
-$ git diff --cached <2>
+$ git diff --index <2>
$ git diff HEAD <3>
------------
+
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index bebf30ad3d..e2954aa76e 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -8,12 +8,14 @@ git-merge - Grand Unified Merge Driver
SYNOPSIS
--------
-'git-merge' [-n] [--no-commit] [-s <strategy>]... <msg> <head> <remote> <remote>...
-
+[verse]
+'git-merge' [-n] [--no-commit] [--squash] [-s <strategy>]...
+ [--reflog-action=<action>]
+ -m=<msg> <remote> <remote>...
DESCRIPTION
-----------
-This is the top-level user interface to the merge machinery
+This is the top-level interface to the merge machinery
which drives multiple merge strategy scripts.
@@ -27,13 +29,19 @@ include::merge-options.txt[]
to give a good default for automated `git-merge` invocations.
<head>::
- our branch head commit.
+ Our branch head commit. This has to be `HEAD`, so new
+ syntax does not require it
<remote>::
- other branch head merged into our branch. You need at
+ Other branch head merged into our branch. You need at
least one <remote>. Specifying more than one <remote>
obviously means you are trying an Octopus.
+--reflog-action=<action>::
+ This is used internally when `git-pull` calls this command
+ to record that the merge was created by `pull` command
+ in the `ref-log` entry that results from the merge.
+
include::merge-strategies.txt[]
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index d54fc3e5c6..95fa9010c1 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -8,6 +8,7 @@ git-shortlog - Summarize 'git log' output
SYNOPSIS
--------
git-log --pretty=short | 'git-shortlog' [-h] [-n] [-s]
+git-shortlog [-n|--number] [-s|--summary] [<committish>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index a764d1f8ee..a45067e164 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -49,7 +49,7 @@ latest revision.
Note: You should never attempt to modify the remotes/git-svn
branch outside of git-svn. Instead, create a branch from
-remotes/git-svn and work on that branch. Use the 'commit'
+remotes/git-svn and work on that branch. Use the 'dcommit'
command (see below) to write git commits back to
remotes/git-svn.
@@ -274,7 +274,7 @@ ADVANCED OPTIONS
-b<refname>::
--branch <refname>::
-Used with 'fetch' or 'commit'.
+Used with 'fetch', 'dcommit' or 'commit'.
This can be used to join arbitrary git branches to remotes/git-svn
on new commits where the tree object is equivalent.
@@ -368,7 +368,7 @@ SVN was very wrong.
Basic Examples
~~~~~~~~~~~~~~
-Tracking and contributing to an Subversion managed-project:
+Tracking and contributing to a Subversion-managed project:
------------------------------------------------------------------------
# Initialize a repo (like git init-db):
@@ -377,10 +377,9 @@ Tracking and contributing to an Subversion managed-project:
git-svn fetch
# Create your own branch to hack on:
git checkout -b my-branch remotes/git-svn
-# Commit only the git commits you want to SVN:
- git-svn commit <tree-ish> [<tree-ish_2> ...]
-# Commit all the git commits from my-branch that don't exist in SVN:
- git-svn commit remotes/git-svn..my-branch
+# Do some work, and then commit your new changes to SVN, as well as
+# automatically updating your working HEAD:
+ git-svn dcommit
# Something is committed to SVN, rebase the latest into your branch:
git-svn fetch && git rebase remotes/git-svn
# Append svn:ignore settings to the default git exclude file:
@@ -404,26 +403,24 @@ which can lead to merge commits reversing previous commits in SVN.
DESIGN PHILOSOPHY
-----------------
Merge tracking in Subversion is lacking and doing branched development
-with Subversion is cumbersome as a result. git-svn completely forgoes
-any automated merge/branch tracking on the Subversion side and leaves it
-entirely up to the user on the git side. It's simply not worth it to do
-a useful translation when the original signal is weak.
+with Subversion is cumbersome as a result. git-svn does not do
+automated merge/branch tracking by default and leaves it entirely up to
+the user on the git side.
[[tracking-multiple-repos]]
TRACKING MULTIPLE REPOSITORIES OR BRANCHES
------------------------------------------
-This is for advanced users, most users should ignore this section.
-
Because git-svn does not care about relationships between different
branches or directories in a Subversion repository, git-svn has a simple
hack to allow it to track an arbitrary number of related _or_ unrelated
-SVN repositories via one git repository. Simply set the GIT_SVN_ID
-environment variable to a name other other than "git-svn" (the default)
-and git-svn will ignore the contents of the $GIT_DIR/svn/git-svn directory
-and instead do all of its work in $GIT_DIR/svn/$GIT_SVN_ID for that
-invocation. The interface branch will be remotes/$GIT_SVN_ID, instead of
-remotes/git-svn. Any remotes/$GIT_SVN_ID branch should never be modified
-by the user outside of git-svn commands.
+SVN repositories via one git repository. Simply use the --id/-i flag or
+set the GIT_SVN_ID environment variable to a name other other than
+"git-svn" (the default) and git-svn will ignore the contents of the
+$GIT_DIR/svn/git-svn directory and instead do all of its work in
+$GIT_DIR/svn/$GIT_SVN_ID for that invocation. The interface branch will
+be remotes/$GIT_SVN_ID, instead of remotes/git-svn. Any
+remotes/$GIT_SVN_ID branch should never be modified by the user outside
+of git-svn commands.
[[fetch-args]]
ADDITIONAL FETCH ARGUMENTS
@@ -486,7 +483,8 @@ If you are not using the SVN::* Perl libraries and somebody commits a
conflicting changeset to SVN at a bad moment (right before you commit)
causing a conflict and your commit to fail, your svn working tree
($GIT_DIR/git-svn/tree) may be dirtied. The easiest thing to do is
-probably just to rm -rf $GIT_DIR/git-svn/tree and run 'rebuild'.
+probably just to rm -rf $GIT_DIR/git-svn/tree and run 'rebuild'. You
+can avoid this problem entirely by using 'dcommit'.
We ignore all SVN properties except svn:executable. Too difficult to
map them since we rely heavily on git write-tree being _exactly_ the
diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt
index 68ac6a65df..4bc35a1d4b 100644
--- a/Documentation/git-symbolic-ref.txt
+++ b/Documentation/git-symbolic-ref.txt
@@ -19,29 +19,22 @@ argument to see on which branch your working tree is on.
Give two arguments, create or update a symbolic ref <name> to
point at the given branch <ref>.
-Traditionally, `.git/HEAD` is a symlink pointing at
-`refs/heads/master`. When we want to switch to another branch,
-we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we want
+A symbolic ref is a regular file that stores a string that
+begins with `ref: refs/`. For example, your `.git/HEAD` is
+a regular file whose contents is `ref: refs/heads/master`.
+
+NOTES
+-----
+In the past, `.git/HEAD` was a symbolic link pointing at
+`refs/heads/master`. When we wanted to switch to another branch,
+we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we wanted
to find out which branch we are on, we did `readlink .git/HEAD`.
This was fine, and internally that is what still happens by
default, but on platforms that do not have working symlinks,
or that do not have the `readlink(1)` command, this was a bit
cumbersome. On some platforms, `ln -sf` does not even work as
-advertised (horrors).
-
-A symbolic ref can be a regular file that stores a string that
-begins with `ref: refs/`. For example, your `.git/HEAD` *can*
-be a regular file whose contents is `ref: refs/heads/master`.
-This can be used on a filesystem that does not support symbolic
-links. Instead of doing `readlink .git/HEAD`, `git-symbolic-ref
-HEAD` can be used to find out which branch we are on. To point
-the HEAD to `newbranch`, instead of `ln -sf refs/heads/newbranch
-.git/HEAD`, `git-symbolic-ref HEAD refs/heads/newbranch` can be
-used.
-
-Currently, .git/HEAD uses a regular file symbolic ref on Cygwin,
-and everywhere else it is implemented as a symlink. This can be
-changed at compilation time.
+advertised (horrors). Therefore symbolic links are now deprecated
+and symbolic refs are used by default.
Author
------
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 619d65685e..6382ef0a02 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -639,11 +639,35 @@ git Commits
git Diffs
~~~~~~~~~
'GIT_DIFF_OPTS'::
+ Only valid setting is "--unified=??" or "-u??" to set the
+ number of context lines shown when a unified diff is created.
+ This takes precedence over any "-U" or "--unified" option
+ value passed on the git diff command line.
+
'GIT_EXTERNAL_DIFF'::
- see the "generating patches" section in :
- gitlink:git-diff-index[1];
- gitlink:git-diff-files[1];
- gitlink:git-diff-tree[1]
+ When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
+ program named by it is called, instead of the diff invocation
+ described above. For a path that is added, removed, or modified,
+ 'GIT_EXTERNAL_DIFF' is called with 7 parameters:
+
+ path old-file old-hex old-mode new-file new-hex new-mode
++
+where:
+
+ <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
+ contents of <old|new>,
+ <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
+ <old|new>-mode:: are the octal representation of the file modes.
+
++
+The file parameters can point at the user's working file
+(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
+when a new file is added), or a temporary file (e.g. `old-file` in the
+index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
+temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
++
+For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
+parameter, <path>.
other
~~~~~
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 6555e58882..fe4491de41 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -228,29 +228,28 @@ at /home/bob/myrepo. She does this with:
------------------------------------------------
$ cd /home/alice/project
-$ git pull /home/bob/myrepo
+$ git pull /home/bob/myrepo master
------------------------------------------------
-This actually pulls changes from the branch in Bob's repository named
-"master". Alice could request a different branch by adding the name
-of the branch to the end of the git pull command line.
+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. (Note that the
+"master" argument in the above command is actually unnecessary, as it
+is the default.)
-This merges Bob's changes into her repository; "git log" will
-now show the new commits. If Alice has made her own changes in the
-meantime, then Bob's changes will be merged in, and she will 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.
-A more cautious Alice might wish to examine Bob's changes before
-pulling them. She can do this by creating a temporary branch just
-for the purpose of studying Bob's changes:
+You can perform the first operation alone using the "git fetch"
+command. For example, Alice could create a temporary branch just to
+track Bob's changes, without merging them with her own, using:
-------------------------------------
$ git fetch /home/bob/myrepo master:bob-incoming
-------------------------------------
which fetches the changes from Bob's master branch into a new branch
-named bob-incoming. (Unlike git pull, git fetch just fetches a copy
-of Bob's line of development without doing any merging). Then
+named bob-incoming. Then
-------------------------------------
$ git log -p master..bob-incoming
@@ -259,8 +258,8 @@ $ git log -p master..bob-incoming
shows a list of all the changes that Bob made since he branched from
Alice's master branch.
-After examining those changes, and possibly fixing things, Alice can
-pull the changes into her master branch:
+After examining those changes, and possibly fixing things, Alice
+could pull the changes into her master branch:
-------------------------------------
$ git checkout master
@@ -270,6 +269,18 @@ $ git pull . bob-incoming
The last command is a pull from the "bob-incoming" branch in Alice's
own repository.
+Alice could also perform both steps at once with:
+
+-------------------------------------
+$ git pull /home/bob/myrepo master:bob-incoming
+-------------------------------------
+
+This is just like the "git pull /home/bob/myrepo master" that we saw
+before, except that it also stores the unmerged changes from bob's
+master branch in bob-incoming before merging them into Alice's
+current branch. Note that git pull always merges into the current
+branch, regardless of what else is given on the commandline.
+
Later, Bob can update his repo with Alice's latest changes using
-------------------------------------