diff options
Diffstat (limited to 'Documentation')
117 files changed, 555 insertions, 178 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 1c3a9fead5..d62aebd848 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -3,6 +3,7 @@ *.[1-8] *.made *.texi +*.pdf git.info gitman.info howto-index.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 36989b7f65..18c71d763f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -232,6 +232,7 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) clean: $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 $(RM) *.texi *.texi+ *.texi++ git.info gitman.info + $(RM) *.pdf $(RM) howto-index.txt howto/*.html doc.dep $(RM) technical/api-*.html technical/api-index.txt $(RM) $(cmds_txt) *.made diff --git a/Documentation/RelNotes/1.7.7.txt b/Documentation/RelNotes/1.7.7.txt new file mode 100644 index 0000000000..6d3bfd1968 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.txt @@ -0,0 +1,98 @@ +Git v1.7.7 Release Notes +======================== + +Updates since v1.7.6 +-------------------- + + * The scripting part of the codebase is getting prepared for i18n/l10n. + + * Interix and Cygwin ports got updated. + + * Various codepaths that invoked zlib deflate/inflate assumed that these + functions can compress or uncompress more than 4GB data in one call on + platforms with 64-bit long, which has been corrected. + + * "git archive" can be told to pass the output to gzip compression and + produce "archive.tar.gz". + + * "git checkout" (both the code to update the files upon checking out a + different branch, the code to checkout specific set of files) learned + to stream the data from object store when possible, without having to + read the entire contents of a file in memory first. + + * "git clone" can now take "--config key=value" option to set the + repository configuration options that affect the initial checkout. + + * "git diff --stat" learned --stat-count option to limit the output of + diffstat report. + + * "git fetch", "git push" and friends no longer show connection + errors for addresses that couldn't be connected when at least one + address succeeds (this is arguably a regression but a deliberate + one). + + * "git grep" learned --break and --heading options, to let users mimic + output format of "ack". + + * "git rebase master topci" no longer spews usage hints after giving + "fatal: no such branch: topci" error message. + + * "git stash" learned --include-untracked option. + + * "git submodule update" used to stop at the first error updating a + submodule; it now goes on to update other submodules that can be + updated, and reports the ones with errors at the end. + + * "git verify-pack" has been rewritten to use the "index-pack" machinery + that is more efficient in reading objects in packfiles. + + * test scripts for gitweb tried to run even when CGI-related perl modules + are not installed; it now exits early when they are unavailable. + +Also contains various documentation updates and minor miscellaneous +changes. + + +Fixes since v1.7.6 +------------------ + +Unless otherwise noted, all the fixes in 1.7.6.X maintenance track are +included in this release. + + * "git checkout -b <branch>" sometimes wrote a bogus reflog entry, + causing later "git checkout -" fail. + (merge 71ee7fd jc/checkout-reflog-fix~1 later). + + * "git diff --cc" learned to correctly ignore binary files. + (merge 0508fe5 jk/combine-diff-binary-etc later) + + * "git fetch" did not recurse into submodules in subdirectories. + (merge ea2d325 jl/maint-fetch-recursive-fix later) + + * "git rebase -i -p" incorrectly dropped commits from side branches. + (merge 12bf828 aw/rebase-i-p later) + + * "git submodule add" did not allow a relative repository path when + the superproject did not have any default remote url. + (merge f22a17e8 jl/submodule-add-relurl-wo-upstream later) + + * "git submodule foreach" failed to correctly give the standard input to + the user-supplied command it invoked. + (merge 4dca1aa bc/submodule-foreach-stdin-fix-1.7.4 later) + + * submodules that the user has never showed interest in by running + "git submodule init" was incorrectly marked as interesting by "git + submodule sync". + (merge 2cd9de3 jc/submodule-sync-no-auto-vivify later) + + * "git tag -l <glob>..." did not take multiple glob patterns from the + command line. + (merge 588d0e8 jk/tag-list-multiple-patterns later) + +-- +exec >/var/tmp/1 +echo O=$(git describe master) +O=v1.7.6-344-g22f4128 +git log --first-parent --oneline $O..master +echo +git shortlog --no-merges ^maint ^$O master diff --git a/Documentation/config.txt b/Documentation/config.txt index 6b93777199..0658ffb889 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -344,7 +344,9 @@ core.logAllRefUpdates:: SHA1, the date/time and the reason of the update, but only when the file exists. If this configuration variable is set to true, missing "$GIT_DIR/logs/<ref>" - file is automatically created for branch heads. + file is automatically created for branch heads (i.e. under + refs/heads/), remote refs (i.e. under refs/remotes/), + note refs (i.e. under refs/notes/), and the symbolic ref HEAD. + This information can be used to determine what commit was the tip of a branch "2 days ago". @@ -676,7 +678,7 @@ branch.<name>.rebase:: browser.<tool>.cmd:: Specify the command to invoke the specified browser. The specified command is evaluated in shell with the URLs passed - as arguments. (See linkgit:git-web--browse[1].) + as arguments. (See linkgit:git-web{litdd}browse[1].) browser.<tool>.path:: Override the path for the given tool that may be used to @@ -1196,6 +1198,14 @@ http.proxy:: environment variable (see linkgit:curl[1]). This can be overridden on a per-remote basis; see remote.<name>.proxy +http.cookiefile:: + File containing previously stored cookie lines which should be used + in the git http session, if they match the server. The file format + of the file to read cookies from should be plain HTTP headers or + the Netscape/Mozilla cookie file format (see linkgit:curl[1]). + NOTE that the file specified with http.cookiefile is only used as + input. No cookies will be stored in the file. + http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 24f189f96b..b620b3afec 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -48,11 +48,17 @@ endif::git-format-patch[] --patience:: Generate a diff using the "patience diff" algorithm. ---stat[=<width>[,<name-width>]]:: +--stat[=<width>[,<name-width>[,<count>]]]:: Generate a diffstat. You can override the default output width for 80-column terminal by `--stat=<width>`. The width of the filename part can be controlled by giving another width to it separated by a comma. + By giving a third parameter `<count>`, you can limit the + output to the first `<count>` lines, followed by + `...` if there are more. ++ +These parameters can also be set individually with `--stat-width=<width>`, +`--stat-name-width=<name-width>` and `--stat-count=<count>`. --numstat:: Similar to `\--stat`, but shows number of added and @@ -416,6 +422,17 @@ endif::git-format-patch[] --no-ext-diff:: Disallow external diff drivers. +--textconv:: +--no-textconv:: + Allow (or disallow) external text conversion filters to be run + when comparing binary files. See linkgit:gitattributes[5] for + details. Because textconv filters are typically a one-way + conversion, the resulting diff is suitable for human + consumption, but cannot be applied. For this reason, textconv + filters are enabled by default only for linkgit:git-diff[1] and + linkgit:git-log[1], but not for linkgit:git-format-patch[1] or + diff plumbing commands. + --ignore-submodules[=<when>]:: Ignore changes to submodules in the diff generation. <when> can be either "none", "untracked", "dirty" or "all", which is the default diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index 9eb75c37da..05fd482b74 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -7,6 +7,7 @@ git-annotate - Annotate file lines with commit information SYNOPSIS -------- +[verse] 'git annotate' [options] file [revision] DESCRIPTION diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 9c750e2444..ac7006e640 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -101,6 +101,25 @@ tar.umask:: details. If `--remote` is used then only the configuration of the remote repository takes effect. +tar.<format>.command:: + This variable specifies a shell command through which the tar + output generated by `git archive` should be piped. The command + is executed using the shell with the generated tar file on its + standard input, and should produce the final output on its + standard output. Any compression-level options will be passed + to the command (e.g., "-9"). An output file with the same + extension as `<format>` will be use this format if no other + format is given. ++ +The "tar.gz" and "tgz" formats are defined automatically and default to +`gzip -cn`. You may override them with custom commands. + +tar.<format>.remote:: + If true, enable `<format>` for use by remote clients via + linkgit:git-upload-archive[1]. Defaults to false for + user-defined formats, but true for the "tar.gz" and "tgz" + formats. + ATTRIBUTES ---------- @@ -123,32 +142,46 @@ while archiving any tree in your `$GIT_DIR/info/attributes` file. EXAMPLES -------- -git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -):: +`git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)`:: Create a tar archive that contains the contents of the latest commit on the current branch, and extract it in the `/var/tmp/junk` directory. -git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz:: +`git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a compressed tarball for v1.4.0 release. -git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz:: +`git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz`:: + + Same as above, but using the builtin tar.gz handling. + +`git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0`:: + + Same as above, but the format is inferred from the output file. + +`git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz`:: Create a compressed tarball for v1.4.0 release, but without a global extended pax header. -git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip:: +`git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip`:: Put everything in the current head's Documentation/ directory into 'git-1.4.0-docs.zip', with the prefix 'git-docs/'. -git archive -o latest.zip HEAD:: +`git archive -o latest.zip HEAD`:: Create a Zip archive that contains the contents of the latest commit on the current branch. Note that the output format is inferred by the extension of the output file. +`git config tar.tar.xz.command "xz -c"`:: + + Configure a "tar.xz" format for making LZMA-compressed tarfiles. + You can use it specifying `--format=tar.xz`, or by creating an + output file like `-o foo.tar.xz`. + SEE ALSO -------- diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 7b7bafba0c..ab60a18470 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -8,6 +8,7 @@ git-bisect - Find by binary search the change that introduced a bug SYNOPSIS -------- +[verse] 'git bisect' <subcommand> <options> DESCRIPTION diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 205d83dd0b..c9fdf84a08 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -18,9 +18,12 @@ Checks if a given 'refname' is acceptable, and exits with a non-zero status if it is not. A reference is used in git to specify branches and tags. A -branch head is stored under the `$GIT_DIR/refs/heads` directory, and -a tag is stored under the `$GIT_DIR/refs/tags` directory (or, if refs -are packed by `git gc`, as entries in the `$GIT_DIR/packed-refs` file). +branch head is stored in the `refs/heads` hierarchy, while +a tag is stored in the `refs/tags` hierarchy of the ref namespace +(typically in `$GIT_DIR/refs/heads` and `$GIT_DIR/refs/tags` +directories or, as entries in file `$GIT_DIR/packed-refs` +if refs are packed by `git gc`). + git imposes the following rules on how references are named: . They can include slash `/` for hierarchical (directory) diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 9d8fe0d261..7cfa3d92ac 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -7,6 +7,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits SYNOPSIS -------- +[verse] 'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>... DESCRIPTION @@ -111,31 +112,31 @@ effect to your index in a row. EXAMPLES -------- -git cherry-pick master:: +`git cherry-pick master`:: Apply the change introduced by the commit at the tip of the master branch and create a new commit with this change. -git cherry-pick ..master:: -git cherry-pick ^HEAD master:: +`git cherry-pick ..master`:: +`git cherry-pick ^HEAD master`:: Apply the changes introduced by all commits that are ancestors of master but not of HEAD to produce new commits. -git cherry-pick master{tilde}4 master{tilde}2:: +`git cherry-pick master{tilde}4 master{tilde}2`:: Apply the changes introduced by the fifth and third last commits pointed to by master and create 2 new commits with these changes. -git cherry-pick -n master~1 next:: +`git cherry-pick -n master~1 next`:: Apply to the working tree and the index the changes introduced by the second last commit pointed to by master and by the last commit pointed to by next, but do not create any commit with these changes. -git cherry-pick --ff ..next:: +`git cherry-pick --ff ..next`:: If history is linear and HEAD is an ancestor of next, update the working tree and advance the HEAD pointer to match next. @@ -143,7 +144,7 @@ git cherry-pick --ff ..next:: are in next but not HEAD to the current branch, creating a new commit for each new change. -git rev-list --reverse master \-- README | git cherry-pick -n --stdin:: +`git rev-list --reverse master \-- README | git cherry-pick -n --stdin`:: Apply the changes introduced by all commits on the master branch that touched README to the working tree and index, diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 79448c505b..f6c19c734d 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -7,6 +7,7 @@ git-cherry - Find commits not merged upstream SYNOPSIS -------- +[verse] 'git cherry' [-v] [<upstream> [<head> [<limit>]]] DESCRIPTION diff --git a/Documentation/git-citool.txt b/Documentation/git-citool.txt index 6e5c8126f5..c7a11c36c1 100644 --- a/Documentation/git-citool.txt +++ b/Documentation/git-citool.txt @@ -7,6 +7,7 @@ git-citool - Graphical alternative to git-commit SYNOPSIS -------- +[verse] 'git citool' DESCRIPTION diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index b093e45497..4b8b26b75e 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -159,6 +159,17 @@ objects from the source repository into a pack in the cloned repository. Specify the directory from which templates will be used; (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) +--config <key>=<value>:: +-c <key>=<value>:: + Set a configuration variable in the newly-created repository; + this takes effect immediately after the repository is + initialized, but before the remote history is fetched or any + files checked out. The key is in the same format as expected by + linkgit:git-config[1] (e.g., `core.eol=true`). If multiple + values are given for the same key, each value will be written to + the config file. This makes it safe, for example, to add + additional fetch refspecs to the origin remote. + --depth <depth>:: Create a 'shallow' clone with a history truncated to the specified number of revisions. A shallow repository has a diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index f524d76019..0fdb82ee86 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -8,6 +8,7 @@ git-commit-tree - Create a new commit object SYNOPSIS -------- +[verse] 'git commit-tree' <tree> [(-p <parent commit>)...] < changelog DESCRIPTION diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 7951cb7b00..5cc84a1391 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -284,7 +284,7 @@ When recording your own work, the contents of modified files in your working tree are temporarily stored to a staging area called the "index" with 'git add'. A file can be reverted back, only in the index but not in the working tree, -to that of the last commit with `git reset HEAD -- <file>`, +to that of the last commit with `git reset HEAD \-- <file>`, which effectively reverts 'git add' and prevents the changes to this file from participating in the next commit. After building the state to be committed incrementally with these commands, diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index a73933a931..23c80cea64 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -7,6 +7,7 @@ git-count-objects - Count unpacked number of objects and their disk consumption SYNOPSIS -------- +[verse] 'git count-objects' [-v] DESCRIPTION diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index ad93a3e84e..7f79cec3f8 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,6 +8,7 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- +[verse] 'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index 8d481948bd..906774f0f7 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -8,6 +8,7 @@ git-diff-files - Compares files in the working tree and the index SYNOPSIS -------- +[verse] 'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...] DESCRIPTION diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 2ea22abca2..c0b7c581ad 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -8,6 +8,7 @@ git-diff-index - Compares content and mode of blobs between the index and reposi SYNOPSIS -------- +[verse] 'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] DESCRIPTION diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 590f410abf..a03515f1ec 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -7,6 +7,7 @@ git-difftool - Show changes using common diff tools SYNOPSIS -------- +[verse] 'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...] DESCRIPTION diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 781bd6edc3..f37eada63a 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -8,6 +8,7 @@ git-fast-export - Git data exporter SYNOPSIS -------- +[verse] 'git fast-export [options]' | 'git fast-import' DESCRIPTION @@ -82,6 +83,10 @@ marks the same across runs. allow that. So fake a tagger to be able to fast-import the output. +--use-done-feature:: + Start the stream with a 'feature done' stanza, and terminate + it with a 'done' command. + --no-data:: Skip output of blob objects and instead refer to blobs via their original SHA-1 hash. This is useful when rewriting the diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 249249aac7..2969388880 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -8,6 +8,7 @@ git-fast-import - Backend for fast Git data importers SYNOPSIS -------- +[verse] frontend | 'git fast-import' [options] DESCRIPTION @@ -101,6 +102,12 @@ OPTIONS when the `cat-blob` command is encountered in the stream. The default behaviour is to write to `stdout`. +--done:: + Require a `done` command at the end of the stream. + This option might be useful for detecting errors that + cause the frontend to terminate before it has started to + write a stream. + --export-pack-edges=<file>:: After creating a packfile, print a line of data to <file> listing the filename of the packfile and the last @@ -330,6 +337,11 @@ and control the current import process. More detailed discussion standard output. This command is optional and is not needed to perform an import. +`done`:: + Marks the end of the stream. This command is optional + unless the `done` feature was requested using the + `--done` command line option or `feature done` command. + `cat-blob`:: Causes fast-import to print a blob in 'cat-file --batch' format to the file descriptor set with `--cat-blob-fd` or @@ -648,9 +660,14 @@ paths for a commit are encouraged to do so. `notemodify` ^^^^^^^^^^^^ -Included in a `commit` command to add a new note (annotating a given -commit) or change the content of an existing note. This command has -two different means of specifying the content of the note. +Included in a `commit` `<notes_ref>` command to add a new note +annotating a `<committish>` or change this annotation contents. +Internally it is similar to filemodify 100644 on `<committish>` +path (maybe split into subdirectories). It's not advised to +use any other commands to write to the `<notes_ref>` tree except +`filedeleteall` to delete all existing notes in this tree. +This command has two different means of specifying the content +of the note. External data format:: The data content for the note was already supplied by a prior @@ -1015,6 +1032,11 @@ notes:: Versions of fast-import not supporting notes will exit with a message indicating so. +done:: + Error out if the stream ends without a 'done' command. + Without this feature, errors causing the frontend to end + abruptly at a convenient point in the stream can go + undetected. `option` ~~~~~~~~ @@ -1044,6 +1066,15 @@ not be passed as option: * cat-blob-fd * force +`done` +~~~~~~ +If the `done` feature is not in use, treated as if EOF was read. +This can be used to tell fast-import to finish early. + +If the `--done` command line option or `feature done` command is +in use, the `done` command is mandatory and marks the end of the +stream. + Crash Reports ------------- If fast-import is supplied invalid input it will terminate with a diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 48d4bf6d68..ed1bdaacd1 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -8,6 +8,7 @@ git-fetch-pack - Receive missing objects from another repository SYNOPSIS -------- +[verse] 'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...] DESCRIPTION diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 60ac8d26eb..b41d7c1de1 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -8,12 +8,10 @@ git-fetch - Download objects and refs from another repository SYNOPSIS -------- +[verse] 'git fetch' [<options>] [<repository> [<refspec>...]] - 'git fetch' [<options>] <group> - 'git fetch' --multiple [<options>] [(<repository> | <group>)...] - 'git fetch' --all [<options>] diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 9dc1f2a947..0f2f117383 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,8 +32,9 @@ changes, which would normally have no effect. Nevertheless, this may be useful in the future for compensating for some git bugs or such, therefore such a usage is permitted. -*NOTE*: This command honors `.git/info/grafts`. If you have any grafts -defined, running this command will make them permanent. +*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +If you have any grafts or replacement refs defined, running this command +will make them permanent. *WARNING*! The rewritten history will have different object names for all the objects and will not converge with the original branch. You will not diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt index 90ebb8a594..eec4bdb600 100644 --- a/Documentation/git-fsck-objects.txt +++ b/Documentation/git-fsck-objects.txt @@ -8,6 +8,7 @@ git-fsck-objects - Verifies the connectivity and validity of the objects in the SYNOPSIS -------- +[verse] 'git fsck-objects' ... DESCRIPTION diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 4966cb5784..815afcb922 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -8,6 +8,7 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- +[verse] 'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] DESCRIPTION diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 8035736c96..1e2a20dd26 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -8,6 +8,7 @@ git-get-tar-commit-id - Extract commit ID from an archive created using git-arch SYNOPSIS -------- +[verse] 'git get-tar-commit-id' < <tarfile> diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index e150c77cff..062711139c 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -148,6 +148,13 @@ OPTIONS gives the default to color output. Same as `--color=never`. +--break:: + Print an empty line between matches from different files. + +--heading:: + Show the filename above the matches in that file instead of + at the start of each shown line. + -[ABC] <context>:: Show `context` trailing (`A` -- after), or leading (`B` -- before), or both (`C` -- context) lines, and place a @@ -208,15 +215,15 @@ OPTIONS Examples -------- -git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}:: +`git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}`:: Looks for `time_t` in all tracked .c and .h files in the working directory and its subdirectories. -git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \):: +`git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \)`:: Looks for a line that has `#define` and either `MAX_PATH` or `PATH_MAX`. -git grep --all-match -e NODE -e Unexpected:: +`git grep --all-match -e NODE -e Unexpected`:: Looks for a line that has `NODE` or `Unexpected` in files that have lines that match both. diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index 32a833e0ae..0041994443 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -7,6 +7,7 @@ git-gui - A portable graphical interface to Git SYNOPSIS -------- +[verse] 'git gui' [<command>] [arguments] DESCRIPTION @@ -49,7 +50,7 @@ version:: Examples -------- -git gui blame Makefile:: +`git gui blame Makefile`:: Show the contents of the file 'Makefile' in the current working directory, and provide annotations for both the @@ -58,41 +59,41 @@ git gui blame Makefile:: uncommitted changes (if any) are explicitly attributed to 'Not Yet Committed'. -git gui blame v0.99.8 Makefile:: +`git gui blame v0.99.8 Makefile`:: Show the contents of 'Makefile' in revision 'v0.99.8' and provide annotations for each line. Unlike the above example the file is read from the object database and not the working directory. -git gui blame --line=100 Makefile:: +`git gui blame --line=100 Makefile`:: Loads annotations as described above and automatically scrolls the view to center on line '100'. -git gui citool:: +`git gui citool`:: Make one commit and return to the shell when it is complete. This command returns a non-zero exit code if the window was closed in any way other than by making a commit. -git gui citool --amend:: +`git gui citool --amend`:: Automatically enter the 'Amend Last Commit' mode of the interface. -git gui citool --nocommit:: +`git gui citool --nocommit`:: Behave as normal citool, but instead of making a commit simply terminate with a zero exit code. It still checks that the index does not contain any unmerged entries, so you can use it as a GUI version of linkgit:git-mergetool[1] -git citool:: +`git citool`:: Same as `git gui citool` (above). -git gui browser maint:: +`git gui browser maint`:: Show a browser for the tree of the 'maint' branch. Files selected in the browser can be viewed with the internal diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 42aa2b0c01..9e0b3f6811 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -7,6 +7,7 @@ git-help - display help information about git SYNOPSIS -------- +[verse] 'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND] DESCRIPTION diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index fefa752198..4d42073867 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -8,6 +8,7 @@ git-http-fetch - Download from a remote git repository via HTTP SYNOPSIS -------- +[verse] 'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url> DESCRIPTION diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index 82ae34b9b8..2e67362bd4 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -8,6 +8,7 @@ git-http-push - Push objects over HTTP/DAV to another repository SYNOPSIS -------- +[verse] 'git http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...] DESCRIPTION diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index 4e09708cc9..875d2831a5 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -8,6 +8,7 @@ git-imap-send - Send a collection of patches from stdin to an IMAP folder SYNOPSIS -------- +[verse] 'git imap-send' diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 9f97f5a915..a21e346789 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -8,6 +8,7 @@ git-init-db - Creates an empty git repository SYNOPSIS -------- +[verse] 'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]] diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index f2777a7786..9ac2bbaa56 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -8,6 +8,7 @@ git-init - Create an empty git repository or reinitialize an existing one SYNOPSIS -------- +[verse] 'git init' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]] [directory] diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index 08f85ba046..ea95c90460 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -51,8 +51,8 @@ OPTIONS start:: --start:: - Start the httpd instance and exit. This does not generate - any of the configuration files for spawning a new instance. + Start the httpd instance and exit. Regenerate configuration files + as necessary for spawning a new instance. stop:: --stop:: @@ -62,8 +62,8 @@ stop:: restart:: --restart:: - Restart the httpd instance and exit. This does not generate - any of the configuration files for spawning a new instance. + Restart the httpd instance and exit. Regenerate configuration files + as necessary for spawning a new instance. CONFIGURATION ------------- diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index de5c0d37a5..6c934660d7 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -8,6 +8,7 @@ git-log - Show commit logs SYNOPSIS -------- +[verse] 'git log' [<options>] [<since>..<until>] [[\--] <path>...] DESCRIPTION @@ -87,45 +88,45 @@ include::diff-generate-patch.txt[] Examples -------- -git log --no-merges:: +`git log --no-merges`:: Show the whole commit history, but skip any merges -git log v2.6.12.. include/scsi drivers/scsi:: +`git log v2.6.12.. include/scsi drivers/scsi`:: Show all commits since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories -git log --since="2 weeks ago" \-- gitk:: +`git log --since="2 weeks ago" \-- gitk`:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named 'gitk' -git log --name-status release..test:: +`git log --name-status release..test`:: Show the commits that are in the "test" branch but not yet in the "release" branch, along with the list of paths each commit modifies. -git log --follow builtin-rev-list.c:: +`git log --follow builtin-rev-list.c`:: Shows the commits that changed builtin-rev-list.c, including those commits that occurred before the file was given its present name. -git log --branches --not --remotes=origin:: +`git log --branches --not --remotes=origin`:: Shows all commits that are in any of local branches but not in any of remote-tracking branches for 'origin' (what you have that origin doesn't). -git log master --not --remotes=*/master:: +`git log master --not --remotes=*/master`:: Shows all commits that are in local master but not in any remote repository master branches. -git log -p -m --first-parent:: +`git log -p -m --first-parent`:: Shows the history including change diffs, but only from the "main branch" perspective, skipping commits that come from merged diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index adf7e1c055..c406a11001 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -7,6 +7,7 @@ git-lost-found - Recover lost refs that luckily have not yet been pruned SYNOPSIS -------- +[verse] 'git lost-found' DESCRIPTION diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index ed45662cc9..51dc325748 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -8,6 +8,7 @@ git-mailinfo - Extracts patch and authorship from a single e-mail message SYNOPSIS -------- +[verse] 'git mailinfo' [-k|-b] [-u | --encoding=<encoding> | -n] [--scissors] <msg> <patch> diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index 9b2049d674..4d1b871d96 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -7,6 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program SYNOPSIS -------- +[verse] 'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...] DESCRIPTION diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index 635c66956e..d7db2a3737 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -76,12 +76,12 @@ OPTIONS EXAMPLES -------- -git merge-file README.my README README.upstream:: +`git merge-file README.my README README.upstream`:: combines the changes of README.my and README.upstream since README, tries to merge them and writes the result into README.my. -git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345:: +`git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345`:: merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels `a` and `c` instead of `tmp/a123` and `tmp/c345`. diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 6ce54673b0..e0df1b3340 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -8,6 +8,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- +[verse] 'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*) DESCRIPTION diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt index ee059def79..04e803d5d3 100644 --- a/Documentation/git-merge-one-file.txt +++ b/Documentation/git-merge-one-file.txt @@ -8,6 +8,7 @@ git-merge-one-file - The standard helper program to use with git-merge-index SYNOPSIS -------- +[verse] 'git merge-one-file' DESCRIPTION diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index 3bfa7b4220..c5f84b6495 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -8,6 +8,7 @@ git-merge-tree - Show three-way merge without touching index SYNOPSIS -------- +[verse] 'git merge-tree' <base-tree> <branch1> <branch2> DESCRIPTION diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt index 63ededec1d..f98a41b87c 100644 --- a/Documentation/git-mergetool--lib.txt +++ b/Documentation/git-mergetool--lib.txt @@ -7,7 +7,8 @@ git-mergetool--lib - Common git merge tool shell scriptlets SYNOPSIS -------- -'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool--lib"' +[verse] +'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool{litdd}lib"' DESCRIPTION ----------- diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 8c79ae8d2a..3470910109 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -7,6 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts SYNOPSIS -------- +[verse] 'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...] DESCRIPTION diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 037ab1045d..65e167a5c5 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -8,6 +8,7 @@ git-mktag - Creates a tag object SYNOPSIS -------- +[verse] 'git mktag' < signature_file DESCRIPTION diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index afe21be64d..5c6ebdfad9 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -8,6 +8,7 @@ git-mktree - Build a tree-object from ls-tree formatted text SYNOPSIS -------- +[verse] 'git mktree' [-z] [--missing] [--batch] DESCRIPTION diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index db0e030d69..b8db373964 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -8,6 +8,7 @@ git-mv - Move or rename a file, a directory, or a symlink SYNOPSIS -------- +[verse] 'git mv' <options>... <args>... DESCRIPTION diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index db9f0f7055..f2869da572 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -8,6 +8,7 @@ git-pack-redundant - Find redundant pack files SYNOPSIS -------- +[verse] 'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > DESCRIPTION diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 54b92534ce..a3c6677bfa 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -7,6 +7,7 @@ git-pack-refs - Pack heads and tags for efficient repository access SYNOPSIS -------- +[verse] 'git pack-refs' [--all] [--no-prune] DESCRIPTION diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt index 02217f6ba2..a45ea1ece8 100644 --- a/Documentation/git-parse-remote.txt +++ b/Documentation/git-parse-remote.txt @@ -8,6 +8,7 @@ git-parse-remote - Routines to help parsing remote repository access parameters SYNOPSIS -------- +[verse] '. "$(git --exec-path)/git-parse-remote"' DESCRIPTION diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 50e26f43c1..90268f02e7 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -7,6 +7,7 @@ git-patch-id - Compute unique ID for a patch SYNOPSIS -------- +[verse] 'git patch-id' < <patch> DESCRIPTION diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt index a34d62f0da..87ea3fb054 100644 --- a/Documentation/git-peek-remote.txt +++ b/Documentation/git-peek-remote.txt @@ -8,6 +8,7 @@ git-peek-remote - List the references in a remote repository SYNOPSIS -------- +[verse] 'git peek-remote' [--upload-pack=<git-upload-pack>] [<host>:]<directory> DESCRIPTION diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 9e6202cdff..80dc022ede 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -8,6 +8,7 @@ git-prune-packed - Remove extra objects that are already in pack files SYNOPSIS -------- +[verse] 'git prune-packed' [-n|--dry-run] [-q|--quiet] diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index f616a739ef..80d01b0571 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -8,6 +8,7 @@ git-prune - Prune all unreachable objects from the object database SYNOPSIS -------- +[verse] 'git prune' [-n] [-v] [--expire <expire>] [--] [<head>...] DESCRIPTION diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 14609cbd4d..e1da468766 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -8,6 +8,7 @@ git-pull - Fetch from and merge with another repository or a local branch SYNOPSIS -------- +[verse] 'git pull' [options] [<repository> [<refspec>...]] diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 88acfcd4cc..49c6e9fa51 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -327,12 +327,12 @@ a case where you do mean to lose history. Examples -------- -git push:: +`git push`:: Works like `git push <remote>`, where <remote> is the current branch's remote (or `origin`, if no remote is configured for the current branch). -git push origin:: +`git push origin`:: Without additional configuration, works like `git push origin :`. + @@ -344,45 +344,45 @@ use `git config remote.origin.push HEAD`. Any valid <refspec> (like the ones in the examples below) can be configured as the default for `git push origin`. -git push origin ::: +`git push origin :`:: Push "matching" branches to `origin`. See <refspec> in the <<OPTIONS,OPTIONS>> section above for a description of "matching" branches. -git push origin master:: +`git push origin master`:: Find a ref that matches `master` in the source repository (most likely, it would find `refs/heads/master`), and update the same ref (e.g. `refs/heads/master`) in `origin` repository with it. If `master` did not exist remotely, it would be created. -git push origin HEAD:: +`git push origin HEAD`:: A handy way to push the current branch to the same name on the remote. -git push origin master:satellite/master dev:satellite/dev:: +`git push origin master:satellite/master dev:satellite/dev`:: Use the source ref that matches `master` (e.g. `refs/heads/master`) to update the ref that matches `satellite/master` (most probably `refs/remotes/satellite/master`) in the `origin` repository, then do the same for `dev` and `satellite/dev`. -git push origin HEAD:master:: +`git push origin HEAD:master`:: Push the current branch to the remote ref matching `master` in the `origin` repository. This form is convenient to push the current branch without thinking about its local name. -git push origin master:refs/heads/experimental:: +`git push origin master:refs/heads/experimental`:: Create the branch `experimental` in the `origin` repository by copying the current `master` branch. This form is only needed to create a new branch or tag in the remote repository when the local name and the remote name are different; otherwise, the ref name on its own will work. -git push origin :experimental:: +`git push origin :experimental`:: Find a ref that matches `experimental` in the `origin` repository (e.g. `refs/heads/experimental`), and delete it. -git push origin {plus}dev:master:: +`git push origin {plus}dev:master`:: Update the origin repository's master branch with the dev branch, allowing non-fast-forward updates. *This can leave unreferenced commits dangling in the origin repository.* Consider the diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 46a96f2313..c45d53c6e1 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,6 +8,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- +[verse] 'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u [--exclude-per-directory=<gitignore>] | -i]] [--index-output=<file>] [--no-sparse-checkout] diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 9a075bc4d2..504945c691 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -12,7 +12,6 @@ SYNOPSIS [<upstream>] [<branch>] 'git rebase' [-i | --interactive] [options] --onto <newbase> --root [<branch>] - 'git rebase' --continue | --skip | --abort DESCRIPTION @@ -46,7 +45,7 @@ with a different commit message or timestamp will be skipped). It is possible that a merge failure will prevent this process from being completely automatic. You will have to resolve any such merge failure and run `git rebase --continue`. Another option is to bypass the commit -that caused the merge failure with `git rebase --skip`. To restore the +that caused the merge failure with `git rebase --skip`. To check out the original <branch> and remove the .git/rebase-apply working files, use the command `git rebase --abort` instead. @@ -233,7 +232,11 @@ leave out at most one of A and B, in which case it defaults to HEAD. Restart the rebasing process after having resolved a merge conflict. --abort:: - Restore the original branch and abort the rebase operation. + Abort the rebase operation and reset HEAD to the original + branch. If <branch> was provided when the rebase operation was + started, then HEAD will be reset to <branch>. Otherwise HEAD + will be reset to where it was when the rebase operation was + started. --skip:: Restart the rebasing process by skipping the current patch. diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index f34e0ae1bd..459c08598f 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -8,6 +8,7 @@ git-receive-pack - Receive what is pushed into the repository SYNOPSIS -------- +[verse] 'git-receive-pack' <directory> DESCRIPTION diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 09057bf90c..976dc14937 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -8,6 +8,7 @@ git-reflog - Manage reflog information SYNOPSIS -------- +[verse] 'git reflog' <subcommand> <options> DESCRIPTION diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt index 9893376487..3b33c99510 100644 --- a/Documentation/git-relink.txt +++ b/Documentation/git-relink.txt @@ -7,6 +7,7 @@ git-relink - Hardlink common objects in local repositories SYNOPSIS -------- +[verse] 'git relink' [--safe] <dir>... <master_dir> DESCRIPTION diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 68263a6a53..8a8e1d775d 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -7,6 +7,7 @@ git-remote-ext - Bridge smart transport to external command. SYNOPSIS -------- +[verse] git remote add <nick> "ext::<command>[ <arguments>...]" DESCRIPTION diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt index 4aecd4d187..f095d57d09 100644 --- a/Documentation/git-remote-fd.txt +++ b/Documentation/git-remote-fd.txt @@ -35,19 +35,19 @@ GIT_TRANSLOOP_DEBUG:: EXAMPLES -------- -git fetch fd::17 master:: +`git fetch fd::17 master`:: Fetch master, using file descriptor #17 to communicate with git-upload-pack. -git fetch fd::17/foo master:: +`git fetch fd::17/foo master`:: Same as above. -git push fd::7,8 master (as URL):: +`git push fd::7,8 master (as URL)`:: Push master, using file descriptor #7 to read data from git-receive-pack and file descriptor #8 to write data to same service. -git push fd::7,8/bar master:: +`git push fd::7,8/bar master`:: Same as above. Documentation diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 58f6ad4994..4f83dea5a3 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -7,6 +7,7 @@ git-remote-helpers - Helper programs to interact with remote repositories SYNOPSIS -------- +[verse] 'git remote-<transport>' <repository> [<URL>] DESCRIPTION @@ -47,6 +48,9 @@ arguments. The first argument specifies a remote repository as in git; it is either the name of a configured remote or a URL. The second argument specifies a URL; it is usually of the form '<transport>://<address>', but any arbitrary string is possible. +The 'GIT_DIR' environment variable is set up for the remote helper +and can be used to determine where to store additional data or from +which directory to invoke auxiliary git commands. When git encounters a URL of the form '<transport>://<address>', where '<transport>' is a protocol that it cannot handle natively, it diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 528f34a131..5a8c5061f3 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -60,11 +60,11 @@ the remote repository. + With `-t <branch>` option, instead of the default glob refspec for the remote to track all branches under -`$GIT_DIR/remotes/<name>/`, a refspec to track only `<branch>` +the `refs/remotes/<name>/` namespace, a refspec to track only `<branch>` is created. You can give more than one `-t <branch>` to track multiple branches without grabbing all branches. + -With `-m <master>` option, `$GIT_DIR/remotes/<name>/HEAD` is set +With `-m <master>` option, a symbolic-ref `refs/remotes/<name>/HEAD` is set up to point at remote's `<master>` branch. See also the set-head command. + When a fetch mirror is created with `\--mirror=fetch`, the refs will not @@ -92,24 +92,25 @@ configuration settings for the remote are removed. 'set-head':: -Sets or deletes the default branch (`$GIT_DIR/remotes/<name>/HEAD`) for +Sets or deletes the default branch (i.e. the target of the +symbolic-ref `refs/remotes/<name>/HEAD`) for the named remote. Having a default branch for a remote is not required, but allows the name of the remote to be specified in lieu of a specific branch. For example, if the default branch for `origin` is set to `master`, then `origin` may be specified wherever you would normally specify `origin/master`. + -With `-d`, `$GIT_DIR/remotes/<name>/HEAD` is deleted. +With `-d`, the symbolic ref `refs/remotes/<name>/HEAD` is deleted. + -With `-a`, the remote is queried to determine its `HEAD`, then -`$GIT_DIR/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote +With `-a`, the remote is queried to determine its `HEAD`, then the +symbolic-ref `refs/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote `HEAD` is pointed at `next`, "`git remote set-head origin -a`" will set -`$GIT_DIR/refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will +the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will only work if `refs/remotes/origin/next` already exists; if not it must be fetched first. + -Use `<branch>` to set `$GIT_DIR/remotes/<name>/HEAD` explicitly. e.g., "git -remote set-head origin master" will set `$GIT_DIR/refs/remotes/origin/HEAD` to +Use `<branch>` to set the symbolic-ref `refs/remotes/<name>/HEAD` explicitly. e.g., "git +remote set-head origin master" will set the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/master`. This will only work if `refs/remotes/origin/master` already exists; if not it must be fetched first. + diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 0decee240b..40af321153 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -8,6 +8,7 @@ git-repack - Pack unpacked objects in a repository SYNOPSIS -------- +[verse] 'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>] DESCRIPTION diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index a0d1fa6594..9ec115b9e0 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -8,6 +8,7 @@ git-repo-config - Get and set repository or global options SYNOPSIS -------- +[verse] 'git repo-config' ... diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 3521d8e3c8..b99681ce85 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -7,6 +7,7 @@ git-request-pull - Generates a summary of pending changes SYNOPSIS -------- +[verse] 'git request-pull' [-p] <start> <url> [<end>] DESCRIPTION diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 52db1d80cf..a6253ba617 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -7,6 +7,7 @@ git-rerere - Reuse recorded resolution of conflicted merges SYNOPSIS -------- +[verse] 'git rerere' ['clear'|'forget' <pathspec>|'diff'|'status'|'gc'] DESCRIPTION diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 02c44c999f..42c9676eaa 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -8,6 +8,7 @@ git-rev-parse - Pick out and massage parameters SYNOPSIS -------- +[verse] 'git rev-parse' [ --option ] <args>... DESCRIPTION diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index ac10cfbb14..b311d59c7c 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -7,6 +7,7 @@ git-revert - Revert some existing commits SYNOPSIS -------- +[verse] 'git revert' [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit>... DESCRIPTION @@ -23,7 +24,7 @@ throw away all uncommitted changes in your working directory, you should see linkgit:git-reset[1], particularly the '--hard' option. If you want to extract specific files as they were in another commit, you should see linkgit:git-checkout[1], specifically the `git checkout -<commit> -- <filename>` syntax. Take care with these alternatives as +<commit> \-- <filename>` syntax. Take care with these alternatives as both will discard uncommitted changes in your working directory. OPTIONS @@ -92,12 +93,12 @@ effect to your index in a row. EXAMPLES -------- -git revert HEAD~3:: +`git revert HEAD~3`:: Revert the changes specified by the fourth last commit in HEAD and create a new commit with the reverted changes. -git revert -n master{tilde}5..master{tilde}2:: +`git revert -n master{tilde}5..master{tilde}2`:: Revert the changes done by commits from the fifth last commit in master (included) to the third last commit in master diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 8c0554f971..665ad4ddab 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -7,6 +7,7 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- +[verse] 'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>... DESCRIPTION @@ -136,7 +137,7 @@ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached EXAMPLES -------- -git rm Documentation/\*.txt:: +`git rm Documentation/\*.txt`:: Removes all `*.txt` files from the index that are under the `Documentation` directory and any of its subdirectories. + @@ -144,7 +145,7 @@ Note that the asterisk `*` is quoted from the shell in this example; this lets git, and not the shell, expand the pathnames of files and subdirectories under the `Documentation/` directory. -git rm -f git-*.sh:: +`git rm -f git-*.sh`:: Because this example lets the shell expand the asterisk (i.e. you are listing the files explicitly), it does not remove `subdir/git-foo.sh`. diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 5a168cfab2..327233c85b 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -8,6 +8,7 @@ git-send-email - Send a collection of patches as emails SYNOPSIS -------- +[verse] 'git send-email' [options] <file|directory|rev-list options>... diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 17f8f55526..bd3eaa69bf 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -8,6 +8,7 @@ git-send-pack - Push objects over git protocol to another repository SYNOPSIS -------- +[verse] 'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] DESCRIPTION diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.txt index 61e4c08dac..5c3ec327bb 100644 --- a/Documentation/git-sh-i18n--envsubst.txt +++ b/Documentation/git-sh-i18n--envsubst.txt @@ -1,5 +1,5 @@ -git-sh-i18n--envsubst(1) -======================== +git-sh-i18n{litdd}envsubst(1) +============================= NAME ---- @@ -10,8 +10,8 @@ SYNOPSIS [verse] eval_gettext () { printf "%s" "$1" | ( - export PATH $('git sh-i18n--envsubst' --variables "$1"); - 'git sh-i18n--envsubst' "$1" + export PATH $('git sh-i18n{litdd}envsubst' --variables "$1"); + 'git sh-i18n{litdd}envsubst' "$1" ) } @@ -22,7 +22,7 @@ This is not a command the end user would want to run. Ever. This documentation is meant for people who are studying the plumbing scripts and/or are writing new ones. -git-sh-i18n--envsubst is Git's stripped-down copy of the GNU +'git sh-i18n{litdd}envsubst' is Git's stripped-down copy of the GNU `envsubst(1)` program that comes with the GNU gettext package. It's used internally by linkgit:git-sh-i18n[1] to interpolate the variables passed to the the `eval_gettext` function. diff --git a/Documentation/git-sh-i18n.txt b/Documentation/git-sh-i18n.txt index 3b1f7ac7b5..60cf49cb2a 100644 --- a/Documentation/git-sh-i18n.txt +++ b/Documentation/git-sh-i18n.txt @@ -7,6 +7,7 @@ git-sh-i18n - Git's i18n setup code for shell scripts SYNOPSIS -------- +[verse] '. "$(git --exec-path)/git-sh-i18n"' DESCRIPTION @@ -34,7 +35,7 @@ gettext:: eval_gettext:: Currently a dummy fall-through function implemented as a wrapper around `printf(1)` with variables expanded by the - linkgit:git-sh-i18n--envsubst[1] helper. Will be replaced by a + linkgit:git-sh-i18n{litdd}envsubst[1] helper. Will be replaced by a real gettext implementation in a later version. GIT diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 27fd8ba854..a2f346ca71 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -7,6 +7,7 @@ git-sh-setup - Common git shell script setup code SYNOPSIS -------- +[verse] '. "$(git --exec-path)/git-sh-setup"' DESCRIPTION diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index d7d4b92894..9b9250600f 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -8,6 +8,7 @@ git-shell - Restricted login shell for Git-only SSH access SYNOPSIS -------- +[verse] 'git shell' [-c <command> <argument>] DESCRIPTION diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index ee4559b6f2..a8e77b5350 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -13,7 +13,6 @@ SYNOPSIS [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...] - 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] DESCRIPTION diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index c4d99f1028..2dcbbb2454 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -8,6 +8,7 @@ git-show-index - Show packed archive index SYNOPSIS -------- +[verse] 'git show-index' < idx-file diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 7f075e84f5..1e38819e67 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -8,6 +8,7 @@ git-show - Show various types of objects SYNOPSIS -------- +[verse] 'git show' [options] <object>... DESCRIPTION @@ -47,23 +48,23 @@ include::pretty-formats.txt[] EXAMPLES -------- -git show v1.0.0:: +`git show v1.0.0`:: Shows the tag `v1.0.0`, along with the object the tags points at. -git show v1.0.0^\{tree\}:: +`git show v1.0.0^\{tree\}`:: Shows the tree pointed to by the tag `v1.0.0`. -git show -s --format=%s v1.0.0^\{commit\}:: +`git show -s --format=%s v1.0.0^\{commit\}`:: Shows the subject of the commit pointed to by the tag `v1.0.0`. -git show next~10:Documentation/README:: +`git show next~10:Documentation/README`:: Shows the contents of the file `Documentation/README` as they were current in the 10th last commit of the branch `next`. -git show master:Makefile master:t/Makefile:: +`git show master:Makefile master:t/Makefile`:: Concatenates the contents of said Makefiles in the head of the branch `master`. diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 15f051fa44..43af38aa4b 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -13,7 +13,8 @@ SYNOPSIS 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] [<message>]] +'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] + [-u|--include-untracked] [-a|--all] [<message>]] 'git stash' clear 'git stash' create @@ -42,7 +43,7 @@ is also possible). OPTIONS ------- -save [-p|--patch] [--[no-]keep-index] [-q|--quiet] [<message>]:: +save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: Save your local modifications to a new 'stash', and run `git reset --hard` to revert them. The <message> part is optional and gives @@ -54,6 +55,11 @@ save [-p|--patch] [--[no-]keep-index] [-q|--quiet] [<message>]:: If the `--keep-index` option is used, all changes already added to the index are left intact. + +If the `--include-untracked` option is used, all untracked files are also +stashed and then cleaned up with `git clean`, leaving the working directory +in a very clean state. If the `--all` option is used instead then the +ignored files are stashed and cleaned in addition to the untracked files. ++ With `--patch`, you can interactively select hunks from the diff between HEAD and the working tree to be stashed. The stash entry is constructed such that its index state is the same as the index state diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 38cb741f18..3d51717bbe 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -8,6 +8,7 @@ git-status - Show the working tree status SYNOPSIS -------- +[verse] 'git status' [<options>...] [--] [<pathspec>...] DESCRIPTION @@ -69,6 +70,9 @@ configuration variable documented in linkgit:git-config[1]. (and suppresses the output of submodule summaries when the config option `status.submodulesummary` is set). +--ignored:: + Show ignored files as well. + -z:: Terminate entries with NUL, instead of LF. This implies the `--porcelain` output format if no other format is given. @@ -119,7 +123,8 @@ codes can be interpreted as follows: * 'C' = copied * 'U' = updated but unmerged -Ignored files are not listed. +Ignored files are not listed, unless `--ignored` option is in effect, +in which case `XY` are `!!`. X Y Meaning ------------------------------------------------- @@ -142,6 +147,7 @@ Ignored files are not listed. U U unmerged, both modified ------------------------------------------------- ? ? untracked + ! ! ignored ------------------------------------------------- If -b is used the short-format status is preceded by a line diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 10509cc450..b78f031cd4 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -8,6 +8,7 @@ git-stripspace - Filter out empty lines SYNOPSIS -------- +[verse] 'git stripspace' [-s | --strip-comments] < <stream> DESCRIPTION diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 5e7a4130ee..0ec85742dd 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -78,7 +78,9 @@ to exist in the superproject. If <path> is not given, the <repository> is the URL of the new submodule's origin repository. This may be either an absolute URL, or (if it begins with ./ or ../), the location relative to the superproject's origin -repository. +repository. If the superproject doesn't have an origin configured +the superproject is its own authoritative upstream and the current +working directory is used instead. + <path> is the relative location for the cloned submodule to exist in the superproject. If <path> does not exist, then the @@ -167,12 +169,14 @@ commit for each submodule. sync:: Synchronizes submodules' remote URL configuration setting - to the value specified in .gitmodules. This is useful when + to the value specified in .gitmodules. It will only affect those + submodules which already have an url entry in .git/config (that is the + case when they are initialized or freshly added). This is useful when submodule URLs change upstream and you need to update your local repositories accordingly. + "git submodule sync" synchronizes all submodules while -"git submodule sync -- A" synchronizes submodule "A" only. +"git submodule sync \-- A" synchronizes submodule "A" only. OPTIONS ------- diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 713e523034..ed5eca1fce 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -7,6 +7,7 @@ git-svn - Bidirectional operation between a Subversion repository and git SYNOPSIS -------- +[verse] 'git svn' <command> [options] [arguments] DESCRIPTION diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index d7795ed657..75b1ae5061 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -7,6 +7,7 @@ git-symbolic-ref - Read and modify symbolic refs SYNOPSIS -------- +[verse] 'git symbolic-ref' [-q] [-m <reason>] <name> [<ref>] DESCRIPTION diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index d82f62120a..fb1c0ac694 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... -'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>] +'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION @@ -69,8 +69,11 @@ OPTIONS If the tag is not annotated, the commit message is displayed instead. -l <pattern>:: - List tags with names that match the given pattern (or all if no pattern is given). - Typing "git tag" without arguments, also lists all tags. + List tags with names that match the given pattern (or all if no + pattern is given). Running "git tag" without arguments also + lists all tags. The pattern is a shell wildcard (i.e., matched + using fnmatch(3)). Multiple patterns may be given; if any of + them matches, the tag is shown. --contains <commit>:: Only list tags which contain the specified commit. diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 5f15754257..346e7a2079 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -8,6 +8,7 @@ git-tar-tree - Create a tar archive of the files in the named tree object SYNOPSIS -------- +[verse] 'git tar-tree' [--remote=<repo>] <tree-ish> [ <base> ] DESCRIPTION @@ -52,26 +53,26 @@ tar.umask:: EXAMPLES -------- -git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -):: +`git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -)`:: Create a tar archive that contains the contents of the latest commit on the current branch, and extracts it in `/var/tmp/junk` directory. -git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz:: +`git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a tarball for v1.4.0 release. -git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz:: +`git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz`:: Create a tarball for v1.4.0 release, but without a global extended pax header. -git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar:: +`git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar`:: Get a tarball v1.4.0 from example.com. -git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar:: +`git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar`:: Put everything in the current head's Documentation/ directory into 'git-1.4.0-docs.tar', with the prefix 'git-docs/'. diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.txt index c49d727f74..e9f148a00d 100644 --- a/Documentation/git-unpack-file.txt +++ b/Documentation/git-unpack-file.txt @@ -9,6 +9,7 @@ git-unpack-file - Creates a temporary file with a blob's contents SYNOPSIS -------- +[verse] 'git unpack-file' <blob> DESCRIPTION diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index dd7799095b..ff23494e70 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -8,6 +8,7 @@ git-unpack-objects - Unpack objects from a packed archive SYNOPSIS -------- +[verse] 'git unpack-objects' [-n] [-q] [-r] [--strict] <pack-file diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index e25a65a80f..d377a35243 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -7,6 +7,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- +[verse] 'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>]) DESCRIPTION @@ -60,8 +61,9 @@ still contains <oldvalue>. Logging Updates --------------- -If config parameter "core.logAllRefUpdates" is true or the file -"$GIT_DIR/logs/<ref>" exists then `git update-ref` will append +If config parameter "core.logAllRefUpdates" is true and the ref is one under +"refs/heads/", "refs/remotes/", "refs/notes/", or the symbolic ref HEAD; or +the file "$GIT_DIR/logs/<ref>" exists then `git update-ref` will append a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating the log name) describing the change in ref value. Log lines are formatted as: diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 775024da3e..bd0e36492f 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -8,6 +8,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers SYNOPSIS -------- +[verse] 'git update-server-info' [--force] DESCRIPTION diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt index acbf634f85..4d52d3833a 100644 --- a/Documentation/git-upload-archive.txt +++ b/Documentation/git-upload-archive.txt @@ -8,6 +8,7 @@ git-upload-archive - Send archive back to git-archive SYNOPSIS -------- +[verse] 'git upload-archive' <directory> DESCRIPTION diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 4c0ca9ded2..a58e90ca8d 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -8,6 +8,7 @@ git-upload-pack - Send objects packed back to git-fetch-pack SYNOPSIS -------- +[verse] 'git-upload-pack' [--strict] [--timeout=<n>] <directory> DESCRIPTION diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 6498f7cb69..5317cc2474 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -8,6 +8,7 @@ git-var - Show a git logical variable SYNOPSIS -------- +[verse] 'git var' ( -l | <variable> ) DESCRIPTION diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 7c2428d569..cd230769fd 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -8,6 +8,7 @@ git-verify-pack - Validate packed git archive files SYNOPSIS -------- +[verse] 'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ... diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index 8c9a71865b..5ff76e892a 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -7,6 +7,7 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- +[verse] 'git verify-tag' <tag>... DESCRIPTION diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 69d92fa00e..c2bc87bc61 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -7,6 +7,7 @@ git-web--browse - git helper script to launch a web browser SYNOPSIS -------- +[verse] 'git web{litdd}browse' [OPTIONS] URL/FILE ... DESCRIPTION @@ -68,7 +69,7 @@ browser.<tool>.path You can explicitly provide a full path to your preferred browser by setting the configuration variable 'browser.<tool>.path'. For example, you can configure the absolute path to firefox by setting -'browser.firefox.path'. Otherwise, 'git web--browse' assumes the tool +'browser.firefox.path'. Otherwise, 'git web{litdd}browse' assumes the tool is available in PATH. browser.<tool>.cmd diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 31f3663ae7..76c7f7eec5 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -8,6 +8,7 @@ git-whatchanged - Show logs with difference each commit introduces SYNOPSIS -------- +[verse] 'git whatchanged' <option>... DESCRIPTION @@ -52,12 +53,12 @@ include::pretty-formats.txt[] Examples -------- -git whatchanged -p v2.6.12.. include/scsi drivers/scsi:: +`git whatchanged -p v2.6.12.. include/scsi drivers/scsi`:: Show as patches the commits since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories -git whatchanged --since="2 weeks ago" \-- gitk:: +`git whatchanged --since="2 weeks ago" \-- gitk`:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index e8c94c1352..f22041a9dc 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -8,6 +8,7 @@ git-write-tree - Create a tree object from the current index SYNOPSIS -------- +[verse] 'git write-tree' [--missing-ok] [--prefix=<prefix>/] DESCRIPTION diff --git a/Documentation/git.txt b/Documentation/git.txt index 3c7a832343..0172cd7014 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -523,16 +523,15 @@ Any git command accepting any <object> can also use the following symbolic notation: HEAD:: - indicates the head of the current branch (i.e. the - contents of `$GIT_DIR/HEAD`). + indicates the head of the current branch. <tag>:: a valid tag 'name' - (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). + (i.e. a `refs/tags/<tag>` reference). <head>:: a valid head 'name' - (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). + (i.e. a `refs/heads/<head>` reference). For a more complete list of ways to spell object names, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 412c55b549..2bbe76b5d8 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -79,7 +79,7 @@ Attributes for all users on a system should be placed in the `$(prefix)/etc/gitattributes` file. Sometimes you would need to override an setting of an attribute -for a path to `unspecified` state. This can be done by listing +for a path to `Unspecified` state. This can be done by listing the name of the attribute prefixed with an exclamation point `!`. @@ -868,7 +868,7 @@ If this attribute is not set or has an invalid value, the value of the (See linkgit:git-config[1]). -USING ATTRIBUTE MACROS +USING MACRO ATTRIBUTES ---------------------- You do not want any end-of-line conversions applied to, nor textual diffs @@ -879,24 +879,27 @@ produced for, any binary file you track. You would need to specify e.g. ------------ but that may become cumbersome, when you have many attributes. Using -attribute macros, you can specify groups of attributes set or unset at -the same time. The system knows a built-in attribute macro, `binary`: +macro attributes, you can define an attribute that, when set, also +sets or unsets a number of other attributes at the same time. The +system knows a built-in macro attribute, `binary`: ------------ *.jpg binary ------------ -which is equivalent to the above. Note that the attribute macros can only -be "Set" (see the above example that sets "binary" macro as if it were an -ordinary attribute --- setting it in turn unsets "text" and "diff"). +Setting the "binary" attribute also unsets the "text" and "diff" +attributes as above. Note that macro attributes can only be "Set", +though setting one might have the effect of setting or unsetting other +attributes or even returning other attributes to the "Unspecified" +state. -DEFINING ATTRIBUTE MACROS +DEFINING MACRO ATTRIBUTES ------------------------- -Custom attribute macros can be defined only in the `.gitattributes` file -at the toplevel (i.e. not in any subdirectory). The built-in attribute -macro "binary" is equivalent to: +Custom macro attributes can be defined only in the `.gitattributes` +file at the toplevel (i.e. not in any subdirectory). The built-in +macro attribute "binary" is equivalent to: ------------ [attr]binary -diff -text diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt index d861ec452f..aeb0cdc973 100644 --- a/Documentation/gitcvs-migration.txt +++ b/Documentation/gitcvs-migration.txt @@ -7,7 +7,8 @@ gitcvs-migration - git for CVS users SYNOPSIS -------- -git cvsimport * +[verse] +'git cvsimport' * DESCRIPTION ----------- diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 6af29a4603..370624c171 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -7,6 +7,7 @@ gitdiffcore - Tweaking diff output SYNOPSIS -------- +[verse] 'git diff' * DESCRIPTION diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index e10ac58cae..a17a354936 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -7,6 +7,7 @@ gitk - The git repository browser SYNOPSIS -------- +[verse] 'gitk' [<option>...] [<revs>] [--] [<path>...] DESCRIPTION diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index 7fe5848d1f..f1e4422acc 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -7,6 +7,7 @@ gittutorial-2 - A tutorial introduction to git: part two SYNOPSIS -------- +[verse] git * DESCRIPTION diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 0982f74ef6..dee050567e 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -7,6 +7,7 @@ gittutorial - A tutorial introduction to git (for version 1.5.1 or newer) SYNOPSIS -------- +[verse] git * DESCRIPTION diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index 1ef55fffcf..5e4f362ff8 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -7,6 +7,7 @@ gitworkflows - An overview of recommended workflows with git SYNOPSIS -------- +[verse] git * diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 8f62d1abee..3595b586bc 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -161,8 +161,8 @@ to point at the new commit. [[def_head]]head:: A <<def_ref,named reference>> to the <<def_commit,commit>> at the tip of a - <<def_branch,branch>>. Heads are stored in - `$GIT_DIR/refs/heads/`, except when using packed refs. (See + <<def_branch,branch>>. Heads are stored in a file in + `$GIT_DIR/refs/heads/` directory, except when using packed refs. (See linkgit:git-pack-refs[1].) [[def_HEAD]]HEAD:: @@ -170,8 +170,8 @@ to point at the new commit. working tree>> is normally derived from the state of the tree referred to by HEAD. HEAD is a reference to one of the <<def_head,heads>> in your repository, except when using a - <<def_detached_HEAD,detached HEAD>>, in which case it may - reference an arbitrary commit. + <<def_detached_HEAD,detached HEAD>>, in which case it directly + references an arbitrary commit. [[def_head_ref]]head ref:: A synonym for <<def_head,head>>. @@ -382,8 +382,9 @@ should not be combined with other pathspec. [[def_ref]]ref:: A 40-byte hex representation of a <<def_SHA1,SHA1>> or a name that - denotes a particular <<def_object,object>>. These may be stored in - `$GIT_DIR/refs/`. + denotes a particular <<def_object,object>>. They may be stored in + a file under `$GIT_DIR/refs/` directory, or + in the `$GIT_DIR/packed-refs` file. [[def_reflog]]reflog:: A reflog shows the local "history" of a ref. In other words, @@ -459,14 +460,14 @@ should not be combined with other pathspec. command. [[def_tag]]tag:: - A <<def_ref,ref>> pointing to a <<def_tag_object,tag>> or - <<def_commit_object,commit object>>. In contrast to a <<def_head,head>>, - a tag is not changed by a <<def_commit,commit>>. Tags (not - <<def_tag_object,tag objects>>) are stored in `$GIT_DIR/refs/tags/`. A - git tag has nothing to do with a Lisp tag (which would be - called an <<def_object_type,object type>> in git's context). A - tag is most typically used to mark a particular point in the - commit ancestry <<def_chain,chain>>. + A <<def_ref,ref>> under `refs/tags/` namespace that points to an + object of an arbitrary type (typically a tag points to either a + <<def_tag_object,tag>> or a <<def_commit_object,commit object>>). + In contrast to a <<def_head,head>>, a tag is not updated by + the `commit` command. A git tag has nothing to do with a Lisp + tag (which would be called an <<def_object_type,object type>> + in git's context). A tag is most typically used to mark a particular + point in the commit ancestry <<def_chain,chain>>. [[def_tag_object]]tag object:: An <<def_object,object>> containing a <<def_ref,ref>> pointing to diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 7e7ba68781..39e6207269 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -272,7 +272,7 @@ Default mode:: --full-history:: - As the default mode but does not prune some history. + Same as the default mode, but does not prune some history. --dense:: @@ -313,7 +313,7 @@ that you are filtering for a file `foo` in this commit graph: \ / / / / `-------------' ----------------------------------------------------------------------- -The horizontal line of history A--P is taken to be the first parent of +The horizontal line of history A---P is taken to be the first parent of each merge. The commits are: * `I` is the initial commit, in which `foo` exists with contents diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index 5cb2b0590a..b0cafe87be 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -49,6 +49,8 @@ Additionally, if `foo` is a new command, there are 3 more things to do: . Add an entry for `git-foo` to `command-list.txt`. +. Add an entry for `/git-foo` to `.gitignore`. + How a built-in is called ------------------------ diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 7b233ca196..8930b3fabc 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -147,8 +147,9 @@ GIT index format - 160-bit object name for the object that would result from writing this span of index as a tree. - An entry can be in an invalidated state and is represented by having -1 - in the entry_count field. + An entry can be in an invalidated state and is represented by having + -1 in the entry_count field. In this case, there is no object name + and the next entry starts immediately after the newline. The entries are written out in the top-down, depth-first order. The first entry represents the root level of the repository, followed by the diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 369f91d3b9..a7004c63e7 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -179,34 +179,36 @@ and descriptions. Packfile Negotiation -------------------- -After reference and capabilities discovery, the client can decide -to terminate the connection by sending a flush-pkt, telling the -server it can now gracefully terminate (as happens with the ls-remote -command) or it can enter the negotiation phase, where the client and -server determine what the minimal packfile necessary for transport is. - -Once the client has the initial list of references that the server -has, as well as the list of capabilities, it will begin telling the -server what objects it wants and what objects it has, so the server -can make a packfile that only contains the objects that the client needs. -The client will also send a list of the capabilities it wants to be in -effect, out of what the server said it could do with the first 'want' line. +After reference and capabilities discovery, the client can decide to +terminate the connection by sending a flush-pkt, telling the server it can +now gracefully terminate, and disconnect, when it does not need any pack +data. This can happen with the ls-remote command, and also can happen when +the client already is up-to-date. + +Otherwise, it enters the negotiation phase, where the client and +server determine what the minimal packfile necessary for transport is, +by telling the server what objects it wants, its shallow objects +(if any), and the maximum commit depth it wants (if any). The client +will also send a list of the capabilities it wants to be in effect, +out of what the server said it could do with the first 'want' line. ---- upload-request = want-list - have-list - compute-end + *shallow-line + *1depth-request + flush-pkt want-list = first-want *additional-want - flush-pkt + + shallow-line = PKT_LINE("shallow" SP obj-id) + + depth-request = PKT_LINE("deepen" SP depth) first-want = PKT-LINE("want" SP obj-id SP capability-list LF) additional-want = PKT-LINE("want" SP obj-id LF) - have-list = *have-line - have-line = PKT-LINE("have" SP obj-id LF) - compute-end = flush-pkt / PKT-LINE("done") + depth = 1*DIGIT ---- Clients MUST send all the obj-ids it wants from the reference @@ -215,21 +217,64 @@ discovery phase as 'want' lines. Clients MUST send at least one obj-id in a 'want' command which did not appear in the response obtained through ref discovery. -If client is requesting a shallow clone, it will now send a 'deepen' -line with the depth it is requesting. +The client MUST write all obj-ids which it only has shallow copies +of (meaning that it does not have the parents of a commit) as +'shallow' lines so that the server is aware of the limitations of +the client's history. Clients MUST NOT mention an obj-id which +it does not know exists on the server. + +The client now sends the maximum commit history depth it wants for +this transaction, which is the number of commits it wants from the +tip of the history, if any, as a 'deepen' line. A depth of 0 is the +same as not making a depth request. The client does not want to receive +any commits beyond this depth, nor objects needed only to complete +those commits. Commits whose parents are not received as a result are +defined as shallow and marked as such in the server. This information +is sent back to the client in the next step. + +Once all the 'want's and 'shallow's (and optional 'deepen') are +transferred, clients MUST send a flush-pkt, to tell the server side +that it is done sending the list. + +Otherwise, if the client sent a positive depth request, the server +will determine which commits will and will not be shallow and +send this information to the client. If the client did not request +a positive depth, this step is skipped. -Once all the "want"s (and optional 'deepen') are transferred, -clients MUST send a flush-pkt. If the client has all the references -on the server, client flushes and disconnects. +---- + shallow-update = *shallow-line + *unshallow-line + flush-pkt -TODO: shallow/unshallow response and document the deepen command in the ABNF. + shallow-line = PKT-LINE("shallow" SP obj-id) + + unshallow-line = PKT-LINE("unshallow" SP obj-id) +---- + +If the client has requested a positive depth, the server will compute +the set of commits which are no deeper than the desired depth, starting +at the client's wants. The server writes 'shallow' lines for each +commit whose parents will not be sent as a result. The server writes +an 'unshallow' line for each commit which the client has indicated is +shallow, but is no longer shallow at the currently requested depth +(that is, its parents will now be sent). The server MUST NOT mark +as unshallow anything which the client has not indicated was shallow. Now the client will send a list of the obj-ids it has using 'have' -lines. In multi_ack mode, the canonical implementation will send up -to 32 of these at a time, then will send a flush-pkt. The canonical -implementation will skip ahead and send the next 32 immediately, -so that there is always a block of 32 "in-flight on the wire" at a -time. +lines, so the server can make a packfile that only contains the objects +that the client needs. In multi_ack mode, the canonical implementation +will send up to 32 of these at a time, then will send a flush-pkt. The +canonical implementation will skip ahead and send the next 32 immediately, +so that there is always a block of 32 "in-flight on the wire" at a time. + +---- + upload-haves = have-list + compute-end + + have-list = *have-line + have-line = PKT-LINE("have" SP obj-id LF) + compute-end = flush-pkt / PKT-LINE("done") +---- If the server reads 'have' lines, it then will respond by ACKing any of the obj-ids the client said it had that the server also has. The |