diff options
Diffstat (limited to 'Documentation')
32 files changed, 475 insertions, 212 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b1bfff630f..7e4d5716a6 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -237,6 +237,9 @@ For Python scripts: Writing Documentation: + Most (if not all) of the documentation pages are written in AsciiDoc + and processed into HTML output and manpages. + Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions. A few commented examples follow to provide reference diff --git a/Documentation/RelNotes/1.8.1.6.txt b/Documentation/RelNotes/1.8.1.6.txt new file mode 100644 index 0000000000..c15cf2e805 --- /dev/null +++ b/Documentation/RelNotes/1.8.1.6.txt @@ -0,0 +1,39 @@ +Git 1.8.1.6 Release Notes +========================= + +Fixes since v1.8.1.5 +-------------------- + + * An earlier change to the attribute system introduced at v1.8.1.2 by + mistake stopped a pattern "dir" (without trailing slash) from + matching a directory "dir" (it only wanted to allow pattern "dir/" + to also match). + + * The code to keep track of what directory names are known to Git on + platforms with case insensitive filesystems can get confused upon a + hash collision between these pathnames and looped forever. + + * When the "--prefix" option is used to "checkout-index", the code + did not pick the correct output filter based on the attribute + setting. + + * Annotated tags outside refs/tags/ hierarchy were not advertised + correctly to the ls-remote and fetch with recent version of Git. + + * The logic used by "git diff -M --stat" to shorten the names of + files before and after a rename did not work correctly when the + common prefix and suffix between the two filenames overlapped. + + * "git update-index -h" did not do the usual "-h(elp)" thing. + + * perl/Git.pm::cat_blob slurped everything in core only to write it + out to a file descriptor, which was not a very smart thing to do. + + * The SSL peer verification done by "git imap-send" did not ask for + Server Name Indication (RFC 4366), failing to connect SSL/TLS + sites that serve multiple hostnames on a single IP. + + * "git bundle verify" did not say "records a complete history" for a + bundle that does not have any prerequisites. + +Also contains various documentation fixes. diff --git a/Documentation/RelNotes/1.8.2.1.txt b/Documentation/RelNotes/1.8.2.1.txt new file mode 100644 index 0000000000..1354ad03f5 --- /dev/null +++ b/Documentation/RelNotes/1.8.2.1.txt @@ -0,0 +1,115 @@ +Git v1.8.2.1 Release Notes +========================== + +Fixes since v1.8.2 +------------------ + + * An earlier change to the attribute system introduced at v1.8.1.2 by + mistake stopped a pattern "dir" (without trailing slash) from + matching a directory "dir" (it only wanted to allow pattern "dir/" + to also match). + + * Verification of signed tags were not done correctly when not in C + or en/US locale. + + * 'git commit -m "$msg"' used to add an extra newline even when + $msg already ended with one. + + * The "--match=<pattern>" option of "git describe", when used with + "--all" to allow refs that are not annotated tags to be used as a + base of description, did not restrict the output from the command + to those that match the given pattern. + + * An aliased command spawned from a bare repository that does not say + it is bare with "core.bare = yes" is treated as non-bare by mistake. + + * When "format-patch" quoted a non-ascii strings on the header files, + it incorrectly applied rfc2047 and chopped a single character in + the middle of it. + + * "git archive" reports a failure when asked to create an archive out + of an empty tree. It would be more intuitive to give an empty + archive back in such a case. + + * "git tag -f <tag>" always said "Updated tag '<tag>'" even when + creating a new tag (i.e. not overwriting nor updating). + + * "git cmd -- ':(top'" was not diagnosed as an invalid syntax, and + instead the parser kept reading beyond the end of the string. + + * Annotated tags outside refs/tags/ hierarchy were not advertised + correctly to the ls-remote and fetch with recent version of Git. + + * The code to keep track of what directory names are known to Git on + platforms with case insensitive filesystems can get confused upon a + hash collision between these pathnames and looped forever. + + * The logic used by "git diff -M --stat" to shorten the names of + files before and after a rename did not work correctly when the + common prefix and suffix between the two filenames overlapped. + + * "git submodule update", when recursed into sub-submodules, did not + acccumulate the prefix paths. + + * "git am $maildir/" applied messages in an unexpected order; sort + filenames read from the maildir/ in a way that is more likely to + sort messages in the order the writing MUA meant to, by sorting + numeric segment in numeric order and non-numeric segment in + alphabetical order. + + * When export-subst is used, "zip" output recorded incorrect + size of the file. + + * Some platforms and users spell UTF-8 differently; retry with the + most official "UTF-8" when the system does not understand the + user-supplied encoding name that are the common alternative + spellings of UTF-8. + + * "git branch" did not bother to check nonsense command line + parameters and issue errors in many cases. + + * "git update-index -h" did not do the usual "-h(elp)" thing. + + * perl/Git.pm::cat_blob slurped everything in core only to write it + out to a file descriptor, which was not a very smart thing to do. + + * The SSL peer verification done by "git imap-send" did not ask for + Server Name Indication (RFC 4366), failing to connect SSL/TLS + sites that serve multiple hostnames on a single IP. + + * "git index-pack" had a buffer-overflow while preparing an + informational message when the translated version of it was too + long. + + * Clarify in the documentation "what" gets pushed to "where" when the + command line to "git push" does not say these explicitly. + + * In "git reflog expire", REACHABLE bit was not cleared from the + correct objects. + + * The "--color=<when>" argument to the commands in the diff family + was described poorly. + + * The arguments given to pre-rebase hook were not documented. + + * The v4 index format was not documented. + + * The "--match=<pattern>" argument "git describe" takes uses glob + pattern but it wasn't obvious from the documentation. + + * Some sources failed to compile on systems that lack NI_MAXHOST in + their system header (e.g. z/OS). + + * Add an example use of "--env-filter" in "filter-branch" + documentation. + + * "git bundle verify" did not say "records a complete history" for a + bundle that does not have any prerequisites. + + * In the v1.8.0 era, we changed symbols that do not have to be global + to file scope static, but a few functions in graph.c were used by + CGit from sideways bypassing the entry points of the API the + in-tree users use. + + * "git merge-tree" had a typo in the logic to detect d/f conflicts, + which caused it to segfault in some cases. diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl index 828ec62554..87437f8a95 100755 --- a/Documentation/cat-texi.perl +++ b/Documentation/cat-texi.perl @@ -12,6 +12,7 @@ while (<STDIN>) { push @menu, $1; } s/\(\@pxref{\[(URLS|REMOTES)\]}\)//; + s/\@anchor\{[^{}]*\}//g; print TMP; } close TMP; diff --git a/Documentation/config.txt b/Documentation/config.txt index bbba728d09..bc750d5794 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -178,6 +178,10 @@ advice.*:: the template shown when writing commit messages in linkgit:git-commit[1], and in the help message shown by linkgit:git-checkout[1] when switching branch. + statusUoption:: + Advise to consider using the `-u` option to linkgit:git-status[1] + when the command takes more than 2 seconds to enumerate untracked + files. commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to merge to avoid overwriting local changes. @@ -443,7 +447,7 @@ core.sharedRepository:: core.warnAmbiguousRefs:: If true, Git will warn you if the ref name you passed it is ambiguous - and might match multiple refs in the .git/refs/ tree. True by default. + and might match multiple refs in the repository. True by default. core.compression:: An integer -1..9, indicating a default compression level. @@ -551,7 +555,7 @@ core.commentchar:: (default '#'). sequence.editor:: - Text editor used by `git rebase -i` for editing the rebase insn file. + Text editor used by `git rebase -i` for editing the rebase instruction file. The value is meant to be interpreted by the shell when it is used. It can be overridden by the `GIT_SEQUENCE_EDITOR` environment variable. When not configured the default commit message editor is used instead. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 869d965a3b..104579dc75 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -195,8 +195,8 @@ any of those replacements occurred. --color[=<when>]:: Show colored diff. - The value must be `always` (the default for `<when>`), `never`, or `auto`. - The default value is `never`. + `--color` (i.e. without '=<when>') is the same as `--color=always`. + '<when>' can be one of `always`, `never`, or `auto`. ifdef::git-diff[] It can be changed by the `color.ui` and `color.diff` configuration settings. diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index b4c2e24849..250e5228a3 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -56,7 +56,8 @@ OPTIONS Write the archive to <file> instead of stdout. --worktree-attributes:: - Look for attributes in .gitattributes in working directory too. + Look for attributes in .gitattributes files in the working tree + as well (see <<ATTRIBUTES>>). <extra>:: This can be any options that the archiver backend understands. @@ -120,6 +121,7 @@ tar.<format>.remote:: user-defined formats, but true for the "tar.gz" and "tgz" formats. +[[ATTRIBUTES]] ATTRIBUTES ---------- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 0eb79ccdba..9b1be5581d 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -137,6 +137,8 @@ OPTIONS -m <msg>:: --message=<msg>:: Use the given <msg> as the commit message. + If multiple `-m` options are given, their values are + concatenated as separate paragraphs. -t <file>:: --template=<file>:: @@ -172,16 +174,25 @@ OPTIONS linkgit:git-commit-tree[1]. --cleanup=<mode>:: - This option sets how the commit message is cleaned up. - The '<mode>' can be one of 'verbatim', 'whitespace', 'strip', - and 'default'. The 'default' mode will strip leading and - trailing empty lines and #commentary from the commit message - only if the message is to be edited. Otherwise only whitespace - removed. The 'verbatim' mode does not change message at all, - 'whitespace' removes just leading/trailing whitespace lines - and 'strip' removes both whitespace and commentary. The default - can be changed by the 'commit.cleanup' configuration variable - (see linkgit:git-config[1]). + This option determines how the supplied commit message should be + cleaned up before committing. The '<mode>' can be `strip`, + `whitespace`, `verbatim`, or `default`. ++ +-- +strip:: + Strip leading and trailing empty lines, trailing whitespace, and + #commentary and collapse consecutive empty lines. +whitespace:: + Same as `strip` except #commentary is not removed. +verbatim:: + Do not change the message at all. +default:: + Same as `strip` if the message is to be edited. + Otherwise `whitespace`. +-- ++ +The default can be changed by the 'commit.cleanup' configuration +variable (see linkgit:git-config[1]). -e:: --edit:: @@ -196,14 +207,15 @@ OPTIONS without changing its commit message. --amend:: - Used to amend the tip of the current branch. Prepare the tree - object you would want to replace the latest commit as usual - (this includes the usual -i/-o and explicit paths), and the - commit log editor is seeded with the commit message from the - tip of the current branch. The commit you create replaces the - current tip -- if it was a merge, it will have the parents of - the current tip as parents -- so the current top commit is - discarded. + Replace the tip of the current branch by creating a new + commit. The recorded tree is prepared as usual (including + the effect of the `-i` and `-o` options and explicit + pathspec), and the message from the original commit is used + as the starting point, instead of an empty message, when no + other message is specified from the command line via options + such as `-m`, `-F`, `-c`, etc. The new commit has the same + parents and author as the current one (the `--reset-author` + option can countermand this). + -- It is a rough equivalent for: diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 472f00f607..7da0f13a5c 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -56,7 +56,7 @@ For example, if we want a password for `https://example.com/foo.git`, we might generate the following credential description (don't forget the blank line at the end; it tells `git credential` that the application finished feeding all the -infomation it has): +information it has): protocol=https host=example.com diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 32da244fd5..3c81e85ec5 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -81,8 +81,9 @@ OPTIONS that points at object deadbee....). --match <pattern>:: - Only consider tags matching the given pattern (can be used to avoid - leaking private tags made from the repository). + Only consider tags matching the given `glob(7)` pattern, + excluding the "refs/tags/" prefix. This can be used to avoid + leaking private tags from the repository. --always:: Show uniquely abbreviated commit object as fallback. diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index dfd12c94e4..e4c8e82660 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -64,8 +64,11 @@ argument is always evaluated in the shell context using the 'eval' command Prior to that, the $GIT_COMMIT environment variable will be set to contain the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, -and GIT_COMMITTER_DATE are set according to the current commit. The values -of these variables after the filters have run, are used for the new commit. +and GIT_COMMITTER_DATE are taken from the current commit and exported to +the environment, in order to affect the author and committer identities of +the replacement commit created by linkgit:git-commit-tree[1] after the +filters have run. + If any evaluation of <command> returns a non-zero exit status, the whole operation will be aborted. @@ -329,6 +332,26 @@ git filter-branch --msg-filter ' ' HEAD~10..HEAD -------------------------------------------------------- +The `--env-filter` option can be used to modify committer and/or author +identity. For example, if you found out that your commits have the wrong +identity due to a misconfigured user.email, you can make a correction, +before publishing the project, like this: + +-------------------------------------------------------- +git filter-branch --env-filter ' + if test "$GIT_AUTHOR_EMAIL" = "root@localhost" + then + GIT_AUTHOR_EMAIL=john@example.com + export GIT_AUTHOR_EMAIL + fi + if test "$GIT_COMMITTER_EMAIL" = "root@localhost" + then + GIT_COMMITTER_EMAIL=john@example.com + export GIT_COMMITTER_EMAIL + fi +' -- --all +-------------------------------------------------------- + To restrict rewriting to only part of the history, specify a revision range in addition to the new branch name. The new branch name will point to the top-most revision that a 'git rev-list' of this range diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index c852a2677a..42391f2ae7 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -170,6 +170,30 @@ happens: If you tried a merge which resulted in complex conflicts and want to start over, you can recover with `git merge --abort`. +MERGING TAG +----------- + +When merging an annotated (and possibly signed) tag, Git always +creates a merge commit even if a fast-forward merge is possible, and +the commit message template is prepared with the tag message. +Additionally, if the tag is signed, the signature check is reported +as a comment in the message template. See also linkgit:git-tag[1]. + +When you want to just integrate with the work leading to the commit +that happens to be tagged, e.g. synchronizing with an upstream +release point, you may not want to make an unnecessary merge commit. + +In such a case, you can "unwrap" the tag yourself before feeding it +to `git merge`, or pass `--ff-only` when you do not have any work on +your own. e.g. + +--- +git fetch origin +git merge v1.2.3^0 +git merge --ff-only v1.2.3 +--- + + HOW CONFLICTS ARE PRESENTED --------------------------- diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index c975743230..24ab07a3f8 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -218,7 +218,7 @@ $ git merge origin/next ------------------------------------------------ -If you tried a pull which resulted in a complex conflicts and +If you tried a pull which resulted in complex conflicts and would want to start over, you can recover with 'git reset'. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 13980257ee..577d201c00 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -23,6 +23,17 @@ You can make interesting things happen to a repository every time you push into it, by setting up 'hooks' there. See documentation for linkgit:git-receive-pack[1]. +When the command line does not specify where to push with the +`<repository>` argument, `branch.*.remote` configuration for the +current branch is consulted to determine where to push. If the +configuration is missing, it defaults to 'origin'. + +When the command line does not specify what to push with `<refspec>...` +arguments or `--all`, `--mirror`, `--tags` options, the command finds +the default `<refspec>` by consulting `remote.*.push` configuration, +and if it is not found, honors `push.default` configuration to decide +what to push (See gitlink:git-config[1] for the meaning of `push.default`). + OPTIONS[[OPTIONS]] ------------------ @@ -33,13 +44,10 @@ OPTIONS[[OPTIONS]] of a remote (see the section <<REMOTES,REMOTES>> below). <refspec>...:: + Specify what destination ref to update with what source object. The format of a <refspec> parameter is an optional plus - `+`, followed by the source ref <src>, followed + `+`, followed by the source object <src>, followed by a colon `:`, followed by the destination ref <dst>. - It is used to specify with what <src> object the <dst> ref - in the remote repository is to be updated. If not specified, - the behavior of the command is controlled by the `push.default` - configuration variable. + The <src> is often the name of the branch you would want to push, but it can be any arbitrary "SHA-1 expression", such as `master~4` or @@ -66,10 +74,7 @@ the remote repository. The special refspec `:` (or `+:` to allow non-fast-forward updates) directs Git to push "matching" branches: for every branch that exists on the local side, the remote side is updated if a branch of the same name -already exists on the remote side. This is the default operation mode -if no explicit refspec is found (that is neither on the command line -nor in any Push line of the corresponding remotes file---see below) and -no `push.default` configuration variable is set. +already exists on the remote side. --all:: Instead of naming each ref to push, specifies that all diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 58b7facb09..8cfc748ae2 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -86,7 +86,7 @@ begins with `ext::`. Examples: edit .ssh/config. "ext::socat -t3600 - ABSTRACT-CONNECT:/git-server %G/somerepo":: - Represents repository with path /somerepo accessable over + Represents repository with path /somerepo accessible over git protocol at abstract namespace address /git-server. "ext::git-server-alias foo %G/repo":: diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 0412c4017d..9046df98a0 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -46,15 +46,21 @@ OPTIONS Show untracked files. + The mode parameter is optional (defaults to 'all'), and is used to -specify the handling of untracked files; when -u is not used, the -default is 'normal', i.e. show untracked files and directories. +specify the handling of untracked files. + The possible options are: + - - 'no' - Show no untracked files - - 'normal' - Shows untracked files and directories + - 'no' - Show no untracked files. + - 'normal' - Shows untracked files and directories. - 'all' - Also shows individual files in untracked directories. + +When `-u` option is not used, untracked files and directories are +shown (i.e. the same as specifying `normal`), to help you avoid +forgetting to add newly created files. Because it takes extra work +to find untracked files in the filesystem, this mode may take some +time in a large working tree. You can use `no` to have `git status` +return more quickly without showing untracked files. ++ The default can be changed using the status.showUntrackedFiles configuration variable documented in linkgit:git-config[1]. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 1b8b6498cd..7706d41c87 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -245,7 +245,7 @@ first have already been pushed into SVN. patch), "all" (accept all patches), or "quit". + 'git svn dcommit' returns immediately if answer if "no" or "quit", without - commiting anything to SVN. + committing anything to SVN. 'branch':: Create a branch in the SVN repository. @@ -856,7 +856,7 @@ HANDLING OF SVN BRANCHES ------------------------ If 'git svn' is configured to fetch branches (and --follow-branches is in effect), it sometimes creates multiple Git branches for one -SVN branch, where the addtional branches have names of the form +SVN branch, where the additional branches have names of the form 'branchname@nnn' (with nnn an SVN revision number). These additional branches are created if 'git svn' cannot find a parent commit for the first commit in an SVN branch, to connect the branch to the history of diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index e3032c46c6..b21aa87fe8 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -126,6 +126,12 @@ This option is only applicable when listing tags without annotation lines. linkgit:git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a tag name. +<commit>:: +<object>:: + The object that the new tag will refer to, usually a commit. + Defaults to HEAD. + + CONFIGURATION ------------- By default, 'git tag' in sign-with-default mode (-s) will use your diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt index ad8b823f77..78a0d955ec 100644 --- a/Documentation/git-tools.txt +++ b/Documentation/git-tools.txt @@ -109,7 +109,7 @@ Others - *git.el* (contrib/) - This is an Emacs interface for Git. The user interface is modeled on + This is an Emacs interface for Git. The user interface is modelled on pcl-cvs. It has been developed on Emacs 21 and will probably need some tweaking to work on XEmacs. diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 77a912d4ea..c92775829b 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -145,7 +145,15 @@ you will need to handle the situation manually. --index-version <n>:: Write the resulting index out in the named on-disk format version. - The current default version is 2. + Supported versions are 2, 3 and 4. The current default version is 2 + or 3, depending on whether extra features are used, such as + `git add -N`. ++ +Version 4 performs a simple pathname compression that reduces index +size by 30%-50% on large repositories, which results in faster load +time. Version 4 is relatively young (first released in in 1.8.0 in +October 2012). Other Git implementations such as JGit and libgit2 +may not support it yet. -z:: Only meaningful with `--stdin` or `--index-info`; paths are diff --git a/Documentation/git.txt b/Documentation/git.txt index 7efaa591b8..6a875f2ade 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,14 +43,16 @@ unreleased) version of Git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.8.2/git.html[documentation for release 1.8.2] +* link:v1.8.2.1/git.html[documentation for release 1.8.2.1] * release notes for + link:RelNotes/1.8.2.1.txt[1.8.2.1]. link:RelNotes/1.8.2.txt[1.8.2]. -* link:v1.8.1.5/git.html[documentation for release 1.8.1.5] +* link:v1.8.1.6/git.html[documentation for release 1.8.1.6] * release notes for + link:RelNotes/1.8.1.6.txt[1.8.1.6], link:RelNotes/1.8.1.5.txt[1.8.1.5], link:RelNotes/1.8.1.4.txt[1.8.1.4], link:RelNotes/1.8.1.3.txt[1.8.1.3], @@ -774,9 +776,12 @@ other If this environment variable is set then 'git fetch' and 'git push' will use this command instead of 'ssh' when they need to connect to a remote system. - The '$GIT_SSH' command will be given exactly two arguments: - the 'username@host' (or just 'host') from the URL and the - shell command to execute on that remote system. + The '$GIT_SSH' command will be given exactly two or + four arguments: the 'username@host' (or just 'host') + from the URL and the shell command to execute on that + remote system, optionally preceded by '-p' (literally) and + the 'port' from the URL when it specifies something other + than the default SSH port. + To pass options to the program that you want to list in GIT_SSH you will need to wrap the program and options into a shell script, diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index dc9e617a10..9ac5088acd 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -107,13 +107,14 @@ couple of magic command line options: --------------------------------------------- $ git describe -h usage: git describe [options] <committish>* + or: git describe [options] --dirty --contains find the tag that comes after the commit --debug debug search strategy on stderr - --all use any ref in .git/refs - --tags use any tag in .git/refs/tags - --abbrev [<n>] use <n> digits to display SHA-1s - --candidates <n> consider <n> most recent tags (default: 10) + --all use any ref + --tags use any tag, even unannotated + --long always use long format + --abbrev[=<n>] use <n> digits to display SHA-1s --------------------------------------------- --help-all:: diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index eab9b356cd..dc6693fe48 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -140,9 +140,11 @@ the outcome of 'git commit'. pre-rebase ~~~~~~~~~~ -This hook is called by 'git rebase' and can be used to prevent a branch -from getting rebased. - +This hook is called by 'git rebase' and can be used to prevent a +branch from getting rebased. The hook may be called with one or +two parameters. The first parameter is the upstream from which +the series was forked. The second parameter is the branch being +rebased, and is not set when rebasing the current branch. post-checkout ~~~~~~~~~~~~~ diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 0bcbe0ac3c..34a8445828 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -30,7 +30,8 @@ set to `no` at the beginning of them. --no-ff:: Create a merge commit even when the merge resolves as a - fast-forward. + fast-forward. This is the default behaviour when merging an + annotated (and possibly signed) tag. --ff-only:: Refuse to merge and exit with a non-zero status unless the diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 105f18a6f9..293965524e 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -133,6 +133,7 @@ The placeholders are: - '%GG': raw verification message from GPG for a signed commit - '%G?': show either "G" for Good or "B" for Bad for a signed commit - '%GS': show the name of the signer for a signed commit +- '%GK': show the key used to sign a signed commit - '%gD': reflog selector, e.g., `refs/stash@{1}` - '%gd': shortened reflog selector, e.g., `stash@{1}` - '%gn': reflog identity name diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 314e25da73..b0f72206a0 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -55,7 +55,7 @@ when you run `git cherry-pick`. + 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 prefered as +While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. '<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index a959517b23..a6b7d83a8e 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -55,7 +55,7 @@ Functions initial, empty state. `argv_array_detach`:: - Detach the argv array from the `struct argv_array`, transfering + Detach the argv array from the `struct argv_array`, transferring ownership of the allocated array and strings. `argv_array_free_detached`:: diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 516fda7412..c1b42a40d3 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -160,7 +160,7 @@ int foo_login(struct foo_connection *f) break; default: /* - * Some other error occured. We don't know if the + * Some other error occurred. We don't know if the * credential is good or bad, so report nothing to the * credential subsystem. */ diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt index dbbea95db7..aa1c50f181 100644 --- a/Documentation/technical/api-ref-iteration.txt +++ b/Documentation/technical/api-ref-iteration.txt @@ -35,7 +35,7 @@ Iteration functions * `head_ref_submodule()`, `for_each_ref_submodule()`, `for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`, `for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()` - do the same as the functions descibed above but for a specified + do the same as the functions described above but for a specified submodule. * `for_each_rawref()` can be used to learn about broken ref and symref. diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 27c716b15f..0810251f5a 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -12,7 +12,7 @@ Git index format The signature is { 'D', 'I', 'R', 'C' } (stands for "dircache") 4-byte version number: - The current supported versions are 2 and 3. + The current supported versions are 2, 3 and 4. 32-bit number of index entries. @@ -93,8 +93,8 @@ Git index format 12-bit name length if the length is less than 0xFFF; otherwise 0xFFF is stored in this field. - (Version 3) A 16-bit field, only applicable if the "extended flag" - above is 1, split into (high to low bits). + (Version 3 or later) A 16-bit field, only applicable if the + "extended flag" above is 1, split into (high to low bits). 1-bit reserved for future diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index 0e37ec9de5..a37f1378d0 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -26,7 +26,9 @@ Git pack format (deltified representation) n-byte type and length (3-bit type, (n-1)*7+4-bit length) - 20-byte base object name + 20-byte base object name if OBJ_REF_DELTA or a negative relative + offset from the delta object's position in the pack if this + is an OBJ_OFS_DELTA object compressed delta data Observation: length of each object is encoded in a variable diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 5f36f8115f..e831cc2020 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -19,7 +19,7 @@ Further chapters cover more specialized topics. Comprehensive reference documentation is available through the man pages, or linkgit:git-help[1] command. For example, for the command -"git clone <repo>", you can either use: +`git clone <repo>`, you can either use: ------------------------------------------------ $ man git-clone @@ -66,11 +66,11 @@ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git The initial clone may be time-consuming for a large project, but you will only need to clone once. -The clone command creates a new directory named after the project ("git" -or "linux-2.6" in the examples above). After you cd into this +The clone command creates a new directory named after the project (`git` +or `linux-2.6` in the examples above). After you cd into this directory, you will see that it contains a copy of the project files, called the <<def_working_tree,working tree>>, together with a special -top-level directory named ".git", which contains all the information +top-level directory named `.git`, which contains all the information about the history of the project. [[how-to-check-out]] @@ -188,7 +188,7 @@ As you can see, a commit shows who made the latest change, what they did, and why. Every commit has a 40-hexdigit id, sometimes called the "object name" or the -"SHA-1 id", shown on the first line of the "git show" output. You can usually +"SHA-1 id", shown on the first line of the `git show` output. You can usually refer to a commit by a shorter name, such as a tag or a branch name, but this longer name can also be useful. Most importantly, it is a globally unique name for this commit: so if you tell somebody else the object name (for @@ -268,35 +268,35 @@ Manipulating branches Creating, deleting, and modifying branches is quick and easy; here's a summary of the commands: -git branch:: +`git branch`:: list all branches -git branch <branch>:: - create a new branch named <branch>, referencing the same +`git branch <branch>`:: + create a new branch named `<branch>`, referencing the same point in history as the current branch -git branch <branch> <start-point>:: - create a new branch named <branch>, referencing - <start-point>, which may be specified any way you like, +`git branch <branch> <start-point>`:: + create a new branch named `<branch>`, referencing + `<start-point>`, which may be specified any way you like, including using a branch name or a tag name -git branch -d <branch>:: - delete the branch <branch>; if the branch you are deleting +`git branch -d <branch>`:: + delete the branch `<branch>`; if the branch you are deleting points to a commit which is not reachable from the current branch, this command will fail with a warning. -git branch -D <branch>:: +`git branch -D <branch>`:: even if the branch points to a commit not reachable from the current branch, you may know that that commit is still reachable from some other branch or tag. In that case it is safe to use this command to force Git to delete the branch. -git checkout <branch>:: - make the current branch <branch>, updating the working - directory to reflect the version referenced by <branch> -git checkout -b <new> <start-point>:: - create a new branch <new> referencing <start-point>, and +`git checkout <branch>`:: + make the current branch `<branch>`, updating the working + directory to reflect the version referenced by `<branch>` +`git checkout -b <new> <start-point>`:: + create a new branch `<new>` referencing `<start-point>`, and check it out. The special symbol "HEAD" can always be used to refer to the current -branch. In fact, Git uses a file named "HEAD" in the .git directory to -remember which branch is current: +branch. In fact, Git uses a file named `HEAD` in the `.git` directory +to remember which branch is current: ------------------------------------------------ $ cat .git/HEAD @@ -346,7 +346,7 @@ of the HEAD in the repository that you cloned from. That repository may also have had other branches, though, and your local repository keeps branches which track each of those remote branches, called remote-tracking branches, which you -can view using the "-r" option to linkgit:git-branch[1]: +can view using the `-r` option to linkgit:git-branch[1]: ------------------------------------------------ $ git branch -r @@ -364,7 +364,7 @@ In this example, "origin" is called a remote repository, or "remote" for short. The branches of this repository are called "remote branches" from our point of view. The remote-tracking branches listed above were created based on the remote branches at clone time and will -be updated by "git fetch" (hence "git pull") and "git push". See +be updated by `git fetch` (hence `git pull`) and `git push`. See <<Updating-a-repository-With-git-fetch>> for details. You might want to build on one of these remote-tracking branches @@ -374,7 +374,7 @@ on a branch of your own, just as you would for a tag: $ git checkout -b my-todo-copy origin/todo ------------------------------------------------ -You can also check out "origin/todo" directly to examine it or +You can also check out `origin/todo` directly to examine it or write a one-off patch. See <<detached-head,detached head>>. Note that the name "origin" is just the name that Git uses by default @@ -386,17 +386,17 @@ Naming branches, tags, and other references Branches, remote-tracking branches, and tags are all references to commits. All references are named with a slash-separated path name -starting with "refs"; the names we've been using so far are actually +starting with `refs`; the names we've been using so far are actually shorthand: - - The branch "test" is short for "refs/heads/test". - - The tag "v2.6.18" is short for "refs/tags/v2.6.18". - - "origin/master" is short for "refs/remotes/origin/master". + - The branch `test` is short for `refs/heads/test`. + - The tag `v2.6.18` is short for `refs/tags/v2.6.18`. + - `origin/master` is short for `refs/remotes/origin/master`. The full name is occasionally useful if, for example, there ever exists a tag and a branch with the same name. -(Newly created refs are actually stored in the .git/refs directory, +(Newly created refs are actually stored in the `.git/refs` directory, under the path given by their name. However, for efficiency reasons they may also be packed together in a single file; see linkgit:git-pack-refs[1]). @@ -418,7 +418,7 @@ Eventually the developer cloned from will do additional work in her repository, creating new commits and advancing the branches to point at the new commits. -The command "git fetch", with no arguments, will update all of the +The command `git fetch`, with no arguments, will update all of the remote-tracking branches to the latest version found in her repository. It will not touch any of your own branches--not even the "master" branch that was created for you on clone. @@ -438,7 +438,7 @@ $ git fetch linux-nfs ------------------------------------------------- New remote-tracking branches will be stored under the shorthand name -that you gave "git remote add", in this case linux-nfs: +that you gave `git remote add`, in this case `linux-nfs`: ------------------------------------------------- $ git branch -r @@ -446,10 +446,10 @@ linux-nfs/master origin/master ------------------------------------------------- -If you run "git fetch <remote>" later, the remote-tracking branches for the -named <remote> will be updated. +If you run `git fetch <remote>` later, the remote-tracking branches +for the named `<remote>` will be updated. -If you examine the file .git/config, you will see that Git has added +If you examine the file `.git/config`, you will see that Git has added a new stanza: ------------------------------------------------- @@ -462,7 +462,7 @@ $ cat .git/config ------------------------------------------------- This is what causes Git to track the remote's branches; you may modify -or delete these configuration options by editing .git/config with a +or delete these configuration options by editing `.git/config` with a text editor. (See the "CONFIGURATION FILE" section of linkgit:git-config[1] for details.) @@ -499,7 +499,7 @@ Bisecting: 3537 revisions left to test after this [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6] ------------------------------------------------- -If you run "git branch" at this point, you'll see that Git has +If you run `git branch` at this point, you'll see that Git has temporarily moved you in "(no branch)". HEAD is now detached from any branch and points directly to a commit (with commit id 65934...) that is reachable from "master" but not from v2.6.18. Compile and test it, @@ -545,11 +545,11 @@ id, and check it out with: $ git reset --hard fb47ddb2db... ------------------------------------------------- -then test, run "bisect good" or "bisect bad" as appropriate, and +then test, run `bisect good` or `bisect bad` as appropriate, and continue. -Instead of "git bisect visualize" and then "git reset --hard -fb47ddb2db...", you might just want to tell Git that you want to skip +Instead of `git bisect visualize` and then `git reset --hard +fb47ddb2db...`, you might just want to tell Git that you want to skip the current commit: ------------------------------------------------- @@ -561,8 +561,8 @@ bad one between some first skipped commits and a later bad commit. There are also ways to automate the bisecting process if you have a test script that can tell a good from a bad commit. See -linkgit:git-bisect[1] for more information about this and other "git -bisect" features. +linkgit:git-bisect[1] for more information about this and other `git +bisect` features. [[naming-commits]] Naming commits @@ -591,7 +591,7 @@ $ git show HEAD~4 # the great-great-grandparent ------------------------------------------------- Recall that merge commits may have more than one parent; by default, -^ and ~ follow the first parent listed in the commit, but you can +`^` and `~` follow the first parent listed in the commit, but you can also choose: ------------------------------------------------- @@ -640,7 +640,7 @@ running $ git tag stable-1 1b2e1d63ff ------------------------------------------------- -You can use stable-1 to refer to the commit 1b2e1d63ff. +You can use `stable-1` to refer to the commit 1b2e1d63ff. This creates a "lightweight" tag. If you would also like to include a comment with the tag, and possibly sign it cryptographically, then you @@ -669,7 +669,7 @@ $ git log -S'foo()' # commits which add or remove any file data ------------------------------------------------- And of course you can combine all of these; the following finds -commits since v2.5 which touch the Makefile or any file under fs: +commits since v2.5 which touch the `Makefile` or any file under `fs`: ------------------------------------------------- $ git log v2.5.. Makefile fs/ @@ -681,7 +681,7 @@ You can also ask git log to show patches: $ git log -p ------------------------------------------------- -See the "--pretty" option in the linkgit:git-log[1] man page for more +See the `--pretty` option in the linkgit:git-log[1] man page for more display options. Note that git log starts with the most recent commit and works @@ -742,8 +742,8 @@ Examples Counting the number of commits on a branch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Suppose you want to know how many commits you've made on "mybranch" -since it diverged from "origin": +Suppose you want to know how many commits you've made on `mybranch` +since it diverged from `origin`: ------------------------------------------------- $ git log --pretty=oneline origin..mybranch | wc -l @@ -780,7 +780,7 @@ $ git rev-list master e05db0fd4f31dde7005f075a84f96b360d05984b ------------------------------------------------- -Or you could recall that the ... operator selects all commits +Or you could recall that the `...` operator selects all commits contained reachable from either one reference or the other but not both; so @@ -880,7 +880,7 @@ Showing commits unique to a given branch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Suppose you would like to see all the commits reachable from the branch -head named "master" but not from any other head in your repository. +head named `master` but not from any other head in your repository. We can list all the heads in this repository with linkgit:git-show-ref[1]: @@ -894,7 +894,7 @@ a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master 1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes ------------------------------------------------- -We can get just the branch-head names, and remove "master", with +We can get just the branch-head names, and remove `master`, with the help of the standard utilities cut and grep: ------------------------------------------------- @@ -939,7 +939,7 @@ is preceded by `project/`. The output file format is inferred from the output file extension if possible, see linkgit:git-archive[1] for details. -Versions of Git older than 1.7.7 don't know about the 'tar.gz' format, +Versions of Git older than 1.7.7 don't know about the `tar.gz` format, you'll need to use gzip explicitly: ------------------------------------------------- @@ -1062,7 +1062,7 @@ at step 3, Git maintains a snapshot of the tree's contents in a special staging area called "the index." At the beginning, the content of the index will be identical to -that of the HEAD. The command "git diff --cached", which shows +that of the HEAD. The command `git diff --cached`, which shows the difference between the HEAD and the index, should therefore produce no output at that point. @@ -1101,7 +1101,7 @@ $ git diff shows the difference between the working tree and the index file. -Note that "git add" always adds just the current contents of a file +Note that `git add` always adds just the current contents of a file to the index; further changes to the same file will be ignored unless you run `git add` on the file again. @@ -1172,8 +1172,9 @@ annoying to have these untracked files lying around; e.g. they make `git add .` practically useless, and they keep showing up in the output of `git status`. -You can tell Git to ignore certain files by creating a file called .gitignore -in the top level of your working directory, with contents such as: +You can tell Git to ignore certain files by creating a file called +`.gitignore` in the top level of your working directory, with contents +such as: ------------------------------------------------- # Lines starting with '#' are considered comments. @@ -1197,10 +1198,10 @@ for other users who clone your repository. If you wish the exclude patterns to affect only certain repositories (instead of every repository for a given project), you may instead put -them in a file in your repository named .git/info/exclude, or in any file -specified by the `core.excludesfile` configuration variable. Some Git -commands can also take exclude patterns directly on the command line. -See linkgit:gitignore[5] for the details. +them in a file in your repository named `.git/info/exclude`, or in any +file specified by the `core.excludesfile` configuration variable. +Some Git commands can also take exclude patterns directly on the +command line. See linkgit:gitignore[5] for the details. [[how-to-merge]] How to merge @@ -1213,10 +1214,10 @@ linkgit:git-merge[1]: $ git merge branchname ------------------------------------------------- -merges the development in the branch "branchname" into the current +merges the development in the branch `branchname` into the current branch. -A merge is made by combining the changes made in "branchname" and the +A merge is made by combining the changes made in `branchname` and the changes made up to the latest commit in your current branch since their histories forked. The work tree is overwritten by the result of the merge when this combining is done cleanly, or overwritten by a @@ -1338,7 +1339,7 @@ that part is not conflicting and is not shown. Same for stage 3). The diff above shows the differences between the working-tree version of file.txt and the stage 2 and stage 3 versions. So instead of preceding -each line by a single "+" or "-", it now uses two columns: the first +each line by a single `+` or `-`, it now uses two columns: the first column is used for differences between the first parent and the working directory copy, and the second for differences between the second parent and the working directory copy. (See the "COMBINED DIFF FORMAT" section @@ -1613,7 +1614,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f You will see informational messages on dangling objects. They are objects that still exist in the repository but are no longer referenced by any of -your branches, and can (and will) be removed after a while with "gc". +your branches, and can (and will) be removed after a while with `gc`. You can run `git fsck --no-dangling` to suppress these messages, and still view real errors. @@ -1625,9 +1626,9 @@ Recovering lost changes Reflogs ^^^^^^^ -Say you modify a branch with +linkgit:git-reset[1] \--hard+, and then -realize that the branch was the only reference you had to that point in -history. +Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>, +and then realize that the branch was the only reference you had to +that point in history. Fortunately, Git also keeps a log, called a "reflog", of all the previous values of each branch. So in this case you can still find the @@ -1638,8 +1639,8 @@ $ git log master@{1} ------------------------------------------------- This lists the commits reachable from the previous version of the -"master" branch head. This syntax can be used with any Git command -that accepts a commit, not just with git log. Some other examples: +`master` branch head. This syntax can be used with any Git command +that accepts a commit, not just with `git log`. Some other examples: ------------------------------------------------- $ git show master@{2} # See where the branch pointed 2, @@ -1743,8 +1744,8 @@ one step: $ git pull origin master ------------------------------------------------- -In fact, if you have "master" checked out, then this branch has been -configured by "git clone" to get changes from the HEAD branch of the +In fact, if you have `master` checked out, then this branch has been +configured by `git clone` to get changes from the HEAD branch of the origin repository. So often you can accomplish the above with just a simple @@ -1759,11 +1760,11 @@ the current branch. More generally, a branch that is created from a remote-tracking branch will pull by default from that branch. See the descriptions of the -branch.<name>.remote and branch.<name>.merge options in +`branch.<name>.remote` and `branch.<name>.merge` options in linkgit:git-config[1], and the discussion of the `--track` option in linkgit:git-checkout[1], to learn how to control these defaults. -In addition to saving you keystrokes, "git pull" also helps you by +In addition to saving you keystrokes, `git pull` also helps you by producing a default commit message documenting the branch and repository that you pulled from. @@ -1771,7 +1772,7 @@ repository that you pulled from. <<fast-forwards,fast-forward>>; instead, your branch will just be updated to point to the latest commit from the upstream branch.) -The `git pull` command can also be given "." as the "remote" repository, +The `git pull` command can also be given `.` as the "remote" repository, in which case it just merges in a branch from the current repository; so the commands @@ -1796,7 +1797,7 @@ $ git format-patch origin ------------------------------------------------- will produce a numbered series of files in the current directory, one -for each patch in the current branch but not in origin/HEAD. +for each patch in the current branch but not in `origin/HEAD`. `git format-patch` can include an initial "cover letter". You can insert commentary on individual patches after the three dash line which @@ -1818,7 +1819,7 @@ Importing patches to a project Git also provides a tool called linkgit:git-am[1] (am stands for "apply mailbox"), for importing such an emailed series of patches. Just save all of the patch-containing messages, in order, into a -single mailbox file, say "patches.mbox", then run +single mailbox file, say `patches.mbox`, then run ------------------------------------------------- $ git am -3 patches.mbox @@ -1826,7 +1827,7 @@ $ git am -3 patches.mbox Git will apply each patch in order; if any conflicts are found, it will stop, and you can fix the conflicts as described in -"<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells +"<<resolving-a-merge,Resolving a merge>>". (The `-3` option tells Git to perform a merge; if you would prefer it just to abort and leave your tree and index untouched, you may omit that option.) @@ -1902,7 +1903,7 @@ We explain how to do this in the following sections. Setting up a public repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Assume your personal repository is in the directory ~/proj. We +Assume your personal repository is in the directory `~/proj`. We first create a new clone of the repository and tell `git daemon` that it is meant to be public: @@ -1912,10 +1913,10 @@ $ touch proj.git/git-daemon-export-ok ------------------------------------------------- The resulting directory proj.git contains a "bare" git repository--it is -just the contents of the ".git" directory, without any files checked out +just the contents of the `.git` directory, without any files checked out around it. -Next, copy proj.git to the server where you plan to host the +Next, copy `proj.git` to the server where you plan to host the public repository. You can use scp, rsync, or whatever is most convenient. @@ -1926,8 +1927,8 @@ Exporting a Git repository via the Git protocol This is the preferred method. If someone else administers the server, they should tell you what -directory to put the repository in, and what git:// URL it will appear -at. You can then skip to the section +directory to put the repository in, and what `git://` URL it will +appear at. You can then skip to the section "<<pushing-changes-to-a-public-repository,Pushing changes to a public repository>>", below. @@ -1962,7 +1963,7 @@ $ mv hooks/post-update.sample hooks/post-update (For an explanation of the last two lines, see linkgit:git-update-server-info[1] and linkgit:githooks[5].) -Advertise the URL of proj.git. Anybody else should then be able to +Advertise the URL of `proj.git`. Anybody else should then be able to clone or pull from that URL, for example with a command line like: ------------------------------------------------- @@ -1985,8 +1986,8 @@ access, which you will need to update the public repository with the latest changes created in your private repository. The simplest way to do this is using linkgit:git-push[1] and ssh; to -update the remote branch named "master" with the latest state of your -branch named "master", run +update the remote branch named `master` with the latest state of your +branch named `master`, run ------------------------------------------------- $ git push ssh://yourserver.com/~you/proj.git master:master @@ -2002,7 +2003,7 @@ As with `git fetch`, `git push` will complain if this does not result in a <<fast-forwards,fast-forward>>; see the following section for details on handling this case. -Note that the target of a "push" is normally a +Note that the target of a `push` is normally a <<def_bare_repository,bare>> repository. You can also push to a repository that has a checked-out working tree, but a push to update the currently checked-out branch is denied by default to prevent confusion. @@ -2030,9 +2031,9 @@ which lets you do the same push with just $ git push public-repo master ------------------------------------------------- -See the explanations of the remote.<name>.url, branch.<name>.remote, -and remote.<name>.push options in linkgit:git-config[1] for -details. +See the explanations of the `remote.<name>.url`, +`branch.<name>.remote`, and `remote.<name>.push` options in +linkgit:git-config[1] for details. [[forcing-push]] What to do when a push fails @@ -2167,7 +2168,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see Now create the branches in which you are going to work; these start out at the current tip of origin/master branch, and should be set up (using -the --track option to linkgit:git-branch[1]) to merge changes in from +the `--track` option to linkgit:git-branch[1]) to merge changes in from Linus by default. ------------------------------------------------- @@ -2186,7 +2187,7 @@ Important note! If you have any local changes in these branches, then this merge will create a commit object in the history (with no local changes Git will simply do a "fast-forward" merge). Many people dislike the "noise" that this creates in the Linux history, so you should avoid -doing this capriciously in the "release" branch, as these noisy commits +doing this capriciously in the `release` branch, as these noisy commits will become part of the permanent history when you ask Linus to pull from the release branch. @@ -2228,7 +2229,7 @@ patches), and create a new branch from a recent stable tag of Linus's branch. Picking a stable base for your branch will: 1) help you: by avoiding inclusion of unrelated and perhaps lightly tested changes -2) help future bug hunters that use "git bisect" to find problems +2) help future bug hunters that use `git bisect` to find problems ------------------------------------------------- $ git checkout -b speed-up-spinlocks v2.6.35 @@ -2253,9 +2254,9 @@ It is unlikely that you would have any conflicts here ... but you might if you spent a while on this step and had also pulled new versions from upstream. Some time later when enough time has passed and testing done, you can pull the -same branch into the "release" tree ready to go upstream. This is where you +same branch into the `release` tree ready to go upstream. This is where you see the value of keeping each patch (or patch series) in its own branch. It -means that the patches can be moved into the "release" tree in any order. +means that the patches can be moved into the `release` tree in any order. ------------------------------------------------- $ git checkout release && git pull . speed-up-spinlocks @@ -2288,7 +2289,7 @@ If it has been merged, then there will be no output.) Once a patch completes the great cycle (moving from test to release, then pulled by Linus, and finally coming back into your local -"origin/master" branch), the branch for this change is no longer needed. +`origin/master` branch), the branch for this change is no longer needed. You detect this when the output from: ------------------------------------------------- @@ -2303,8 +2304,8 @@ $ git branch -d branchname Some changes are so trivial that it is not necessary to create a separate branch and then merge into each of the test and release branches. For -these changes, just apply directly to the "release" branch, and then -merge that into the "test" branch. +these changes, just apply directly to the `release` branch, and then +merge that into the `test` branch. After pushing your work to `mytree`, you can use linkgit:git-request-pull[1] to prepare a "please pull" request message @@ -2337,7 +2338,7 @@ origin) fi ;; *) - echo "Usage: $0 origin|test|release" 1>&2 + echo "usage: $0 origin|test|release" 1>&2 exit 1 ;; esac @@ -2351,7 +2352,7 @@ pname=$0 usage() { - echo "Usage: $pname branch test|release" 1>&2 + echo "usage: $pname branch test|release" 1>&2 exit 1 } @@ -2475,8 +2476,8 @@ you are rewriting history. Keeping a patch series up to date using git rebase -------------------------------------------------- -Suppose that you create a branch "mywork" on a remote-tracking branch -"origin", and create some commits on top of it: +Suppose that you create a branch `mywork` on a remote-tracking branch +`origin`, and create some commits on top of it: ------------------------------------------------- $ git checkout -b mywork origin @@ -2488,7 +2489,7 @@ $ git commit ------------------------------------------------- You have performed no merges into mywork, so it is just a simple linear -sequence of patches on top of "origin": +sequence of patches on top of `origin`: ................................................ o--o--O <-- origin @@ -2497,7 +2498,7 @@ sequence of patches on top of "origin": ................................................ Some more interesting work has been done in the upstream project, and -"origin" has advanced: +`origin` has advanced: ................................................ o--o--O--o--o--o <-- origin @@ -2505,7 +2506,7 @@ Some more interesting work has been done in the upstream project, and a--b--c <-- mywork ................................................ -At this point, you could use "pull" to merge your changes back in; +At this point, you could use `pull` to merge your changes back in; the result would create a new merge commit, like this: ................................................ @@ -2524,7 +2525,7 @@ $ git rebase origin ------------------------------------------------- This will remove each of your commits from mywork, temporarily saving -them as patches (in a directory named ".git/rebase-apply"), update mywork to +them as patches (in a directory named `.git/rebase-apply`), update mywork to point at the latest version of origin, then apply each of the saved patches to the new mywork. The result will look like: @@ -2795,10 +2796,10 @@ arbitrary name: $ git fetch origin todo:my-todo-work ------------------------------------------------- -The first argument, "origin", just tells Git to fetch from the +The first argument, `origin`, just tells Git to fetch from the repository you originally cloned from. The second argument tells Git -to fetch the branch named "todo" from the remote repository, and to -store it locally under the name refs/heads/my-todo-work. +to fetch the branch named `todo` from the remote repository, and to +store it locally under the name `refs/heads/my-todo-work`. You can also fetch branches from other repositories; so @@ -2806,8 +2807,8 @@ You can also fetch branches from other repositories; so $ git fetch git://example.com/proj.git master:example-master ------------------------------------------------- -will create a new branch named "example-master" and store in it the -branch named "master" from the repository at the given URL. If you +will create a new branch named `example-master` and store in it the +branch named `master` from the repository at the given URL. If you already have a branch named example-master, it will attempt to <<fast-forwards,fast-forward>> to the commit given by example.com's master branch. In more detail: @@ -2816,7 +2817,7 @@ master branch. In more detail: git fetch and fast-forwards --------------------------- -In the previous example, when updating an existing branch, "git fetch" +In the previous example, when updating an existing branch, `git fetch` checks to make sure that the most recent commit on the remote branch is a descendant of the most recent commit on your copy of the branch before updating your copy of the branch to point at the new @@ -2842,11 +2843,11 @@ resulting in a situation like: o--o--o <-- new head of the branch ................................................ -In this case, "git fetch" will fail, and print out a warning. +In this case, `git fetch` will fail, and print out a warning. In that case, you can still force Git to update to the new head, as described in the following section. However, note that in the -situation above this may mean losing the commits labeled "a" and "b", +situation above this may mean losing the commits labeled `a` and `b`, unless you've already created a reference of your own pointing to them. @@ -2861,7 +2862,7 @@ descendant of the old head, you may force the update with: $ git fetch git://example.com/proj.git +master:refs/remotes/example/master ------------------------------------------------- -Note the addition of the "+" sign. Alternatively, you can use the "-f" +Note the addition of the `+` sign. Alternatively, you can use the `-f` flag to force updates of all the fetched branches, as in: ------------------------------------------------- @@ -2875,7 +2876,7 @@ may be lost, as we saw in the previous section. Configuring remote-tracking branches ------------------------------------ -We saw above that "origin" is just a shortcut to refer to the +We saw above that `origin` is just a shortcut to refer to the repository that you originally cloned from. This information is stored in Git configuration variables, which you can see using linkgit:git-config[1]: @@ -2984,7 +2985,7 @@ Commit Object ~~~~~~~~~~~~~ The "commit" object links a physical state of a tree with a description -of how we got there and why. Use the --pretty=raw option to +of how we got there and why. Use the `--pretty=raw` option to linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite commit: @@ -3026,7 +3027,7 @@ of the tree referred to by this commit with the trees associated with its parents. In particular, Git does not attempt to record file renames explicitly, though it can identify cases where the existence of the same file data at changing paths suggests a rename. (See, for example, the --M option to linkgit:git-diff[1]). +`-M` option to linkgit:git-diff[1]). A commit is usually created by linkgit:git-commit[1], which creates a commit whose parent is normally the current HEAD, and whose tree is @@ -3077,7 +3078,7 @@ Blob Object ~~~~~~~~~~~ You can use linkgit:git-show[1] to examine the contents of a blob; take, -for example, the blob in the entry for "COPYING" from the tree above: +for example, the blob in the entry for `COPYING` from the tree above: ------------------------------------------------ $ git show 6ff87c4664 @@ -3160,14 +3161,14 @@ nLE/L9aUXdWeTFPron96DLA= See the linkgit:git-tag[1] command to learn how to create and verify tag objects. (Note that linkgit:git-tag[1] can also be used to create "lightweight tags", which are not tag objects at all, but just simple -references whose names begin with "refs/tags/"). +references whose names begin with `refs/tags/`). [[pack-files]] How Git stores objects efficiently: pack files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Newly created objects are initially created in a file named after the -object's SHA-1 hash (stored in .git/objects). +object's SHA-1 hash (stored in `.git/objects`). Unfortunately this system becomes inefficient once a project has a lot of objects. Try this on an old project: @@ -3208,9 +3209,9 @@ $ git prune to remove any of the "loose" objects that are now contained in the pack. This will also remove any unreferenced objects (which may be -created when, for example, you use "git reset" to remove a commit). +created when, for example, you use `git reset` to remove a commit). You can verify that the loose objects are gone by looking at the -.git/objects directory or by running +`.git/objects` directory or by running ------------------------------------------------ $ git count-objects @@ -3237,7 +3238,7 @@ branch still exists, as does everything it pointed to. The branch pointer itself just doesn't, since you replaced it with another one. There are also other situations that cause dangling objects. For -example, a "dangling blob" may arise because you did a "git add" of a +example, a "dangling blob" may arise because you did a `git add` of a file, but then, before you actually committed it and made it part of the bigger picture, you changed something else in that file and committed that *updated* thing--the old state that you added originally ends up @@ -3280,14 +3281,14 @@ $ git show <dangling-blob/tree-sha-goes-here> ------------------------------------------------ to show what the contents of the blob were (or, for a tree, basically -what the "ls" for that directory was), and that may give you some idea +what the `ls` for that directory was), and that may give you some idea of what the operation was that left that dangling object. Usually, dangling blobs and trees aren't very interesting. They're almost always the result of either being a half-way mergebase (the blob will often even have the conflict markers from a merge in it, if you have had conflicting merges that you fixed up by hand), or simply -because you interrupted a "git fetch" with ^C or something like that, +because you interrupted a `git fetch` with ^C or something like that, leaving _some_ of the new objects in the object database, but just dangling and useless. @@ -3298,16 +3299,16 @@ state, you can just prune all unreachable objects: $ git prune ------------------------------------------------ -and they'll be gone. But you should only run "git prune" on a quiescent +and they'll be gone. But you should only run `git prune` on a quiescent repository--it's kind of like doing a filesystem fsck recovery: you don't want to do that while the filesystem is mounted. -(The same is true of "git fsck" itself, btw, but since +(The same is true of `git fsck` itself, btw, but since `git fsck` never actually *changes* the repository, it just reports on what it found, `git fsck` itself is never 'dangerous' to run. Running it while somebody is actually changing the repository can cause confusing and scary messages, but it won't actually do anything bad. In -contrast, running "git prune" while somebody is actively changing the +contrast, running `git prune` while somebody is actively changing the repository is a *BAD* idea). [[recovering-from-repository-corruption]] @@ -3345,7 +3346,7 @@ missing blob 4b9458b3786228369c63936db65827de3cc06200 Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 points to it. If you could find just one copy of that missing blob object, possibly in some other repository, you could move it into -.git/objects/4b/9458b3... and be done. Suppose you can't. You can +`.git/objects/4b/9458b3...` and be done. Suppose you can't. You can still examine the tree that pointed to it with linkgit:git-ls-tree[1], which might output something like: @@ -3360,10 +3361,10 @@ $ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 ------------------------------------------------ So now you know that the missing blob was the data for a file named -"myfile". And chances are you can also identify the directory--let's -say it's in "somedirectory". If you're lucky the missing copy might be +`myfile`. And chances are you can also identify the directory--let's +say it's in `somedirectory`. If you're lucky the missing copy might be the same as the copy you have checked out in your working tree at -"somedirectory/myfile"; you can test whether that's right with +`somedirectory/myfile`; you can test whether that's right with linkgit:git-hash-object[1]: ------------------------------------------------ @@ -3418,7 +3419,7 @@ $ git hash-object -w <recreated-file> and your repository is good again! -(Btw, you could have ignored the fsck, and started with doing a +(Btw, you could have ignored the `fsck`, and started with doing a ------------------------------------------------ $ git log --raw --all @@ -3432,7 +3433,7 @@ just missing one particular blob version. The index ----------- -The index is a binary file (generally kept in .git/index) containing a +The index is a binary file (generally kept in `.git/index`) containing a sorted list of path names, each with permissions and the SHA-1 of a blob object; linkgit:git-ls-files[1] can show you the contents of the index: @@ -3572,7 +3573,7 @@ $ ls -a The `git submodule add <repo> <path>` command does a couple of things: -- It clones the submodule from <repo> to the given <path> under the +- It clones the submodule from `<repo>` to the given `<path>` under the current directory and by default checks out the master branch. - It adds the submodule's clone path to the linkgit:gitmodules[5] file and adds this file to the index, ready to be committed. @@ -3700,11 +3701,11 @@ Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path In older Git versions it could be easily forgotten to commit new or modified files in a submodule, which silently leads to similar problems as not pushing -the submodule changes. Starting with Git 1.7.0 both "git status" and "git diff" +the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff` in the superproject show submodules as modified when they contain new or -modified files to protect against accidentally committing such a state. "git -diff" will also add a "-dirty" to the work tree side when generating patch -output or used with the --submodule option: +modified files to protect against accidentally committing such a state. `git +diff` will also add a `-dirty` to the work tree side when generating patch +output or used with the `--submodule` option: ------------------------------------------------- $ git diff @@ -3880,7 +3881,7 @@ or, if you want to check out all of the index, use `-a`. NOTE! `git checkout-index` normally refuses to overwrite old files, so if you have an old version of the tree already checked out, you will -need to use the "-f" flag ('before' the "-a" flag or the filename) to +need to use the `-f` flag ('before' the `-a` flag or the filename) to 'force' the checkout. @@ -3891,7 +3892,7 @@ from one representation to the other: Tying it all together ~~~~~~~~~~~~~~~~~~~~~ -To commit a tree you have instantiated with "git write-tree", you'd +To commit a tree you have instantiated with `git write-tree`, you'd create a "commit" object that refers to that tree and the history behind it--most notably the "parent" commits that preceded it in history. @@ -4152,8 +4153,9 @@ As a result, the general consistency of an object can always be tested independently of the contents or the type of the object: all objects can be validated by verifying that (a) their hashes match the content of the file and (b) the object successfully inflates to a stream of bytes that -forms a sequence of <ascii type without space> {plus} <space> {plus} <ascii decimal -size> {plus} <byte\0> {plus} <binary object data>. +forms a sequence of +`<ascii type without space> + <space> + <ascii decimal size> + +<byte\0> + <binary object data>`. The structured objects can further have their structure and connectivity to other objects verified. This is generally done with @@ -4632,10 +4634,10 @@ Think about how to create a clear chapter dependency graph that will allow people to get to important topics without necessarily reading everything in between. -Scan Documentation/ for other stuff left out; in particular: +Scan `Documentation/` for other stuff left out; in particular: - howto's -- some of technical/? +- some of `technical/`? - hooks - list of commands in linkgit:git[1] |