diff options
Diffstat (limited to 'Documentation')
28 files changed, 362 insertions, 66 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 45577117c2..57da6aadeb 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -76,11 +76,19 @@ For shell scripts specifically (not exhaustive): - We do not use Process Substitution <(list) or >(list). + - Do not write control structures on a single line with semicolon. + "then" should be on the next line for if statements, and "do" + should be on the next line for "while" and "for". + - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell functions. + - We prefer a space between the function name and the parentheses. The + opening "{" should also be on the same line. + E.g.: my_function () { + - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, [::], [==], nor [..]) for portability. diff --git a/Documentation/Makefile b/Documentation/Makefile index 063fa696c9..cf5916fe8b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -344,4 +344,7 @@ require-htmlrepo:: quick-install-html: require-htmlrepo '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) +print-man1: + @for i in $(MAN1_TXT); do echo $$i; done + .PHONY: FORCE diff --git a/Documentation/RelNotes/1.7.11.6.txt b/Documentation/RelNotes/1.7.11.6.txt new file mode 100644 index 0000000000..e548a59824 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.6.txt @@ -0,0 +1,34 @@ +Git v1.7.11.6 Release Notes +=========================== + +Fixes since v1.7.11.5 +--------------------- + +This is primarily documentation and low-impact code clarification. + + - "ciabot" script (in contrib/) has been updated with extensive + documentation. + + - The "--rebase" option to "git pull" can be abbreviated to "-r", + but we didn't document it. + + - It was generally understood that "--long-option"s to many of our + subcommands can be abbreviated to the unique prefix, but it was not + easy to find it described for new readers of the documentation set. + + - The "--topo-order", "--date-order" (and the lack of either means + the default order) options to "rev-list" and "log" family of + commands were poorly described in the documentation. + + - Older parts of the documentation described as if having a regular + file in .git/refs/ hierarchy were the only way to have branches and + tags, which is not true for quite some time. + + - A utility shell function test_seq has been added as a replacement + for the 'seq' utility found on some platforms. + + - Fallback 'getpass' implementation made unportable use of stdio API. + + - "git commit --amend" let the user edit the log message and then + died when the human-readable committer name was given + insufficiently by getpwent(3). diff --git a/Documentation/RelNotes/1.8.0.txt b/Documentation/RelNotes/1.8.0.txt new file mode 100644 index 0000000000..b626a9a059 --- /dev/null +++ b/Documentation/RelNotes/1.8.0.txt @@ -0,0 +1,155 @@ +Git v1.8.0 Release Notes +======================== + +Backward compatibility notes +---------------------------- + +In the next major release, we will change the behaviour of the "git +push" command. When "git push [$there]" does not say what to push, we +have used the traditional "matching" semantics (all your branches were +sent to the remote as long as there already are branches of the same +name over there). We will use the "simple" semantics, that pushes the +current branch to the branch with the same name only when the current +branch is set to integrate with that remote branch. There is a user +preference configuration variable "push.default" to change this, and +"git push" will warn about the upcoming change until you set this +variable. + + +Updates since v1.7.12 +--------------------- + +UI, Workflows & Features + + * A credential helper for Win32 to allow access to the keychain of + the logged-in user has been added. + + * "git cherry-pick" learned the "--allow-empty-message" option to + allow it to replay a commit without any log message. + + * "git daemon" learned the "--access-hook" option to allow an + external command to decline service based on the client address, + repository path, etc. + + * "git difftool --dir-diff" learned to use symbolic links to prepare + temporary copy of the working tree when available. + + * "git grep" learned to use a non-standard pattern type by default if + a configuration variable tells it to. + +Foreign Interface + + * "git svn" has been updated to work with SVN 1.7. + +Performance, Internal Implementation, etc. (please report possible regressions) + + * The "check-docs" build target has been updated and greatly + simplified. + + * The documentation in the TeXinfo format was using indented output + for materials meant to be examples that are better typeset in + monospace. + + * Compatibility wrapper to learn the maximum number of file + descriptors we can open around sysconf(_SC_OPEN_MAX) and + getrlimit(RLIMIT_NO_FILE) has been introduced for portability. + + * Compatibility wrapper around some mkdir(2) implementations that + reject parameter with trailing slash has been introduced. + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.12 +------------------- + +Unless otherwise noted, all the fixes since v1.7.12 in the +maintenance track are contained in this release (see release notes +to them for details). + + * The exit status code from "git config" was way overspecified while + being incorrect. The implementation has been updated to give the + documented status for a case that was documented, and introduce a + new code for "all other errors". + (merge 9409c7a jc/maint-config-exit-status later to maint). + + * "git foo" errored out with "Not a directory" when the user had a + non-directory on $PATH, and worse yet it masked an alias "foo" from + running. (merge a785508 jc/maint-sane-execvp-notdir later to + maint). + + * The interactive prompt "git send-email" gives was error prone. It + asked "What e-mail address do you want to use?" with the address it + guessed (correctly) the user would want to use in its prompt, + tempting the user to say "y". But the response was taken as "No, + please use 'y' as the e-mail address instead", which is most + certainly not what the user meant. + (merge 51bbccf jc/send-email-reconfirm later to maint). + + * "git stash apply/pop" did not trigger "rerere" upon conflicts + unlike other mergy operations. + (merge 743bf6d ph/stash-rerere later to maint). + + * "git submodule update -f" did not update paths in the working tree + that has local changes. + (merge 01d4721 sz/submodule-force-update later to maint). + + * We used curl_easy_strerror() without checking version of cURL, + breaking the build for versions before curl 7.12.0. + (merge 4246b0b js/no-curl-easy-strerror-on-old-curl later to maint). + + * Code to work around MacOS X UTF-8 gotcha has been cleaned up. + (merge 9a27f96 rr/precompose-utf8-cleanup later to maint). + + * Documentation for the configuration file format had a confusing + example. + (merge d1e1fe7 mh/maint-config-doc-proxy-command later to maint). + + * "git submodule <cmd> path" did not error out when the path to the + submodule was misspelt. + (merge be9d0a3 hv/submodule-path-unmatch later to maint). + + * Some capabilities were asked by fetch-pack even when upload-pack + did not advertise that they are available. fetch-pack has been + fixed not to do so. + + * The reflog entries left by "git rebase" and "git rebase -i" were + inconsistent (the interactive one gave an abbreviated object name). + (merge 1af221e mg/rebase-i-onto-reflog-in-full later to maint). + + * When the user exports a non-default IFS without HT, scripts that + rely on being able to parse "ls-files -s | while read a b c..." + start to fail. Protect them from such a misconfiguration. + (merge 785063e jc/maint-protect-sh-from-ifs later to maint). + + * "git prune" without "-v" used to warn about leftover temporary + files (which is an indication of an earlier aborted operation). + (merge 90b29cb bc/prune-info later to maint). + + * When "git push" triggered the automatic gc on the receiving end, a + message from "git prune" that said it was removing cruft leaked to + the standard output, breaking the communication protocol. + (merge 4b7f2fa bc/receive-pack-stdout-protection later to maint). + + * "git diff" had a confusion between taking data from a path in the + working tree and taking data from an object that happens to have + name 0{40} recorded in a tree. + (merge c479d14 jk/maint-null-in-trees later to maint). + + * The output from "git diff -B" for a file that ends with an + incomplete line did not put "\ No newline..." on a line of its own. + + * "git send-email" did not unquote encoded words that appear on the + header correctly, and lost "_" from strings. + (merge b622d4d tr/maint-send-email-2047 later to maint). + + * When the user gives an argument that can be taken as both a + revision name and a pathname without disambiguating with "--", we + used to give a help message "Use '--' to separate". The message + has been clarified to show where that '--' goes on the command + line. + (merge 4d4b573 mm/die-with-dashdash-help later to maint). + + * "gitweb" when used with PATH_INFO failed to notice directories with + SP (and other characters that need URL-style quoting) in them. + (merge cacfc09 js/gitweb-path-info-unquote later to maint). diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index a26d245ab4..1273a85c8a 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -36,7 +36,7 @@ ifndef::git-asciidoc-no-roff[] # v1.72 breaks with this because it replaces dots not in roff requests. [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> ifdef::doctype-manpage[] .ft C endif::doctype-manpage[] @@ -53,7 +53,7 @@ ifdef::doctype-manpage[] # The following two small workarounds insert a simple paragraph after screen [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> | </literallayout><simpara></simpara> {title#}</example> diff --git a/Documentation/config.txt b/Documentation/config.txt index a95e5a4ac9..6416cae511 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1210,8 +1210,16 @@ gitweb.snapshot:: grep.lineNumber:: If set to true, enable '-n' option by default. +grep.patternType:: + Set the default matching behavior. Using a value of 'basic', 'extended', + 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp', + '--fixed-strings', or '--perl-regexp' option accordingly, while the + value 'default' will return to the default matching behavior. + grep.extendedRegexp:: - If set to true, enable '--extended-regexp' option by default. + If set to true, enable '--extended-regexp' option by default. This + option is ignored when the 'grep.patternType' option is set to a value + other than 'default'. gpg.program:: Use this custom program instead of "gpg" found on $PATH when diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 0e170a51ca..c205d2363e 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -118,6 +118,11 @@ effect to your index in a row. previous commit are dropped. To force the inclusion of those commits use `--keep-redundant-commits`. +--allow-empty-message:: + By default, cherry-picking a commit with an empty message will fail. + This option overrides that behaviour, allowing commits with empty + messages to be cherry picked. + --keep-redundant-commits:: If a commit being cherry picked duplicates a commit already in the current history, it will become empty. By default these diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 2d6ef32a08..eaea079165 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -54,16 +54,16 @@ configuration file by default, and options '--system', '--global', '--file <filename>' can be used to tell the command to write to that location (you can say '--local' but that is the default). -This command will fail (with exit code ret) if: +This command will fail with non-zero status upon error. Some exit +codes are: . The config file is invalid (ret=3), . can not write to the config file (ret=4), . no section or name was provided (ret=2), . the section or key is invalid (ret=1), . you try to unset an option which does not exist (ret=5), -. you try to unset/set an option for which multiple lines match (ret=5), -. you try to use an invalid regexp (ret=6), or -. you use '--global' option without $HOME being properly set (ret=128). +. you try to unset/set an option for which multiple lines match (ret=5), or +. you try to use an invalid regexp (ret=6). On success, the command returns the exit code 0. @@ -267,7 +267,7 @@ Given a .git/config like this: ; Proxy settings [core] - gitproxy="proxy-command" for kernel.org + gitproxy=proxy-command for kernel.org gitproxy=default-proxy ; for all the rest you can set the filemode to true with @@ -342,7 +342,7 @@ To actually match only values with an exclamation mark, you have to To add a new proxy, without altering any of the existing ones, use ------------ -% git config core.gitproxy '"proxy-command" for example.com' +% git config --add core.gitproxy '"proxy-command" for example.com' ------------ An example to use customized color from the configuration in your diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt index 11edc5a173..d15db42d43 100644 --- a/Documentation/git-credential-cache--daemon.txt +++ b/Documentation/git-credential-cache--daemon.txt @@ -3,7 +3,7 @@ git-credential-cache--daemon(1) NAME ---- -git-credential-cache--daemon - temporarily store user credentials in memory +git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index f3d09c5d51..eeff5fa989 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -3,7 +3,7 @@ git-credential-cache(1) NAME ---- -git-credential-cache - helper to temporarily store passwords in memory +git-credential-cache - Helper to temporarily store passwords in memory SYNOPSIS -------- diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 31093467d1..b27c03c361 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -3,7 +3,7 @@ git-credential-store(1) NAME ---- -git-credential-store - helper to store credentials on disk +git-credential-store - Helper to store credentials on disk SYNOPSIS -------- diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index e8f757704c..7e5098a95e 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -16,6 +16,7 @@ SYNOPSIS [--reuseaddr] [--detach] [--pid-file=<file>] [--enable=<service>] [--disable=<service>] [--allow-override=<service>] [--forbid-override=<service>] + [--access-hook=<path>] [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]] [<directory>...] @@ -171,6 +172,21 @@ the facility of inet daemon to achieve the same before spawning errors are not enabled, all errors report "access denied" to the client. The default is --no-informative-errors. +--access-hook=<path>:: + Every time a client connects, first run an external command + specified by the <path> with service name (e.g. "upload-pack"), + path to the repository, hostname (%H), canonical hostname + (%CH), ip address (%IP), and tcp port (%P) as its command line + arguments. The external command can decide to decline the + service by exiting with a non-zero status (or to allow it by + exiting with a zero status). It can also look at the $REMOTE_ADDR + and $REMOTE_PORT environment variables to learn about the + requestor when making this decision. ++ +The external command can optionally write a single line to its +standard output to be sent to the requestor as an error message when +it declines the service. + <directory>:: A directory to add to the whitelist of allowed directories. Unless --strict-paths is specified this will also include subdirectories diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 039cce2e98..72d6bb612b 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -36,12 +36,12 @@ OPTIONS --all:: Instead of using only the annotated tags, use any ref - found in `.git/refs/`. This option enables matching + found in `refs/` namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag - found in `.git/refs/tags`. This option enables matching + found in `refs/tags` namespace. This option enables matching a lightweight (non-annotated) tag. --contains:: diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 31fc2e3aed..73ca7025a3 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -69,6 +69,14 @@ with custom merge tool commands and has the same value as `$MERGED`. --tool-help:: Print a list of diff tools that may be used with `--tool`. +--symlinks:: +--no-symlinks:: + 'git difftool''s default behavior is create symlinks to the + working tree when run in `--dir-diff` mode. ++ + Specifying `--no-symlinks` instructs 'git difftool' to create + copies instead. `--no-symlinks` is the default on Windows. + -x <command>:: --extcmd=<command>:: Specify a custom command for viewing diffs. diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 81f58234a7..15e7ac80c0 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,7 +32,8 @@ 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` and `.git/refs/replace/`. +*NOTE*: This command honors `.git/info/grafts` file and refs in +the `refs/replace/` namespace. If you have any grafts or replacement refs defined, running this command will make them permanent. diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index bbb25da2dd..da348fc942 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -23,8 +23,8 @@ OPTIONS An object to treat as the head of an unreachability trace. + If no objects are given, 'git fsck' defaults to using the -index file, all SHA1 references in .git/refs/*, and all reflogs (unless ---no-reflogs is given) as heads. +index file, all SHA1 references in `refs` namespace, and all reflogs +(unless --no-reflogs is given) as heads. --unreachable:: Print out objects that exist but that aren't reachable from any diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 3bec036883..cfecf848fb 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -42,8 +42,16 @@ CONFIGURATION grep.lineNumber:: If set to true, enable '-n' option by default. +grep.patternType:: + Set the default matching behavior. Using a value of 'basic', 'extended', + 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp', + '--fixed-strings', or '--perl-regexp' option accordingly, while the + value 'default' will return to the default matching behavior. + grep.extendedRegexp:: - If set to true, enable '--extended-regexp' option by default. + If set to true, enable '--extended-regexp' option by default. This + option is ignored when the 'grep.patternType' option is set to a value + other than 'default'. OPTIONS diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index c406a11001..d54932889f 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -48,7 +48,8 @@ $ gitk $(cd .git/lost-found/commit && echo ??*) ------------ After making sure you know which the object is the tag you are looking -for, you can reconnect it to your regular .git/refs hierarchy. +for, you can reconnect it to your regular `refs` hierarchy by using +the `update-ref` command. ------------ $ git cat-file -t 1ef2b196 diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index d7207bd9b9..6b563c500f 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -64,6 +64,9 @@ variable `mergetool.<tool>.trustExitCode` can be set to `true`. Otherwise, 'git mergetool' will prompt the user to indicate the success of the resolution after the custom tool has exited. +--tool-help:: + Print a list of merge tools that may be used with `--tool`. + -y:: --no-prompt:: Don't prompt before each invocation of the merge resolution diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 10afd4edfe..f131677478 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -14,7 +14,8 @@ DESCRIPTION ----------- Traditionally, tips of branches and tags (collectively known as -'refs') were stored one file per ref under `$GIT_DIR/refs` +'refs') were stored one file per ref in a (sub)directory +under `$GIT_DIR/refs` directory. While many branch tips tend to be updated often, most tags and some branch tips are never updated. When a repository has hundreds or thousands of tags, this @@ -22,13 +23,14 @@ one-file-per-ref format both wastes storage and hurts performance. This command is used to solve the storage and performance -problem by stashing the refs in a single file, +problem by storing the refs in a single file, `$GIT_DIR/packed-refs`. When a ref is missing from the -traditional `$GIT_DIR/refs` hierarchy, it is looked up in this +traditional `$GIT_DIR/refs` directory hierarchy, it is looked +up in this file and used if found. Subsequent updates to branches always create new files under -`$GIT_DIR/refs` hierarchy. +`$GIT_DIR/refs` directory hierarchy. A recommended practice to deal with a repository with too many refs is to pack its refs with `--all --prune` once, and @@ -57,6 +59,15 @@ a repository with many branches of historical interests. The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. + +BUGS +---- + +Older documentation written before the packed-refs mechanism was +introduced may still say things like ".git/refs/heads/<branch> file +exists" when it means "branch <branch> exists". + + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index defb544ed0..67fa5ee195 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -101,6 +101,7 @@ include::merge-options.txt[] :git-pull: 1 +-r:: --rebase:: Rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 17df525275..51131d0858 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -14,14 +14,13 @@ SYNOPSIS DESCRIPTION ----------- -Adds a 'replace' reference in `.git/refs/replace/` +Adds a 'replace' reference in `refs/replace/` namespace. The name of the 'replace' reference is the SHA1 of the object that is replaced. The content of the 'replace' reference is the SHA1 of the replacement object. -Unless `-f` is given, the 'replace' reference must not yet exist in -`.git/refs/replace/` directory. +Unless `-f` is given, the 'replace' reference must not yet exist. Replacement references will be used by default by all git commands except those doing reachability traversal (prune, pack transfer and diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index fbbbcb282c..2de7bf0900 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -149,6 +149,11 @@ submodule with the `--init` option. + If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. ++ +If `--force` is specified, the submodule will be checked out (using +`git checkout --force` if appropriate), even if the commit specified in the +index of the containing repository already matches the commit checked out in +the submodule. summary:: Show commit summary between the given commit (defaults to HEAD) and @@ -210,7 +215,9 @@ OPTIONS This option is only valid for add and update commands. When running add, allow adding an otherwise ignored submodule path. When running update, throw away local changes in submodules when - switching to a different commit. + switching to a different commit; and always run a checkout operation + in the submodule, even if the commit listed in the index of the + containing repository matches the commit checked out in the submodule. --cached:: This option is only valid for status and summary commands. These diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index e36a7c3d1e..247534e908 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -20,11 +20,10 @@ SYNOPSIS DESCRIPTION ----------- -Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given +Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given to delete, list or verify tags. -Unless `-f` is given, the tag to be created must not yet exist in the -`.git/refs/tags/` directory. +Unless `-f` is given, the named tag must not yet exist. If one of `-a`, `-s`, or `-u <key-id>` is passed, the command creates a 'tag' object, and requires a tag message. Unless diff --git a/Documentation/git.txt b/Documentation/git.txt index 27da0eb209..463d567a87 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -22,18 +22,17 @@ unusually rich command set that provides both high-level operations and full access to internals. See linkgit:gittutorial[7] to get started, then see -link:everyday.html[Everyday Git] for a useful minimum set of commands, and -"man git-commandname" for documentation of each command. CVS users may -also want to read linkgit:gitcvs-migration[7]. See -the link:user-manual.html[Git User's Manual] for a more in-depth -introduction. +link:everyday.html[Everyday Git] for a useful minimum set of +commands. The link:user-manual.html[Git User's Manual] has a more +in-depth introduction. -The '<command>' is either a name of a Git command (see below) or an alias -as defined in the configuration file (see linkgit:git-config[1]). +After you mastered the basic concepts, you can come back to this +page to learn what commands git offers. You can learn more about +individual git commands with "git help command". linkgit:gitcli[7] +manual page gives you an overview of the command line command syntax. -Formatted and hyperlinked version of the latest git -documentation can be viewed at -`http://git-htmldocs.googlecode.com/git/git.html`. +Formatted and hyperlinked version of the latest git documentation +can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`. ifdef::stalenotes[] [NOTE] @@ -411,24 +410,6 @@ help ...`. linkgit:git-replace[1] for more information. -FURTHER DOCUMENTATION ---------------------- - -See the references above to get started using git. The following is -probably more detail than necessary for a first-time user. - -The link:user-manual.html#git-concepts[git concepts chapter of the -user-manual] and linkgit:gitcore-tutorial[7] both provide -introductions to the underlying git architecture. - -See linkgit:gitworkflows[7] for an overview of recommended workflows. - -See also the link:howto-index.html[howto] documents for some useful -examples. - -The internals are documented in the -link:technical/api-index.html[GIT API documentation]. - GIT COMMANDS ------------ @@ -848,6 +829,29 @@ The index is also capable of storing multiple entries (called "stages") for a given pathname. These stages are used to hold the various unmerged version of a file when a merge is in progress. +FURTHER DOCUMENTATION +--------------------- + +See the references in the "description" section to get started +using git. The following is probably more detail than necessary +for a first-time user. + +The link:user-manual.html#git-concepts[git concepts chapter of the +user-manual] and linkgit:gitcore-tutorial[7] both provide +introductions to the underlying git architecture. + +See linkgit:gitworkflows[7] for an overview of recommended workflows. + +See also the link:howto-index.html[howto] documents for some useful +examples. + +The internals are documented in the +link:technical/api-index.html[GIT API documentation]. + +Users migrating from CVS may also want to +read linkgit:gitcvs-migration[7]. + + Authors ------- Git was started by Linus Torvalds, and is currently maintained by Junio diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index ea17f7a53b..3e72a5d68e 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -62,6 +62,14 @@ scripting git: `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work if you happen to have a file called `HEAD` in the work tree. + * many commands allow a long option "--option" to be abbreviated + only to their unique prefix (e.g. if there is no other option + whose name begins with "opt", you may be able to spell "--opt" to + invoke the "--option" flag), but you should fully spell them out + when writing your scripts; later versions of Git may introduce a + new option whose name shares the same prefix, e.g. "--optimize", + to make a short prefix that used to be unique no longer unique. + ENHANCED OPTION PARSER ---------------------- diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index d9b2b5b2e0..def1340ac7 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -578,16 +578,33 @@ Commit Ordering By default, the commits are shown in reverse chronological order. ---topo-order:: +--date-order:: + Show no parents before all of its children are shown, but + otherwise show commits in the commit timestamp order. - This option makes them appear in topological order (i.e. - descendant commits are shown before their parents). +--topo-order:: + Show no parents before all of its children are shown, and + avoid showing commits on multiple lines of history + intermixed. ++ +For example, in a commit history like this: ++ +---------------------------------------------------------------- ---date-order:: + ---1----2----4----7 + \ \ + 3----5----6----8--- - This option is similar to '--topo-order' in the sense that no - parent comes before all of its children, but otherwise things - are still ordered in the commit timestamp order. +---------------------------------------------------------------- ++ +where the numbers denote the order of commit timestamps, `git +rev-list` and friends with `--date-order` show the commits in the +timestamp order: 8 7 6 5 4 3 2 1. ++ +With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 +3 1); some older commits are shown before newer ones in order to +avoid showing the commits from two parallel development track mixed +together. --reverse:: diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf index 339b30919e..d87294de2f 100644 --- a/Documentation/user-manual.conf +++ b/Documentation/user-manual.conf @@ -14,7 +14,7 @@ ifdef::backend-docbook[] # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> | </literallayout> {title#}</example> |