diff options
Diffstat (limited to 'Documentation')
62 files changed, 1858 insertions, 242 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 06b0c57..cd5b439 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -103,6 +103,14 @@ ifdef DOCBOOK_SUPPRESS_SP XMLTO_EXTRA += -m manpage-suppress-sp.xsl endif +# If your target system uses GNU groff, it may try to render +# apostrophes as a "pretty" apostrophe using unicode. This breaks +# cut&paste, so you should set GNU_ROFF to force them to be ASCII +# apostrophes. Unfortunately does not work with non-GNU roff. +ifdef GNU_ROFF +XMLTO_EXTRA += -m manpage-quote-apos.xsl +endif + SHELL_PATH ?= $(SHELL) # Shell quote; SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) diff --git a/Documentation/RelNotes-1.6.4.4.txt b/Documentation/RelNotes-1.6.4.4.txt new file mode 100644 index 0000000..0ead45f --- /dev/null +++ b/Documentation/RelNotes-1.6.4.4.txt @@ -0,0 +1,26 @@ +GIT v1.6.4.4 Release Notes +========================== + +Fixes since v1.6.4.4 +-------------------- + +* The workaround for Github server that sometimes gave 500 (Internal server + error) response to HEAD requests in 1.6.4.3 introduced a regression that + caused re-fetching projects over http to segfault in certain cases due + to uninitialized pointer being freed. + +* "git pull" on an unborn branch used to consider anything in the work + tree and the index discardable. + +* "git diff -b/w" did not work well on the incomplete line at the end of + the file, due to an incorrect hashing of lines in the low-level xdiff + routines. + +* "git checkout-index --prefix=$somewhere" used to work when $somewhere is + a symbolic link to a directory elsewhere, but v1.6.4.2 broke it. + +* "git unpack-objects --strict", invoked when receive.fsckobjects + configuration is set in the receiving repository of "git push", did not + properly check the objects, especially the submodule links, it received. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes-1.6.5.1.txt b/Documentation/RelNotes-1.6.5.1.txt new file mode 100644 index 0000000..309ba18 --- /dev/null +++ b/Documentation/RelNotes-1.6.5.1.txt @@ -0,0 +1,20 @@ +GIT v1.6.5.1 Release Notes +========================== + +Fixes since v1.6.5 +------------------ + + * An corrupt pack could make codepath to read objects into an + infinite loop. + + * Download throughput display was always shown in KiB/s but on fast links + it is more appropriate to show it in MiB/s. + + * "git grep -f filename" used uninitialized variable and segfaulted. + + * "git clone -b branch" gave a wrong commit object name to post-checkout + hook. + + * "git pull" over http did not work on msys. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes-1.6.5.2.txt b/Documentation/RelNotes-1.6.5.2.txt new file mode 100644 index 0000000..aa7ccce --- /dev/null +++ b/Documentation/RelNotes-1.6.5.2.txt @@ -0,0 +1,19 @@ +GIT v1.6.5.2 Release Notes +========================== + +Fixes since v1.6.5.1 +-------------------- + + * Installation of templates triggered a bug in busybox when using tar + implementation from it. + + * "git add -i" incorrectly ignored paths that are already in the index + if they matched .gitignore patterns. + + * "git describe --always" should have produced some output even there + were no tags in the repository, but it didn't. + + * "git ls-files" when showing tracked files incorrectly paid attention + to the exclude patterns. + +Other minor documentation updates are included. diff --git a/Documentation/RelNotes-1.6.5.txt b/Documentation/RelNotes-1.6.5.txt new file mode 100644 index 0000000..ee141c1 --- /dev/null +++ b/Documentation/RelNotes-1.6.5.txt @@ -0,0 +1,169 @@ +GIT v1.6.5 Release Notes +======================== + +In git 1.7.0, which was planned to be the release after 1.6.5, "git +push" into a branch that is currently checked out will be refused by +default. + +You can choose what should happen upon such a push by setting the +configuration variable receive.denyCurrentBranch in the receiving +repository. + +Also, "git push $there :$killed" to delete the branch $killed in a remote +repository $there, when $killed branch is the current branch pointed at by +its HEAD, will be refused by default. + +You can choose what should happen upon such a push by setting the +configuration variable receive.denyDeleteCurrent in the receiving +repository. + +To ease the transition plan, the receiving repository of such a +push running this release will issue a big warning when the +configuration variable is missing. Please refer to: + + http://git.or.cz/gitwiki/GitFaq#non-bare + http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + +for more details on the reason why this change is needed and the +transition plan. + +Updates since v1.6.4 +-------------------- + +(subsystems) + + * various updates to gitk, git-svn and gitweb. + +(portability) + + * more improvements on mingw port. + + * mingw will also give FRSX as the default value for the LESS + environment variable when the user does not have one. + + * initial support to compile git on Windows with MSVC. + +(performance) + + * On major platforms, the system can be compiled to use with Linus's + block-sha1 implementation of the SHA-1 hash algorithm, which + outperforms the default fallback implementation we borrowed from + Mozilla. + + * Unnecessary inefficiency in deepening of a shallow repository has + been removed. + + * "git clone" does not grab objects that it does not need (i.e. + referenced only from refs outside refs/heads and refs/tags + hierarchy) anymore. + + * The "git" main binary used to link with libcurl, which then dragged + in a large number of external libraries. When using basic plumbing + commands in scripts, this unnecessarily slowed things down. We now + implement http/https/ftp transfer as a separate executable as we + used to. + + * "git clone" run locally hardlinks or copies the files in .git/ to + newly created repository. It used to give new mtime to copied files, + but this delayed garbage collection to trigger unnecessarily in the + cloned repository. We now preserve mtime for these files to avoid + this issue. + +(usability, bells and whistles) + + * Human writable date format to various options, e.g. --since=yesterday, + master@{2000.09.17}, are taught to infer some omitted input properly. + + * A few programs gave verbose "advice" messages to help uninitiated + people when issuing error messages. An infrastructure to allow + users to squelch them has been introduced, and a few such messages + can be silenced now. + + * refs/replace/ hierarchy is designed to be usable as a replacement + of the "grafts" mechanism, with the added advantage that it can be + transferred across repositories. + + * "git am" learned to optionally ignore whitespace differences. + + * "git am" handles input e-mail files that has CRLF line endings sensibly. + + * "git am" learned "--scissors" option to allow you to discard early part + of an incoming e-mail. + + * "git archive -o output.zip" works without being told what format to + use with an explicit "--format=zip".option. + + * "git checkout", "git reset" and "git stash" learned to pick and + choose to use selected changes you made, similar to "git add -p". + + * "git clone" learned a "-b" option to pick a HEAD to check out + different from the remote's default branch. + + * "git clone" learned --recursive option. + + * "git clone" from a local repository on a different filesystem used to + copy individual object files without preserving the old timestamp, giving + them extra lifetime in the new repository until they gc'ed. + + * "git commit --dry-run $args" is a new recommended way to ask "what would + happen if I try to commit with these arguments." + + * "git commit --dry-run" and "git status" shows conflicted paths in a + separate section to make them easier to spot during a merge. + + * "git cvsimport" now supports password-protected pserver access even + when the password is not taken from ~/.cvspass file. + + * "git fast-export" learned --no-data option that can be useful when + reordering commits and trees without touching the contents of + blobs. + + * "git fast-import" has a pair of new front-end in contrib/ area. + + * "git init" learned to mkdir/chdir into a directory when given an + extra argument (i.e. "git init this"). + + * "git instaweb" optionally can use mongoose as the web server. + + * "git log --decorate" can optionally be told with --decorate=full to + give the reference name in full. + + * "git merge" issued an unnecessarily scary message when it detected + that the merge may have to touch the path that the user has local + uncommitted changes to. The message has been reworded to make it + clear that the command aborted, without doing any harm. + + * "git push" can be told to be --quiet. + + * "git push" pays attention to url.$base.pushInsteadOf and uses a URL + that is derived from the URL used for fetching. + + * informational output from "git reset" that lists the locally modified + paths is made consistent with that of "git checkout $another_branch". + + * "git submodule" learned to give submodule name to scripts run with + "foreach" subcommand. + + * various subcommands to "git submodule" learned --recursive option. + + * "git submodule summary" learned --files option to compare the work + tree vs the commit bound at submodule path, instead of comparing + the index. + + * "git upload-pack", which is the server side support for "git clone" and + "git fetch", can call a new post-upload-pack hook for statistics purposes. + +(developers) + + * With GIT_TEST_OPTS="--root=/p/a/t/h", tests can be run outside the + source directory; using tmpfs may give faster turnaround. + + * With NO_PERL_MAKEMAKER set, DESTDIR= is now honoured, so you can + build for one location, and install into another location to tar it + up. + +Fixes since v1.6.4 +------------------ + +All of the fixes in v1.6.4.X maintenance series are included in this +release, unless otherwise noted. diff --git a/Documentation/config.txt b/Documentation/config.txt index 273bbde..d1e2120 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -113,6 +113,21 @@ For command-specific variables, you will find a more detailed description in the appropriate manual page. You will find a description of non-core porcelain configuration variables in the respective porcelain documentation. +advice.*:: + When set to 'true', display the given optional help message. + When set to 'false', do not display. The configuration variables + are: ++ +-- + pushNonFastForward:: + Advice shown when linkgit:git-push[1] refuses + non-fast-forward refs. Default: true. + statusHints:: + Directions on how to stage/unstage/add shown in the + output of linkgit:git-status[1] and the template shown + when writing commit messages. Default: true. +-- + core.fileMode:: If false, the executable bit differences between the index and the working copy are ignored; useful on broken filesystems like FAT. @@ -465,6 +480,14 @@ it will be treated as a shell command. For example, defining executed from the top-level directory of a repository, which may not necessarily be the current directory. +apply.ignorewhitespace:: + When set to 'change', tells 'git-apply' to ignore changes in + whitespace, in the same way as the '--ignore-space-change' + option. + When set to one of: no, none, never, false tells 'git-apply' to + respect all whitespace differences. + See linkgit:git-apply[1]. + apply.whitespace:: Tells 'git-apply' how to handle whitespaces, in the same way as the '--whitespace' option. See linkgit:git-apply[1]. @@ -520,7 +543,7 @@ branch.<name>.merge:: branch.<name>.mergeoptions:: Sets default options for merging into branch <name>. The syntax and - supported options are equal to that of linkgit:git-merge[1], but + supported options are the same as those of linkgit:git-merge[1], but option values containing whitespace characters are currently not supported. @@ -1301,6 +1324,11 @@ rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. +receive.autogc:: + By default, git-receive-pack will run "git-gc --auto" after + receiving data from git-push and updating refs. You can stop + it by setting this variable to false. + receive.fsckObjects:: If it is set to true, git-receive-pack will check all received objects. It will abort in the case of a malformed object or a @@ -1336,6 +1364,10 @@ receive.denyNonFastForwards:: even if that push is forced. This configuration variable is set when initializing a shared repository. +receive.updateserverinfo:: + If set to true, git-receive-pack will run git-update-server-info + after receiving data from git-push and updating refs. + remote.<name>.url:: The URL of a remote repository. See linkgit:git-fetch[1] or linkgit:git-push[1]. @@ -1496,6 +1528,19 @@ url.<base>.insteadOf:: never-before-seen repository on the site. When more than one insteadOf strings match a given URL, the longest match is used. +url.<base>.pushInsteadOf:: + Any URL that starts with this value will not be pushed to; + instead, it will be rewritten to start with <base>, and the + resulting URL will be pushed to. In cases where some site serves + a large number of repositories, and serves them with multiple + access methods, some of which do not allow push, this feature + allows people to specify a pull-only URL and have git + automatically use an appropriate URL to push, even for a + never-before-seen repository on the site. When more than one + pushInsteadOf strings match a given URL, the longest match is + used. If a remote has an explicit pushurl, git will ignore this + setting for that remote. + user.email:: Your email address to be recorded in any newly created commits. Can be overridden by the 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL', and diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 5eb2b0e..2886874 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -1,25 +1,13 @@ -ifndef::git-pull[] --q:: ---quiet:: - Pass --quiet to git-fetch-pack and silence any other internally - used git commands. - --v:: ---verbose:: - Be verbose. -endif::git-pull[] - -a:: --append:: Append ref names and object names of fetched refs to the existing contents of `.git/FETCH_HEAD`. Without this option old data in `.git/FETCH_HEAD` will be overwritten. ---upload-pack <upload-pack>:: - When given, and the repository to fetch from is handled - by 'git-fetch-pack', '--exec=<upload-pack>' is passed to - the command to specify non-default path for the command - run on the other end. +--depth=<depth>:: + Deepen the history of a 'shallow' repository created by + `git clone` with `--depth=<depth>` option (see linkgit:git-clone[1]) + by the specified number of commits. -f:: --force:: @@ -29,6 +17,10 @@ endif::git-pull[] fetches is a descendant of `<lbranch>`. This option overrides that check. +-k:: +--keep:: + Keep downloaded pack. + ifdef::git-pull[] --no-tags:: endif::git-pull[] @@ -49,10 +41,6 @@ endif::git-pull[] flag lets all tags and their associated objects be downloaded. --k:: ---keep:: - Keep downloaded pack. - -u:: --update-head-ok:: By default 'git-fetch' refuses to update the head which @@ -62,7 +50,19 @@ endif::git-pull[] implementing your own Porcelain you are not supposed to use it. ---depth=<depth>:: - Deepen the history of a 'shallow' repository created by - `git clone` with `--depth=<depth>` option (see linkgit:git-clone[1]) - by the specified number of commits. +--upload-pack <upload-pack>:: + When given, and the repository to fetch from is handled + by 'git-fetch-pack', '--exec=<upload-pack>' is passed to + the command to specify non-default path for the command + run on the other end. + +ifndef::git-pull[] +-q:: +--quiet:: + Pass --quiet to git-fetch-pack and silence any other internally + used git commands. + +-v:: +--verbose:: + Be verbose. +endif::git-pull[] diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index e67b7e8..e93e606 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -72,9 +72,14 @@ OPTIONS -p:: --patch:: - Similar to Interactive mode but the initial command loop is - bypassed and the 'patch' subcommand is invoked using each of - the specified filepatterns before exiting. + Interactively choose hunks of patch between the index and the + work tree and add them to the index. This gives the user a chance + to review the difference before adding modified contents to the + index. ++ +This effectively runs `add --interactive`, but bypasses the +initial command menu and directly jumps to the `patch` subcommand. +See ``Interactive mode'' for details. -e, \--edit:: Open the diff vs. the index in an editor and let the user diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 32e689b..67ad5da 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -11,9 +11,9 @@ SYNOPSIS [verse] 'git am' [--signoff] [--keep] [--utf8 | --no-utf8] [--3way] [--interactive] [--committer-date-is-author-date] - [--ignore-date] + [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] - [--reject] [-q | --quiet] + [--reject] [-q | --quiet] [--scissors | --no-scissors] [<mbox> | <Maildir>...] 'git am' (--skip | --resolved | --abort) @@ -39,6 +39,14 @@ OPTIONS --keep:: Pass `-k` flag to 'git-mailinfo' (see linkgit:git-mailinfo[1]). +-c:: +--scissors:: + Remove everything in body before a scissors line (see + linkgit:git-mailinfo[1]). + +---no-scissors:: + Ignore scissors lines (see linkgit:git-mailinfo[1]). + -q:: --quiet:: Be quiet. Only print error messages. @@ -65,6 +73,9 @@ default. You can use `--no-utf8` to override this. it is supposed to apply to and we have those blobs available locally. +--ignore-date:: +--ignore-space-change:: +--ignore-whitespace:: --whitespace=<option>:: -C<n>:: -p<n>:: @@ -125,10 +136,8 @@ the commit, after stripping common prefix "[PATCH <anything>]". The "Subject: " line is supposed to concisely describe what the commit is about in one line of text. -"From: " and "Subject: " lines starting the body (the rest of the -message after the blank line terminating the RFC2822 headers) -override the respective commit author name and title values taken -from the headers. +"From: " and "Subject: " lines starting the body override the respective +commit author name and title values taken from the headers. The commit message is formed by the title taken from the "Subject: ", a blank line and the body of the message up to diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 735374d..5ee8c91 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -13,6 +13,7 @@ SYNOPSIS [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached] + [--ignore-space-change | --ignore-whitespace ] [--whitespace=<nowarn|warn|fix|error|error-all>] [--exclude=PATH] [--include=PATH] [--directory=<root>] [--verbose] [<patch>...] @@ -149,6 +150,14 @@ patch to each path is used. A patch to a path that does not match any include/exclude pattern is used by default if there is no include pattern on the command line, and ignored if there is any include pattern. +--ignore-space-change:: +--ignore-whitespace:: + When applying a patch, ignore changes in whitespace in context + lines if necessary. + Context lines will preserve their whitespace, and they will not + undergo whitespace fixing regardless of the value of the + `--whitespace` option. New lines will still be fixed, though. + --whitespace=<action>:: When applying a patch, detect a new or modified line that has whitespace errors. What are considered whitespace errors is @@ -205,6 +214,10 @@ running `git apply --directory=modules/git-gui`. Configuration ------------- +apply.ignorewhitespace:: + Set to 'change' if you want changes in whitespace to be ignored by default. + Set to one of: no, none, never, false if you want changes in + whitespace to be significant. apply.whitespace:: When no `--whitespace` flag is given from the command line, this configuration item is used as the default. diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 92444dd..3d1c1e7 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>] - [--output=<file>] [--worktree-attributes] + [-o | --output=<file>] [--worktree-attributes] [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish> [path...] @@ -34,8 +34,11 @@ OPTIONS ------- --format=<fmt>:: - Format of the resulting archive: 'tar' or 'zip'. The default - is 'tar'. + Format of the resulting archive: 'tar' or 'zip'. If this option + is not given, and the output file is specified, the format is + inferred from the filename if possible (e.g. writing to "foo.zip" + makes the output to be in the zip format). Otherwise the output + format is `tar`. -l:: --list:: @@ -48,6 +51,7 @@ OPTIONS --prefix=<prefix>/:: Prepend <prefix>/ to each filename in the archive. +-o <file>:: --output=<file>:: Write the archive to <file> instead of stdout. @@ -129,6 +133,12 @@ git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs 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:: + + 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. + SEE ALSO -------- diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index ae201de..0e83680 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -30,10 +30,8 @@ commit) will be listed. With `--no-merged` only branches not merged into the named commit will be listed. If the <commit> argument is missing it defaults to 'HEAD' (i.e. the tip of the current branch). -In the command's second form, a new branch named <branchname> will be created. -It will start out with a head equal to the one given as <start-point>. -If no <start-point> is given, the branch will be created with a head -equal to that of the currently checked out branch. +The command's second form creates a new branch head named <branchname> +which points to the current 'HEAD', or <start-point> if given. Note that this will create the new branch, but it will not switch the working tree to it; use "git checkout <newbranch>" to switch to the @@ -76,6 +74,7 @@ OPTIONS based sha1 expressions such as "<branchname>@\{yesterday}". -f:: +--force:: Reset <branchname> to <startpoint> if <branchname> exists already. Without `-f` 'git-branch' refuses to change an existing branch. @@ -133,11 +132,13 @@ start-point is either a local or remote branch. --contains <commit>:: Only list branches which contain the specified commit. ---merged:: - Only list branches which are fully contained by HEAD. +--merged [<commit>]:: + Only list branches whose tips are reachable from the + specified commit (HEAD if not specified). ---no-merged:: - Do not list branches which are fully contained by HEAD. +--no-merged [<commit>]:: + Only list branches whose tips are not reachable from the + specified commit (HEAD if not specified). <branchname>:: The name of the branch to create or delete. @@ -146,9 +147,9 @@ start-point is either a local or remote branch. may restrict the characters allowed in a branch name. <start-point>:: - The new branch will be created with a HEAD equal to this. It may - be given as a branch name, a commit-id, or a tag. If this option - is omitted, the current branch is assumed. + The new branch head will point to this commit. It may be + given as a branch name, a commit-id, or a tag. If this + option is omitted, the current HEAD will be used instead. <oldbranch>:: The name of an existing branch to rename. @@ -209,6 +210,14 @@ but different purposes: - `--no-merged` is used to find branches which are candidates for merging into HEAD, since those branches are not fully contained by HEAD. +SEE ALSO +-------- +linkgit:git-check-ref-format[1], +linkgit:git-fetch[1], +linkgit:git-remote[1], +link:user-manual.html#what-is-a-branch[``Understanding history: What is +a branch?''] in the Git User's Manual. + Author ------ Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <gitster@pobox.com> diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 0b7982e..e9b3b40 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git check-ref-format' <refname> -'git check-ref-format' [--branch] <branchname-shorthand> +'git check-ref-format' --branch <branchname-shorthand> DESCRIPTION ----------- @@ -63,8 +63,11 @@ reference name expressions (see linkgit:git-rev-parse[1]): . at-open-brace `@{` is used as a notation to access a reflog entry. -With the `--branch` option, it expands a branch name shorthand and -prints the name of the branch the shorthand refers to. +With the `--branch` option, it expands the ``previous branch syntax'' +`@{-n}`. For example, `@{-1}` is a way to refer the last branch you +were on. This option should be used by porcelains to accept this +syntax anywhere a branch name is expected, so they can act as if you +typed the branch name. EXAMPLE ------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index ad4b31e..37c1810 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -11,6 +11,7 @@ SYNOPSIS 'git checkout' [-q] [-f] [-m] [<branch>] 'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... +'git checkout' --patch [<tree-ish>] [--] [<paths>...] DESCRIPTION ----------- @@ -25,7 +26,7 @@ use the --track or --no-track options, which will be passed to `git branch`. As a convenience, --track without `-b` implies branch creation; see the description of --track below. -When <paths> are given, this command does *not* switch +When <paths> or --patch are given, this command does *not* switch branches. It updates the named paths in the working tree from the index file, or from a named <tree-ish> (most often a commit). In this case, the `-b` and `--track` options are meaningless and giving @@ -45,9 +46,11 @@ file can be discarded to recreate the original conflicted merge result. OPTIONS ------- -q:: +--quiet:: Quiet, suppress feedback messages. -f:: +--force:: When switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes. @@ -113,6 +116,16 @@ the conflicted merge in the specified paths. "merge" (default) and "diff3" (in addition to what is shown by "merge" style, shows the original contents). +-p:: +--patch:: + Interactively select hunks in the difference between the + <tree-ish> (or the index, if unspecified) and the working + tree. The chosen hunks are then applied in reverse to the + working tree (and if a <tree-ish> was specified, the index). ++ +This means that you can use `git checkout -p` to selectively discard +edits from your current working tree. + <branch>:: Branch to checkout; if it refers to a branch (i.e., a name that, when prepended with "refs/heads/", is a valid ref), then that diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index ae8938b..9d291bd 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -32,6 +32,7 @@ OPTIONS if you really want to remove such a directory. -f:: +--force:: If the git configuration specifies clean.requireForce as true, 'git-clean' will refuse to run unless given -f or -n. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 1709a2d..7e7d9fc 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -12,15 +12,16 @@ SYNOPSIS 'git clone' [--template=<template_directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-u <upload-pack>] [--reference <repository>] - [--depth <depth>] [--] <repository> [<directory>] + [--depth <depth>] [--recursive] [--] <repository> [<directory>] DESCRIPTION ----------- Clones a repository into a newly created directory, creates remote-tracking branches for each branch in the cloned repository -(visible using `git branch -r`), and creates and checks out an initial -branch equal to the cloned repository's currently active branch. +(visible using `git branch -r`), and creates and checks out an +initial branch that is forked from the cloned repository's +currently active branch. After the clone, a plain `git fetch` without arguments will update all the remote-tracking branches, and a `git pull` without @@ -38,7 +39,7 @@ OPTIONS --local:: -l:: When the repository to clone from is on a local machine, - this flag bypasses normal "git aware" transport + this flag bypasses the normal "git aware" transport mechanism and clones the repository by making a copy of HEAD and everything under objects and refs directories. The files under `.git/objects/` directory are hardlinked @@ -59,7 +60,7 @@ OPTIONS -s:: When the repository to clone is on the local machine, instead of using hard links, automatically setup - .git/objects/info/alternates to share the objects + `.git/objects/info/alternates` to share the objects with the source repository. The resulting repository starts out without any object of its own. + @@ -68,7 +69,7 @@ it unless you understand what it does. If you clone your repository using this option and then delete branches (or use any other git command that makes any existing commit unreferenced) in the source repository, some objects may become unreferenced (or dangling). -These objects may be removed by normal git operations (such as 'git-commit') +These objects may be removed by normal git operations (such as `git commit`) which automatically call `git gc --auto`. (See linkgit:git-gc[1].) If these objects are removed and were referenced by the cloned repository, then the cloned repository will become corrupt. @@ -85,13 +86,13 @@ objects from the source repository into a pack in the cloned repository. --reference <repository>:: If the reference repository is on the local machine, - automatically setup .git/objects/info/alternates to + automatically setup `.git/objects/info/alternates` to obtain objects from the reference repository. Using an already existing repository as an alternate will require fewer objects to be copied from the repository being cloned, reducing network and local storage costs. + -*NOTE*: see NOTE to --shared option. +*NOTE*: see the NOTE for the `--shared` option. --quiet:: -q:: @@ -100,7 +101,7 @@ objects from the source repository into a pack in the cloned repository. --verbose:: -v:: - Display the progressbar, even in case the standard output is not + Display the progress bar, even in case the standard output is not a terminal. --no-checkout:: @@ -120,12 +121,19 @@ objects from the source repository into a pack in the cloned repository. configuration variables are created. --mirror:: - Set up a mirror of the remote repository. This implies --bare. + Set up a mirror of the remote repository. This implies `--bare`. --origin <name>:: -o <name>:: - Instead of using the remote name 'origin' to keep track - of the upstream repository, use <name>. + Instead of using the remote name `origin` to keep track + of the upstream repository, use `<name>`. + +--branch <name>:: +-b <name>:: + Instead of pointing the newly created HEAD to the branch pointed + to by the cloned repository's HEAD, point to `<name>` branch + instead. In a non-bare repository, this is the branch that will + be checked out. --upload-pack <upload-pack>:: -u <upload-pack>:: @@ -147,6 +155,14 @@ objects from the source repository into a pack in the cloned repository. with a long history, and would want to send in fixes as patches. +--recursive:: + After the clone is created, initialize all submodules within, + using their default settings. This is equivalent to running + `git submodule update --init --recursive` immediately after + the clone is finished. This option is ignored if the cloned + repository does not have a worktree/checkout (i.e. if any of + `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) + <repository>:: The (possibly remote) repository to clone from. See the <<URLS,URLS>> section below for more information on specifying @@ -155,8 +171,8 @@ objects from the source repository into a pack in the cloned repository. <directory>:: The name of a new directory to clone into. The "humanish" part of the source repository is used if no directory is - explicitly given ("repo" for "/path/to/repo.git" and "foo" - for "host.xz:foo/.git"). Cloning into an existing directory + explicitly given (`repo` for `/path/to/repo.git` and `foo` + for `host.xz:foo/.git`). Cloning into an existing directory is only allowed if the directory is empty. :git-clone: 1 diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index b5d81be..0578a40 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,7 +8,7 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend] +'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend] [--dry-run] [(-c | -C) <commit>] [-F <file> | -m <msg>] [--allow-empty] [--no-verify] [-e] [--author=<author>] [--cleanup=<mode>] [--] [[-i | -o ]<file>...] @@ -42,10 +42,9 @@ The content to be added can be specified in several ways: by one which files should be part of the commit, before finalizing the operation. Currently, this is done by invoking 'git-add --interactive'. -The 'git-status' command can be used to obtain a +The `--dry-run` option can be used to obtain a summary of what is included by any of the above for the next -commit by giving the same set of parameters you would give to -this command. +commit by giving the same set of parameters (options and paths). If you make a commit and then find a mistake immediately after that, you can recover from it with 'git-reset'. @@ -198,6 +197,11 @@ specified. --quiet:: Suppress commit summary message. +--dry-run:: + Do not create a commit, but show a list of paths that are + to be committed, paths with local changes that will be left + uncommitted and paths that are untracked. + \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index b231dbb..2f97916 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -44,7 +44,9 @@ OPTIONS --abbrev=<n>:: Instead of using the default 7 hexadecimal digits as the - abbreviated object name, use <n> digits. + abbreviated object name, use <n> digits, or as many digits + as needed to form a unique object name. An <n> of 0 + will suppress long format, only showing the closest tag. --candidates=<n>:: Instead of considering only the 10 most recent tags as @@ -68,8 +70,8 @@ OPTIONS This is useful when you want to see parts of the commit object name in "describe" output, even when the commit in question happens to be a tagged version. Instead of just emitting the tag name, it will - describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2 - that points at object deadbeef....). + describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 + that points at object deadbee....). --match <pattern>:: Only consider tags matching the given pattern (can be used to avoid @@ -108,7 +110,7 @@ the output shows the reference path as well: [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2 tags/v1.0.0-21-g975b - [torvalds@g5 git]$ git describe --all HEAD^ + [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^ heads/lt/describe-7-g975b With --abbrev set to 0, the command can be used to find the @@ -117,6 +119,13 @@ closest tagname without any suffix: [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2 tags/v1.0.0 +Note that the suffix you get if you type these commands today may be +longer than what Linus saw above when he ran these commands, as your +git repository may have new commits whose object names begin with +975b that did not exist back then, and "-g975b" suffix alone may not +be sufficient to disambiguate these commits. + + SEARCH STRATEGY --------------- diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index af2328d..75b06f3 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -82,6 +82,14 @@ marks the same across runs. allow that. So fake a tagger to be able to fast-import the output. +--no-data:: + Skip output of blob objects and instead refer to blobs via + their original SHA-1 hash. This is useful when rewriting the + directory structure or history of a repository without + touching the contents of individual files. Note that the + resulting stream can only be used by a repository which + already contains the necessary objects. + [git-rev-list-args...]:: A list of arguments, acceptable to 'git-rev-parse' and 'git-rev-list', that specifies the specific objects and references diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index d3164c5..f2483d6 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -37,6 +37,35 @@ include::pull-fetch-param.txt[] include::urls-remotes.txt[] + +EXAMPLES +-------- + +* Update the remote-tracking branches: ++ +------------------------------------------------ +$ git fetch origin +------------------------------------------------ ++ +The above command copies all branches from the remote refs/heads/ +namespace and stores them to the local refs/remotes/origin/ namespace, +unless the branch.<name>.fetch option is used to specify a non-default +refspec. + +* Using refspecs explicitly: ++ +------------------------------------------------ +$ git fetch origin +pu:pu maint:tmp +------------------------------------------------ ++ +This updates (or creates, as necessary) branches `pu` and `tmp` in +the local repository by fetching from the branches (respectively) +`pu` and `maint` from the remote repository. ++ +The `pu` branch will be updated even if it is does not fast-forward, +because it is prefixed with a plus sign; `tmp` will not be. + + SEE ALSO -------- linkgit:git-pull[1] diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 32ea856..2b40bab 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -12,6 +12,7 @@ SYNOPSIS [--index-filter <command>] [--parent-filter <command>] [--msg-filter <command>] [--commit-filter <command>] [--tag-name-filter <command>] [--subdirectory-filter <directory>] + [--prune-empty] [--original <namespace>] [-d <directory>] [-f | --force] [--] [<rev-list options>...] diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 1c24796..a586950 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -18,8 +18,8 @@ Takes the list of merged objects on stdin and produces a suitable commit message to be used for the merge commit, usually to be passed as the '<merge-message>' argument of 'git-merge'. -This script is intended mostly for internal use by scripts -automatically invoking 'git-merge'. +This command is intended mostly for internal use by scripts +automatically invoking 'git merge'. OPTIONS ------- diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index dcac8c8..4cd9cdf 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -106,7 +106,7 @@ much time is spent optimizing the delta compression of the objects in the repository when the --aggressive option is specified. The larger the value, the more time is spent optimizing the delta compression. See the documentation for the --window' option in linkgit:git-repack[1] for -more details. This defaults to 10. +more details. This defaults to 250. The optional configuration variable 'gc.pruneExpire' controls how old the unreferenced loose objects have to be before they are pruned. The @@ -120,7 +120,7 @@ Notes particular, it will keep not only objects referenced by your current set of branches and tags, but also objects referenced by the index, remote tracking branches, refs saved by 'git-filter-branch' in -refs/original/, or reflogs (which may references commits in branches +refs/original/, or reflogs (which may reference commits in branches that were later amended or rewound). If you are expecting some objects to be collected and they aren't, check diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index b753c9d..8c70020 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -17,6 +17,7 @@ SYNOPSIS [-l | --files-with-matches] [-L | --files-without-match] [-z | --null] [-c | --count] [--all-match] + [--max-depth <depth>] [--color | --no-color] [-A <post-context>] [-B <pre-context>] [-C <context>] [-f <file>] [-e] <pattern> @@ -47,6 +48,10 @@ OPTIONS -I:: Don't match the pattern in binary files. +--max-depth <depth>:: + For each pathspec given on command line, descend at most <depth> + levels of directories. A negative value means no limit. + -w:: --word-regexp:: Match the pattern only at word boundary (either begin at the diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 1fd0ff2..eba3cb4 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -8,7 +8,7 @@ git-init-db - Creates an empty git repository SYNOPSIS -------- -'git init-db' [-q | --quiet] [--template=<template_directory>] [--shared[=<permissions>]] +'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--shared[=<permissions>]] DESCRIPTION diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 7151d12..f081b24 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -8,7 +8,7 @@ git-init - Create an empty git repository or reinitialize an existing one SYNOPSIS -------- -'git init' [-q | --quiet] [--bare] [--template=<template_directory>] [--shared[=<permissions>]] +'git init' [-q | --quiet] [--bare] [--template=<template_directory>] [--shared[=<permissions>]] [directory] OPTIONS @@ -74,6 +74,9 @@ By default, the configuration flag receive.denyNonFastForwards is enabled in shared repositories, so that you cannot force a non fast-forwarding push into it. +If you name a (possibly non-existent) directory at the end of the command +line, the command is run inside the directory (possibly after creating it). + -- diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index 22da21a..0771f25 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -29,7 +29,7 @@ OPTIONS The HTTP daemon command-line that will be executed. Command-line options may be specified here, and the configuration file will be added at the end of the command-line. - Currently lighttpd, apache2 and webrick are supported. + Currently apache2, lighttpd, mongoose and webrick are supported. (Default: lighttpd) -m:: diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 057a021..021066e 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -44,7 +44,7 @@ OPTIONS -o:: --others:: - Show other files in the output + Show other (i.e. untracked) files in the output -i:: --ignored:: diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 8d95aaa..996c3fc 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -8,7 +8,7 @@ git-mailinfo - Extracts patch and authorship from a single e-mail message SYNOPSIS -------- -'git mailinfo' [-k] [-u | --encoding=<encoding> | -n] <msg> <patch> +'git mailinfo' [-k] [-u | --encoding=<encoding> | -n] [--scissors] <msg> <patch> DESCRIPTION @@ -49,6 +49,25 @@ conversion, even with this flag. -n:: Disable all charset re-coding of the metadata. +--scissors:: + Remove everything in body before a scissors line. A line that + mainly consists of scissors (either ">8" or "8<") and perforation + (dash "-") marks is called a scissors line, and is used to request + the reader to cut the message at that line. If such a line + appears in the body of the message before the patch, everything + before it (including the scissors line itself) is ignored when + this option is used. ++ +This is useful if you want to begin your message in a discussion thread +with comments and suggestions on the message you are responding to, and to +conclude it with a patch submission, separating the discussion and the +beginning of the proposed commit log message with a scissors line. ++ +This can enabled by default with the configuration option mailinfo.scissors. + +--no-scissors:: + Ignore scissors lines. Useful for overriding mailinfo.scissors settings. + <msg>:: The commit log message extracted from e-mail, usually except the title line which comes from e-mail Subject. diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 767486c..ce5b369 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -8,12 +8,12 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- -'git merge-base' [--all] <commit> <commit>... +'git merge-base' [-a|--all] <commit> <commit>... DESCRIPTION ----------- -'git-merge-base' finds best common ancestor(s) between two commits to use +'git merge-base' finds best common ancestor(s) between two commits to use in a three-way merge. One common ancestor is 'better' than another common ancestor if the latter is an ancestor of the former. A common ancestor that does not have any better common ancestor is a 'best common @@ -27,8 +27,13 @@ commits on the command line. As the most common special case, specifying only two commits on the command line means computing the merge base between the given two commits. +As a consequence, the 'merge base' is not necessarily contained in each of the +commit arguments if more than two commits are specified. This is different +from linkgit:git-show-branch[1] when used with the `--merge-base` option. + OPTIONS ------- +-a:: --all:: Output all merge bases for the commits, instead of just one. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index af68d69..e886c2e 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -28,9 +28,10 @@ OPTIONS include::merge-options.txt[] -m <msg>:: - The commit message to be used for the merge commit (in case - it is created). The 'git-fmt-merge-msg' script can be used - to give a good default for automated 'git-merge' invocations. + Set the commit message to be used for the merge commit (in + case one is created). The 'git fmt-merge-msg' command can be + used to give a good default for automated 'git merge' + invocations. <remote>...:: Other branch heads to merge into our branch. You need at @@ -49,8 +50,8 @@ include::merge-config.txt[] branch.<name>.mergeoptions:: Sets default options for merging into branch <name>. The syntax and - supported options are equal to that of 'git-merge', but option values - containing whitespace characters are currently not supported. + supported options are the same as those of 'git merge', but option + values containing whitespace characters are currently not supported. HOW MERGE WORKS --------------- @@ -211,6 +212,39 @@ You can work through the conflict with a number of tools: common ancestor, 'git show :2:filename' shows the HEAD version and 'git show :3:filename' shows the remote version. + +EXAMPLES +-------- + +* Merge branches `fixes` and `enhancements` on top of + the current branch, making an octopus merge: ++ +------------------------------------------------ +$ git merge fixes enhancements +------------------------------------------------ + +* Merge branch `obsolete` into the current branch, using `ours` + merge strategy: ++ +------------------------------------------------ +$ git merge -s ours obsolete +------------------------------------------------ + +* Merge branch `maint` into the current branch, but do not make + a new commit automatically: ++ +------------------------------------------------ +$ git merge --no-commit maint +------------------------------------------------ ++ +This can be used when you want to include further changes to the +merge, or want to write your own merge commit message. ++ +You should refrain from abusing this option to sneak substantial +changes into a merge commit. Small fixups like bumping +release/version name would be acceptable. + + SEE ALSO -------- linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index 9c56602..bdcb585 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -28,6 +28,7 @@ committed. OPTIONS ------- -f:: +--force:: Force renaming or moving of a file even if the target exists -k:: Skip move or rename actions which would lead to an error diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index b5f26ce..abfc6b6 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -8,7 +8,7 @@ git-prune-packed - Remove extra objects that are already in pack files SYNOPSIS -------- -'git prune-packed' [-n] [-q] +'git prune-packed' [-n|--dry-run] [-q|--quiet] DESCRIPTION @@ -28,10 +28,12 @@ disk storage, etc. OPTIONS ------- -n:: +--dry-run:: Don't actually remove any objects, only show those that would have been removed. -q:: +--quiet:: Squelch the progress indicator. Author diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 7578623..b932011 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -26,6 +26,10 @@ Also note that options meant for 'git-pull' itself and underlying OPTIONS ------- + +Options related to merging +~~~~~~~~~~~~~~~~~~~~~~~~~~ + include::merge-options.txt[] :git-pull: 1 @@ -47,6 +51,9 @@ unless you have read linkgit:git-rebase[1] carefully. --no-rebase:: Override earlier --rebase. +Options related to fetching +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + include::fetch-options.txt[] include::pull-fetch-param.txt[] @@ -131,54 +138,13 @@ $ git pull origin next ------------------------------------------------ + This leaves a copy of `next` temporarily in FETCH_HEAD, but -does not update any remote-tracking branches. - -* Bundle local branch `fixes` and `enhancements` on top of - the current branch, making an Octopus merge: -+ ------------------------------------------------- -$ git pull . fixes enhancements ------------------------------------------------- -+ -This `git pull .` syntax is equivalent to `git merge`. - -* Merge local branch `obsolete` into the current branch, using `ours` - merge strategy: -+ ------------------------------------------------- -$ git pull -s ours . obsolete ------------------------------------------------- - -* Merge local branch `maint` into the current branch, but do not make - a commit automatically: +does not update any remote-tracking branches. Using remote-tracking +branches, the same can be done by invoking fetch and merge: + ------------------------------------------------ -$ git pull --no-commit . maint +$ git fetch origin +$ git merge origin/next ------------------------------------------------ -+ -This can be used when you want to include further changes to the -merge, or want to write your own merge commit message. -+ -You should refrain from abusing this option to sneak substantial -changes into a merge commit. Small fixups like bumping -release/version name would be acceptable. - -* Command line pull of multiple branches from one repository: -+ ------------------------------------------------- -$ git checkout master -$ git fetch origin +pu:pu maint:tmp -$ git pull . tmp ------------------------------------------------- -+ -This updates (or creates, as necessary) branches `pu` and `tmp` in -the local repository by fetching from the branches (respectively) -`pu` and `maint` from the remote repository. -+ -The `pu` branch will be updated even if it is does not fast-forward; -the others will not be. -+ -The final command then merges the newly fetched `tmp` into master. If you tried a pull which resulted in a complex conflicts and diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 58d2bd5..37c8895 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -9,7 +9,7 @@ git-push - Update remote refs along with associated objects SYNOPSIS -------- [verse] -'git push' [--all | --mirror | --tags] [--dry-run] [--receive-pack=<git-receive-pack>] +'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] [--repo=<repository>] [-f | --force] [-v | --verbose] [<repository> <refspec>...] @@ -82,6 +82,7 @@ nor in any Push line of the corresponding remotes file---see below). if the configuration option `remote.<remote>.mirror` is set. +-n:: --dry-run:: Do everything except actually send the updates. @@ -137,6 +138,11 @@ useful if you write an alias or script around 'git-push'. --verbose:: Run verbosely. +-q:: +--quiet:: + Suppress all output, including the listing of updated refs, + unless an error occurs. + include::urls-remotes.txt[] OUTPUT diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index d4037de..579e8d2 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -9,7 +9,7 @@ git-quiltimport - Applies a quilt patchset onto the current branch SYNOPSIS -------- [verse] -'git quiltimport' [--dry-run] [--author <author>] [--patches <dir>] +'git quiltimport' [--dry-run | -n] [--author <author>] [--patches <dir>] DESCRIPTION diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 7160fa1..4a932b0 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,7 +8,10 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git read-tree' (<tree-ish> | [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) +'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] + [-u [--exclude-per-directory=<gitignore>] | -i]] + [--index-output=<file>] + <tree-ish1> [<tree-ish2> [<tree-ish3>]] DESCRIPTION diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index db1b71d..0aefc34 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -268,8 +268,9 @@ OPTIONS exit with the message "Current branch is up to date" in such a situation. +--ignore-whitespace:: --whitespace=<option>:: - This flag is passed to the 'git-apply' program + These flag are passed to the 'git-apply' program (see linkgit:git-apply[1]) that applies the patch. Incompatible with the --interactive option. diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt new file mode 100644 index 0000000..173ee23 --- /dev/null +++ b/Documentation/git-remote-helpers.txt @@ -0,0 +1,71 @@ +git-remote-helpers(1) +===================== + +NAME +---- +git-remote-helpers - Helper programs for interoperation with remote git + +SYNOPSIS +-------- +'git remote-<transport>' <remote> + +DESCRIPTION +----------- + +These programs are normally not used directly by end users, but are +invoked by various git programs that interact with remote repositories +when the repository they would operate on will be accessed using +transport code not linked into the main git binary. Various particular +helper programs will behave as documented here. + +COMMANDS +-------- + +Commands are given by the caller on the helper's standard input, one per line. + +'capabilities':: + Lists the capabilities of the helper, one per line, ending + with a blank line. + +'list':: + Lists the refs, one per line, in the format "<value> <name> + [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for + a symref, or "?" to indicate that the helper could not get the + value of the ref. A space-separated list of attributes follows + the name; unrecognized attributes are ignored. After the + complete list, outputs a blank line. + +'fetch' <sha1> <name>:: + Fetches the given object, writing the necessary objects to the + database. Outputs a blank line when the fetch is + complete. Only objects which were reported in the ref list + with a sha1 may be fetched this way. ++ +Supported if the helper has the "fetch" capability. + +If a fatal error occurs, the program writes the error message to +stderr and exits. The caller should expect that a suitable error +message has been printed if the child closes the connection without +completing a valid response for the current command. + +Additional commands may be supported, as may be determined from +capabilities reported by the helper. + +CAPABILITIES +------------ + +'fetch':: + This helper supports the 'fetch' command. + +REF LIST ATTRIBUTES +------------------- + +None are defined yet, but the caller must accept any which are supplied. + +Documentation +------------- +Documentation by Daniel Barkalow. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt new file mode 100644 index 0000000..915cb77 --- /dev/null +++ b/Documentation/git-replace.txt @@ -0,0 +1,71 @@ +git-replace(1) +============== + +NAME +---- +git-replace - Create, list, delete refs to replace objects + +SYNOPSIS +-------- +[verse] +'git replace' [-f] <object> <replacement> +'git replace' -d <object>... +'git replace' -l [<pattern>] + +DESCRIPTION +----------- +Adds a 'replace' reference in `.git/refs/replace/` + +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. + +OPTIONS +------- +-f:: + If an existing replace ref for the same object exists, it will + be overwritten (instead of failing). + +-d:: + Delete existing replace refs for the given objects. + +-l <pattern>:: + List replace refs for objects that match the given pattern (or + all if no pattern is given). + Typing "git replace" without arguments, also lists all replace + refs. + +BUGS +---- +Comparing blobs or trees that have been replaced with those that +replace them will not work properly. And using 'git reset --hard' to +go back to a replaced commit will move the branch to the replacement +commit instead of the replaced commit. + +There may be other problems when using 'git rev-list' related to +pending objects. And of course things may break if an object of one +type is replaced by an object of another type (for example a blob +replaced by a commit). + +SEE ALSO +-------- +linkgit:git-tag[1] +linkgit:git-branch[1] + +Author +------ +Written by Christian Couder <chriscool@tuxfamily.org> and Junio C +Hamano <gitster@pobox.com>, based on 'git tag' by Kristian Hogsberg +<krh@redhat.com> and Carlos Rica <jasampler@gmail.com>. + +Documentation +-------------- +Documentation by Christian Couder <chriscool@tuxfamily.org> and the +git-list <git@vger.kernel.org>, based on 'git tag' documentation. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index abb25d1..469cf6d 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -10,6 +10,7 @@ SYNOPSIS [verse] 'git reset' [--mixed | --soft | --hard | --merge] [-q] [<commit>] 'git reset' [-q] [<commit>] [--] <paths>... +'git reset' --patch [<commit>] [--] [<paths>...] DESCRIPTION ----------- @@ -23,8 +24,9 @@ the undo in the history. If you want to undo a commit other than the latest on a branch, linkgit:git-revert[1] is your friend. -The second form with 'paths' is used to revert selected paths in -the index from a given commit, without moving HEAD. +The second and third forms with 'paths' and/or --patch are used to +revert selected paths in the index from a given commit, without moving +HEAD. OPTIONS @@ -50,6 +52,15 @@ OPTIONS and updates the files that are different between the named commit and the current commit in the working tree. +-p:: +--patch:: + Interactively select hunks in the difference between the index + and <commit> (defaults to HEAD). The chosen hunks are applied + in reverse to the index. ++ +This means that `git reset -p` is the opposite of `git add -p` (see +linkgit:git-add[1]). + -q:: Be quiet, only report errors. diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 974d9f5..3341d1b 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -51,20 +51,26 @@ SYNOPSIS DESCRIPTION ----------- -Lists commit objects in reverse chronological order starting at the -given commit(s), taking ancestry relationship into account. This is -useful to produce human-readable log output. +List commits that are reachable by following the `parent` links from the +given commit(s), but exclude commits that are reachable from the one(s) +given with a '{caret}' in front of them. The output is given in reverse +chronological order by default. -Commits which are stated with a preceding '{caret}' cause listing to -stop at that point. Their parents are implied. Thus the following -command: +You can think of this as a set operation. Commits given on the command +line form a set of commits that are reachable from any of them, and then +commits reachable from any of the ones given with '{caret}' in front are +subtracted from that set. The remaining commits are what comes out in the +command's output. Various other options and paths parameters can be used +to further limit the result. + +Thus, the following command: ----------------------------------------------------------------------- $ git rev-list foo bar ^baz ----------------------------------------------------------------------- -means "list all the commits which are included in 'foo' and 'bar', but -not in 'baz'". +means "list all the commits which are reachable from 'foo' or 'bar', but +not from 'baz'". A special notation "'<commit1>'..'<commit2>'" can be used as a short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index d6b192b..767cf4d 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -142,8 +142,9 @@ user is prompted for a password while the input is masked for privacy. --smtp-server-port=<port>:: Specifies a port different from the default port (SMTP - servers typically listen to smtp port 25 and ssmtp port - 465); symbolic port names (e.g. "submission" instead of 465) + servers typically listen to smtp port 25, but may also listen to + submission port 587, or the common SSL smtp port 465); + symbolic port names (e.g. "submission" instead of 587) are also accepted. The port can also be set with the 'sendemail.smtpserverport' configuration variable. diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 89ec536..7343361 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -8,11 +8,12 @@ git-show-branch - Show branches and their commits SYNOPSIS -------- [verse] -'git show-branch' [--all] [--remotes] [--topo-order | --date-order] - [--current] [--color | --no-color] +'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order] + [--current] [--color | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [<rev> | <glob>]... + 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] DESCRIPTION @@ -81,9 +82,11 @@ OPTIONS Synonym to `--more=-1` --merge-base:: - Instead of showing the commit list, just act like the - 'git-merge-base -a' command, except that it can accept - more than two heads. + Instead of showing the commit list, determine possible + merge bases for the specified commits. All merge bases + will be contained in all specified commits. This is + different from how linkgit:git-merge-base[1] handles + the case of three or more commits. --independent:: Among the <reference>s given, display only the ones that diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 1c64a02..fafe728 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -13,7 +13,7 @@ SYNOPSIS 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [save [--keep-index] [-q|--quiet] [<message>]] +'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] [<message>]] 'git stash' clear 'git stash' create @@ -42,15 +42,27 @@ is also possible). OPTIONS ------- -save [--keep-index] [-q|--quiet] [<message>]:: +save [--patch] [--[no-]keep-index] [-q|--quiet] [<message>]:: Save your local modifications to a new 'stash', and run `git reset - --hard` to revert them. This is the default action when no - subcommand is given. The <message> part is optional and gives - the description along with the stashed state. + --hard` to revert them. The <message> part is optional and gives + the description along with the stashed state. For quickly making + a snapshot, you can omit _both_ "save" and <message>, but giving + only <message> does not trigger this action to prevent a misspelled + subcommand from making an unwanted stash. + If the `--keep-index` option is used, all changes already added to the index are left intact. ++ +With `--patch`, you can interactively select hunks from in 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 +of your repository, and its worktree contains only the changes you +selected interactively. The selected changes are then rolled back +from your worktree. ++ +The `--patch` option implies `--keep-index`. You can use +`--no-keep-index` to override this. list [<options>]:: @@ -66,7 +78,8 @@ stash@{1}: On master: 9cc0589... Add git-stash ---------------------------------------------------------------- + The command takes options applicable to the 'git-log' -command to control what is shown and how. See linkgit:git-log[1]. +command to control what is shown and how. If no options are set, the +default is `-n 10`. See linkgit:git-log[1]. show [<stash>]:: @@ -114,7 +127,8 @@ no conflicts. clear:: Remove all the stashed states. Note that those states will then - be subject to pruning, and may be difficult or impossible to recover. + be subject to pruning, and may be impossible to recover (see + 'Examples' below for a possible strategy). drop [-q|--quiet] [<stash>]:: @@ -217,6 +231,20 @@ $ edit/build/test remaining parts $ git commit foo -m 'Remaining parts' ---------------------------------------------------------------- +Recovering stashes that were cleared/dropped erroneously:: + +If you mistakenly drop or clear stashes, they cannot be recovered +through the normal safety mechanisms. However, you can try the +following incantation to get a list of stashes that are still in your +repository, but not reachable any more: ++ +---------------------------------------------------------------- +git fsck --unreachable | +grep commit | cut -d\ -f3 | +xargs git log --merges --no-walk --grep=WIP +---------------------------------------------------------------- + + SEE ALSO -------- linkgit:git-checkout[1], diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 7dd73ae..5ccdd18 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -11,12 +11,12 @@ SYNOPSIS [verse] 'git submodule' [--quiet] add [-b branch] [--reference <repository>] [--] <repository> <path> -'git submodule' [--quiet] status [--cached] [--] [<path>...] +'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] - [--reference <repository>] [--merge] [--] [<path>...] -'git submodule' [--quiet] summary [--cached] [--summary-limit <n>] [commit] [--] [<path>...] -'git submodule' [--quiet] foreach <command> + [--reference <repository>] [--merge] [--recursive] [--] [<path>...] +'git submodule' [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...] +'git submodule' [--quiet] foreach [--recursive] <command> 'git submodule' [--quiet] sync [--] [<path>...] @@ -100,6 +100,9 @@ status:: initialized and `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing repository. This command is the default command for 'git-submodule'. ++ +If '--recursive' is specified, this command will recurse into nested +submodules, and show their status as well. init:: Initialize the submodules, i.e. register each submodule name @@ -122,21 +125,31 @@ update:: If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the submodule with the --init option. ++ +If '--recursive' is specified, this command will recurse into the +registered submodules, and update any nested submodules within. summary:: Show commit summary between the given commit (defaults to HEAD) and working tree/index. For a submodule in question, a series of commits in the submodule between the given super project commit and the - index or working tree (switched by --cached) are shown. + index or working tree (switched by --cached) are shown. If the option + --files is given, show the series of commits in the submodule between + the index of the super project and the working tree of the submodule + (this option doesn't allow to use the --cached option or to provide an + explicit commit). foreach:: Evaluates an arbitrary shell command in each checked out submodule. - The command has access to the variables $path and $sha1: + The command has access to the variables $name, $path and $sha1: + $name is the name of the relevant submodule section in .gitmodules, $path is the name of the submodule directory relative to the superproject, and $sha1 is the commit as recorded in the superproject. Any submodules defined in the superproject but not checked out are ignored by this command. Unless given --quiet, foreach prints the name of each submodule before evaluating the command. + If --recursive is given, submodules are traversed recursively (i.e. + the given shell command is evaluated in nested submodules as well). A non-zero return from the command in any submodule causes the processing to terminate. This can be overridden by adding '|| :' to the end of the command. @@ -169,6 +182,11 @@ OPTIONS commands typically use the commit found in the submodule HEAD, but with this option, the commit stored in the index is used instead. +--files:: + This option is only valid for the summary command. This command + compares the commit in the index with that in the submodule HEAD + when this option is used. + -n:: --summary-limit:: This option is only valid for the summary command. @@ -209,6 +227,12 @@ OPTIONS *NOTE*: Do *not* use this option unless you have read the note for linkgit:git-clone[1]'s --reference and --shared options carefully. +--recursive:: + This option is only valid for foreach, update and status commands. + Traverse submodules recursively. The operation is performed not + only in the submodules of the current repo, but also + in any nested submodules inside those submodules (and so on). + <path>...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 22a0389..1812890 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -102,9 +102,6 @@ COMMANDS Store Git commit times in the local timezone instead of UTC. This makes 'git log' (even without --date=local) show the same times that `svn log` would in the local timezone. - ---parent;; - Fetch only from the SVN parent of the current HEAD. + This doesn't interfere with interoperating with the Subversion repository you cloned from, but if you wish for your local Git @@ -112,6 +109,9 @@ repository to be able to interoperate with someone else's local Git repository, either don't use this option or you should both use it in the same local timezone. +--parent;; + Fetch only from the SVN parent of the current HEAD. + --ignore-paths=<regex>;; This allows one to specify a Perl regular expression that will cause skipping of all matching paths from checkout from SVN. diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index fa73321..299b04f 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -10,14 +10,15 @@ SYNOPSIS -------- [verse] 'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] - <name> [<commit> | <object>] -'git tag' -d <name>... + <tagname> [<commit> | <object>] +'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>] -'git tag' -v <name>... +'git tag' -v <tagname>... DESCRIPTION ----------- -Adds a 'tag' reference in `.git/refs/tags/` + +Adds a tag reference in `.git/refs/tags/`. Unless `-f` is given, the tag must not yet exist in `.git/refs/tags/` directory. @@ -50,6 +51,7 @@ OPTIONS Make a GPG-signed tag, using the given key -f:: +--force:: Replace an existing tag with the given name (instead of failing) -d:: @@ -85,6 +87,12 @@ OPTIONS Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. +<tagname>:: + The name of the tag to create, delete, or describe. + The new tag name must pass all checks defined by + linkgit:git-check-ref-format[1]. Some of these checks + may restrict the characters allowed in a tag name. + CONFIGURATION ------------- By default, 'git-tag' in sign-with-default mode (-s) will use your @@ -249,6 +257,10 @@ $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 ------------ +SEE ALSO +-------- +linkgit:git-check-ref-format[1]. + Author ------ Written by Linus Torvalds <torvalds@osdl.org>, diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index b8e49dc..63f3b5c 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -20,6 +20,8 @@ The UI for the protocol is on the 'git-fetch-pack' side, and the program pair is meant to be used to pull updates from a remote repository. For push operations, see 'git-send-pack'. +After finishing the operation successfully, `post-upload-pack` +hook is called (see linkgit:githooks[5]). OPTIONS ------- diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index c861163..97f7f91 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -8,7 +8,7 @@ git-verify-pack - Validate packed git archive files SYNOPSIS -------- -'git verify-pack' [-v] [--] <pack>.idx ... +'git verify-pack' [-v|--verbose] [--] <pack>.idx ... DESCRIPTION @@ -23,8 +23,15 @@ OPTIONS The idx files to verify. -v:: +--verbose:: After verifying the pack, show list of objects contained - in the pack. + in the pack and a histogram of delta chain length. + +-s:: +--stat-only:: + Do not verify the pack contents; only show the histogram of delta + chain length. With `--verbose`, list of objects is also shown. + \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git.txt b/Documentation/git.txt index f91cabb..e3fe970 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,17 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.6.4.3/git.html[documentation for release 1.6.4.3] +* link:v1.6.5.2/git.html[documentation for release 1.6.5.2] * release notes for + link:RelNotes-1.6.5.2.txt[1.6.5.2], + link:RelNotes-1.6.5.1.txt[1.6.5.1], + link:RelNotes-1.6.5.txt[1.6.5]. + +* link:v1.6.4.4/git.html[documentation for release 1.6.4.4] + +* release notes for + link:RelNotes-1.6.4.4.txt[1.6.4.4], link:RelNotes-1.6.4.3.txt[1.6.4.3], link:RelNotes-1.6.4.2.txt[1.6.4.2], link:RelNotes-1.6.4.1.txt[1.6.4.1], diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 1195e83..1f472ce 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -560,6 +560,16 @@ in the file. E.g. the string `$Format:%H$` will be replaced by the commit hash. +Packing objects +~~~~~~~~~~~~~~~ + +`delta` +^^^^^^^ + +Delta compression will not be attempted for blobs for paths with the +attribute `delta` set to false. + + Viewing files in GUI tools ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index be39ed7..6928724 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -81,7 +81,7 @@ couple of magic command line options: + --------------------------------------------- $ git describe -h -usage: git-describe [options] <committish>* +usage: git describe [options] <committish>* --contains find the tag that comes after the commit --debug debug search strategy on stderr diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index acc408d..06e0f31 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -245,7 +245,7 @@ Both standard output and standard error output are forwarded to for the user. The default 'update' hook, when enabled--and with -`hooks.allowunannotated` config option turned on--prevents +`hooks.allowunannotated` config option unset or set to false--prevents unannotated tags to be pushed. [[post-receive]] @@ -310,6 +310,35 @@ Both standard output and standard error output are forwarded to 'git-send-pack' on the other end, so you can simply `echo` messages for the user. +post-upload-pack +---------------- + +After upload-pack successfully finishes its operation, this hook is called +for logging purposes. + +The hook is passed various pieces of information, one per line, from its +standard input. Currently the following items can be fed to the hook, but +more types of information may be added in the future: + +want SHA-1:: + 40-byte hexadecimal object name the client asked to include in the + resulting pack. Can occur one or more times in the input. + +have SHA-1:: + 40-byte hexadecimal object name the client asked to exclude from + the resulting pack, claiming to have them already. Can occur zero + or more times in the input. + +time float:: + Number of seconds spent for creating the packfile. + +size decimal:: + Size of the resulting packfile in bytes. + +kind string: + Either "clone" (when the client did not give us any "have", and asked + for all our refs with "want"), or "fetch" (otherwise). + pre-auto-gc ~~~~~~~~~~~ diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 572374f..43d84d1 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -456,6 +456,6 @@ This commit is referred to as a "merge commit", or sometimes just a of 'A' is 'origin/B' sometimes we say "'A' is tracking 'origin/B'". [[def_working_tree]]working tree:: - The tree of actual checked out files. The working tree is - normally equal to the <<def_HEAD,HEAD>> plus any local changes - that you have made but not yet committed. + The tree of actual checked out files. The working tree normally + contains the contents of the <<def_HEAD,HEAD>> commit's tree, + plus any local changes that you have made but not yet committed. diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl new file mode 100644 index 0000000..aeb8839 --- /dev/null +++ b/Documentation/manpage-quote-apos.xsl @@ -0,0 +1,16 @@ +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- work around newer groff/man setups using a prettier apostrophe + that unfortunately does not quote anything when cut&pasting + examples to the shell --> +<xsl:template name="escape.apostrophe"> + <xsl:param name="content"/> + <xsl:call-template name="string.subst"> + <xsl:with-param name="string" select="$content"/> + <xsl:with-param name="target">'</xsl:with-param> + <xsl:with-param name="replacement">\(aq</xsl:with-param> + </xsl:call-template> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index adadf8e..48d04a5 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -1,43 +1,42 @@ --q:: ---quiet:: - Operate quietly. - --v:: ---verbose:: - Be verbose. - ---stat:: - Show a diffstat at the end of the merge. The diffstat is also - controlled by the configuration option merge.stat. - --n:: ---no-stat:: - Do not show a diffstat at the end of the merge. +--commit:: +--no-commit:: + Perform the merge and commit the result. This option can + be used to override --no-commit. ++ +With --no-commit perform the merge but pretend the merge +failed and do not autocommit, to give the user a chance to +inspect and further tweak the merge result before committing. ---summary:: ---no-summary:: - Synonyms to --stat and --no-stat; these are deprecated and will be - removed in the future. +--ff:: +--no-ff:: + Do not generate a merge commit if the merge resolved as + a fast-forward, only update the branch pointer. This is + the default behavior of git-merge. ++ +With --no-ff Generate a merge commit even if the merge +resolved as a fast-forward. --log:: +--no-log:: In addition to branch names, populate the log message with one-line descriptions from the actual commits that are being merged. ++ +With --no-log do not list one-line descriptions from the +actual commits being merged. ---no-log:: - Do not list one-line descriptions from the actual commits being - merged. - ---no-commit:: - Perform the merge but pretend the merge failed and do - not autocommit, to give the user a chance to inspect and - further tweak the merge result before committing. ---commit:: - Perform the merge and commit the result. This option can - be used to override --no-commit. +--stat:: +-n:: +--no-stat:: + Show a diffstat at the end of the merge. The diffstat is also + controlled by the configuration option merge.stat. ++ +With -n or --no-stat do not show a diffstat at the end of the +merge. --squash:: +--no-squash:: Produce the working tree and index state as if a real merge happened (except for the merge information), but do not actually make a commit or @@ -46,19 +45,9 @@ commit. This allows you to create a single commit on top of the current branch whose effect is the same as merging another branch (or more in case of an octopus). - ---no-squash:: - Perform the merge and commit the result. This option can - be used to override --squash. - ---no-ff:: - Generate a merge commit even if the merge resolved as a - fast-forward. - ---ff:: - Do not generate a merge commit if the merge resolved as - a fast-forward, only update the branch pointer. This is - the default behavior of git-merge. ++ +With --no-squash perform the merge and commit the result. This +option can be used to override --squash. -s <strategy>:: --strategy=<strategy>:: @@ -67,3 +56,16 @@ If there is no `-s` option, a built-in list of strategies is used instead ('git-merge-recursive' when merging a single head, 'git-merge-octopus' otherwise). + +--summary:: +--no-summary:: + Synonyms to --stat and --no-stat; these are deprecated and will be + removed in the future. + +-q:: +--quiet:: + Operate quietly. + +-v:: +--verbose:: + Be verbose. diff --git a/Documentation/pt_BR/gittutorial.txt b/Documentation/pt_BR/gittutorial.txt new file mode 100644 index 0000000..81e7ad7 --- /dev/null +++ b/Documentation/pt_BR/gittutorial.txt @@ -0,0 +1,675 @@ +gittutorial(7) +============== + +NAME +---- +gittutorial - Um tutorial de introdução ao git (para versão 1.5.1 ou mais nova) + +SYNOPSIS +-------- +git * + +DESCRIPTION +----------- + +Este tutorial explica como importar um novo projeto para o git, +adicionar mudanças a ele, e compartilhar mudanças com outros +desenvolvedores. + +Se, ao invés disso, você está interessado primariamente em usar git para +obter um projeto, por exemplo, para testar a última versão, você pode +preferir começar com os primeiros dois capítulos de +link:user-manual.html[O Manual do Usuário Git]. + +Primeiro, note que você pode obter documentação para um comando como +`git log --graph` com: + +------------------------------------------------ +$ man git-log +------------------------------------------------ + +ou: + +------------------------------------------------ +$ git help log +------------------------------------------------ + +Com a última forma, você pode usar o visualizador de manual de sua +escolha; veja linkgit:git-help[1] para maior informação. + +É uma boa idéia informar ao git seu nome e endereço público de email +antes de fazer qualquer operação. A maneira mais fácil de fazê-lo é: + +------------------------------------------------ +$ git config --global user.name "Seu Nome Vem Aqui" +$ git config --global user.email voce@seudominio.exemplo.com +------------------------------------------------ + + +Importando um novo projeto +----------------------- + +Assuma que você tem um tarball project.tar.gz com seu trabalho inicial. +Você pode colocá-lo sob controle de revisão git da seguinte forma: + +------------------------------------------------ +$ tar xzf project.tar.gz +$ cd project +$ git init +------------------------------------------------ + +Git irá responder + +------------------------------------------------ +Initialized empty Git repository in .git/ +------------------------------------------------ + +Você agora iniciou seu diretório de trabalho--você deve ter notado um +novo diretório criado, com o nome de ".git". + +A seguir, diga ao git para gravar um instantâneo do conteúdo de todos os +arquivos sob o diretório corrente (note o '.'), com 'git-add': + +------------------------------------------------ +$ git add . +------------------------------------------------ + +Este instantâneo está agora armazenado em uma área temporária que o git +chama de "index" ou índice. Você pode armazenar permanentemente o +conteúdo do índice no repositório com 'git-commit': + +------------------------------------------------ +$ git commit +------------------------------------------------ + +Isto vai te pedir por uma mensagem de commit. Você agora gravou sua +primeira versão de seu projeto no git. + +Fazendo mudanças +-------------- + +Modifique alguns arquivos, e, então, adicione seu conteúdo atualizado ao +índice: + +------------------------------------------------ +$ git add file1 file2 file3 +------------------------------------------------ + +Você está agora pronto para fazer o commit. Você pode ver o que está +para ser gravado usando 'git-diff' com a opção --cached: + +------------------------------------------------ +$ git diff --cached +------------------------------------------------ + +(Sem --cached, o comando 'git-diff' irá te mostrar quaisquer mudanças +que você tenha feito mas ainda não adicionou ao índice.) Você também +pode obter um breve sumário da situação com 'git-status': + +------------------------------------------------ +$ git status +# On branch master +# Changes to be committed: +# (use "git reset HEAD <file>..." to unstage) +# +# modified: file1 +# modified: file2 +# modified: file3 +# +------------------------------------------------ + +Se você precisar fazer qualquer outro ajuste, faça-o agora, e, então, +adicione qualquer conteúdo modificado ao índice. Finalmente, grave suas +mudanças com: + +------------------------------------------------ +$ git commit +------------------------------------------------ + +Isto irá novamente te pedir por uma mensagem descrevendo a mudança, e, +então, gravar a nova versão do projeto. + +Alternativamente, ao invés de executar 'git-add' antes, você pode usar + +------------------------------------------------ +$ git commit -a +------------------------------------------------ + +o que irá automaticamente notar quaisquer arquivos modificados (mas não +novos), adicioná-los ao índices, e gravar, tudo em um único passo. + +Uma nota em mensagens de commit: Apesar de não ser exigido, é uma boa +idéia começar a mensagem com uma simples e curta (menos de 50 +caracteres) linha sumarizando a mudança, seguida de uma linha em branco +e, então, uma descrição mais detalhada. Ferramentas que transformam +commits em email, por exemplo, usam a primeira linha no campo de +cabeçalho Subject: e o resto no corpo. + +Git rastreia conteúdo, não arquivos +---------------------------- + +Muitos sistemas de controle de revisão provêem um comando `add` que diz +ao sistema para começar a rastrear mudanças em um novo arquivo. O +comando `add` do git faz algo mais simples e mais poderoso: 'git-add' é +usado tanto para arquivos novos e arquivos recentemente modificados, e +em ambos os casos, ele tira o instantâneo dos arquivos dados e armazena +o conteúdo no índice, pronto para inclusão do próximo commit. + +Visualizando história do projeto +----------------------- + +Em qualquer ponto você pode visualizar a história das suas mudanças +usando + +------------------------------------------------ +$ git log +------------------------------------------------ + +Se você também quer ver a diferença completa a cada passo, use + +------------------------------------------------ +$ git log -p +------------------------------------------------ + +Geralmente, uma visão geral da mudança é útil para ter a sensação de +cada passo + +------------------------------------------------ +$ git log --stat --summary +------------------------------------------------ + +Gerenciando "branches"/ramos +----------------- + +Um simples repositório git pode manter múltiplos ramos de +desenvolvimento. Para criar um novo ramo chamado "experimental", use + +------------------------------------------------ +$ git branch experimental +------------------------------------------------ + +Se você executar agora + +------------------------------------------------ +$ git branch +------------------------------------------------ + +você vai obter uma lista de todos os ramos existentes: + +------------------------------------------------ + experimental +* master +------------------------------------------------ + +O ramo "experimental" é o que você acaba de criar, e o ramo "master" é o +ramo padrão que foi criado pra você automaticamente. O asterisco marca +o ramo em que você está atualmente; digite + +------------------------------------------------ +$ git checkout experimental +------------------------------------------------ + +para mudar para o ramo experimental. Agora edite um arquivo, grave a +mudança, e mude de volta para o ramo master: + +------------------------------------------------ +(edita arquivo) +$ git commit -a +$ git checkout master +------------------------------------------------ + +Verifique que a mudança que você fez não está mais visível, já que ela +foi feita no ramo experimental e você está de volta ao ramo master. + +Você pode fazer uma mudança diferente no ramo master: + +------------------------------------------------ +(edit file) +$ git commit -a +------------------------------------------------ + +neste ponto, os dois ramos divergiram, com diferentes mudanças feitas em +cada um. Para unificar as mudanças feitas no experimental para o +master, execute + +------------------------------------------------ +$ git merge experimental +------------------------------------------------ + +Se as mudanças não conflitarem, estará pronto. Se existirem conflitos, +marcadores serão deixados nos arquivos problemáticos exibindo o +conflito; + +------------------------------------------------ +$ git diff +------------------------------------------------ + +vai exibir isto. Após você editar os arquivos para resolver os +conflitos, + +------------------------------------------------ +$ git commit -a +------------------------------------------------ + +irá gravar o resultado da unificação. Finalmente, + +------------------------------------------------ +$ gitk +------------------------------------------------ + +vai mostrar uma bela representação gráfica da história resultante. + +Neste ponto você pode remover seu ramo experimental com + +------------------------------------------------ +$ git branch -d experimental +------------------------------------------------ + +Este comando garante que as mudanças no ramo experimental já estão no +ramo atual. + +Se você desenvolve em um ramo ideia-louca, e se arrepende, você pode +sempre remover o ramo com + +------------------------------------- +$ git branch -D ideia-louca +------------------------------------- + +Ramos são baratos e fáceis, então isto é uma boa maneira de experimentar +alguma coisa. + +Usando git para colaboração +--------------------------- + +Suponha que Alice começou um novo projeto com um repositório git em +/home/alice/project, e que Bob, que tem um diretório home na mesma +máquina, quer contribuir. + +Bob começa com: + +------------------------------------------------ +bob$ git clone /home/alice/project myrepo +------------------------------------------------ + +Isso cria um novo diretório "myrepo" contendo um clone do repositório de +Alice. O clone está no mesmo pé que o projeto original, possuindo sua +própria cópia da história do projeto original. + +Bob então faz algumas mudanças e as grava: + +------------------------------------------------ +(editar arquivos) +bob$ git commit -a +(repetir conforme necessário) +------------------------------------------------ + +Quanto está pronto, ele diz a Alice para puxar as mudanças do +repositório em /home/bob/myrepo. Ela o faz com: + +------------------------------------------------ +alice$ cd /home/alice/project +alice$ git pull /home/bob/myrepo master +------------------------------------------------ + +Isto unifica as mudanças do ramo "master" do Bob ao ramo atual de Alice. +Se Alice fez suas próprias mudanças no intervalo, ela, então, pode +precisar corrigir manualmente quaisquer conflitos. (Note que o argumento +"master" no comando acima é, de fato, desnecessário, já que é o padrão.) + +O comando "pull" executa, então, duas operações: ele obtém mudanças de +um ramo remoto, e, então, as unifica no ramo atual. + +Note que, em geral, Alice gostaria que suas mudanças locais fossem +gravadas antes de iniciar este "pull". Se o trabalho de Bob conflita +com o que Alice fez desde que suas histórias se ramificaram, Alice irá +usar seu diretório de trabalho e o índice para resolver conflitos, e +mudanças locais existentes irão interferir com o processo de resolução +de conflitos (git ainda irá realizar a obtenção mas irá se recusar a +unificar --- Alice terá que se livrar de suas mudanças locais de alguma +forma e puxar de novo quando isso acontecer). + +Alice pode espiar o que Bob fez sem unificar primeiro, usando o comando +"fetch"; isto permite Alice inspecionar o que Bob fez, usando um símbolo +especial "FETCH_HEAD", com o fim de determinar se ele tem alguma coisa +que vale puxar, assim: + +------------------------------------------------ +alice$ git fetch /home/bob/myrepo master +alice$ git log -p HEAD..FETCH_HEAD +------------------------------------------------ + +Esta operação é segura mesmo se Alice tem mudanças locais não gravadas. +A notação de intervalo "HEAD..FETCH_HEAD" significa mostrar tudo que é +alcançável de FETCH_HEAD mas exclua tudo o que é alcançável de HEAD. +Alice já sabe tudo que leva a seu estado atual (HEAD), e revisa o que Bob +tem em seu estado (FETCH_HEAD) que ela ainda não viu com esse comando. + +Se Alice quer visualizar o que Bob fez desde que suas histórias se +ramificaram, ela pode disparar o seguinte comando: + +------------------------------------------------ +$ gitk HEAD..FETCH_HEAD +------------------------------------------------ + +Isto usa a mesma notação de intervalo que vimos antes com 'git log'. + +Alice pode querer ver o que ambos fizeram desde que ramificaram. Ela +pode usar a forma com três pontos ao invés da forma com dois pontos: + +------------------------------------------------ +$ gitk HEAD...FETCH_HEAD +------------------------------------------------ + +Isto significa "mostre tudo que é alcançável de qualquer um deles, mas +exclua tudo que é alcançável a partir de ambos". + +Por favor, note que essas notações de intervalo podem ser usadas tanto +com gitk quanto com "git log". + +Após inspecionar o que Bob fez, se não há nada urgente, Alice pode +decidir continuar trabalhando sem puxar de Bob. Se a história de Bob +tem alguma coisa que Alice precisa imediatamente, Alice pode optar por +separar seu trabalho em progresso primeiro, fazer um "pull", e, então, +finalmente, retomar seu trabalho em progresso em cima da história +resultante. + +Quando você está trabalhando em um pequeno grupo unido, não é incomum +interagir com o mesmo repositório várias e várias vezes. Definindo um +repositório remoto antes de tudo, você pode fazê-lo mais facilmente: + +------------------------------------------------ +alice$ git remote add bob /home/bob/myrepo +------------------------------------------------ + +Com isso, Alice pode executar a primeira parte da operação "pull" usando +o comando 'git-fetch' sem unificar suas mudanças com seu próprio ramo, +usando: + +------------------------------------- +alice$ git fetch bob +------------------------------------- + +Diferente da forma longa, quando Alice obteve de Bob usando um +repositório remoto antes definido com 'git-remote', o que foi obtido é +armazenado em um ramo remoto, neste caso `bob/master`. Então, após isso: + +------------------------------------- +alice$ git log -p master..bob/master +------------------------------------- + +mostra uma lista de todas as mudanças que Bob fez desde que ramificou do +ramo master de Alice. + +Após examinar essas mudanças, Alice pode unificá-las em seu ramo master: + +------------------------------------- +alice$ git merge bob/master +------------------------------------- + +Esse `merge` pode também ser feito puxando de seu próprio ramo remoto, +assim: + +------------------------------------- +alice$ git pull . remotes/bob/master +------------------------------------- + +Note que 'git pull' sempre unifica ao ramo atual, independente do que +mais foi passado na linha de comando. + +Depois, Bob pode atualizar seu repositório com as últimas mudanças de +Alice, usando + +------------------------------------- +bob$ git pull +------------------------------------- + +Note que ele não precisa dar o caminho do repositório de Alice; quando +Bob clonou seu repositório, o git armazenou a localização de seu +repositório na configuração do mesmo, e essa localização é usada +para puxar: + +------------------------------------- +bob$ git config --get remote.origin.url +/home/alice/project +------------------------------------- + +(A configuração completa criada por 'git-clone' é visível usando `git +config -l`, e a página de manual linkgit:git-config[1] explica o +significado de cada opção.) + +Git também mantém uma cópia limpa do ramo master de Alice sob o nome +"origin/master": + +------------------------------------- +bob$ git branch -r + origin/master +------------------------------------- + +Se Bob decidir depois em trabalhar em um host diferente, ele ainda pode +executar clones e puxar usando o protocolo ssh: + +------------------------------------- +bob$ git clone alice.org:/home/alice/project myrepo +------------------------------------- + +Alternativamente, o git tem um protocolo nativo, ou pode usar rsync ou +http; veja linkgit:git-pull[1] para detalhes. + +Git pode também ser usado em um modo parecido com CVS, com um +repositório central para o qual vários usuários empurram modificações; +veja linkgit:git-push[1] e linkgit:gitcvs-migration[7]. + +Explorando história +----------------- + +A história no git é representada como uma série de commits +interrelacionados. Nós já vimos que o comando 'git-log' pode listar +esses commits. Note que a primeira linha de cada entrada no log também +dá o nome para o commit: + +------------------------------------- +$ git log +commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 +Author: Junio C Hamano <junkio@cox.net> +Date: Tue May 16 17:18:22 2006 -0700 + + merge-base: Clarify the comments on post processing. +------------------------------------- + +Nós podemos dar este nome ao 'git-show' para ver os detalhes sobre este +commit. + +------------------------------------- +$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 +------------------------------------- + +Mas há outras formas de se referir aos commits. Você pode usar qualquer +parte inicial do nome que seja longo o bastante para identificar +unicamente o commit: + +------------------------------------- +$ git show c82a22c39c # os primeiros caracteres do nome são o bastante + # usualmente +$ git show HEAD # a ponta do ramo atual +$ git show experimental # a ponta do ramo "experimental" +------------------------------------- + +Todo commit normalmente tem um commit "pai" que aponta para o estado +anterior do projeto: + +------------------------------------- +$ git show HEAD^ # para ver o pai de HEAD +$ git show HEAD^^ # para ver o avô de HEAD +$ git show HEAD~4 # para ver o trisavô de HEAD +------------------------------------- + +Note que commits de unificação podem ter mais de um pai: + +------------------------------------- +$ git show HEAD^1 # mostra o primeiro pai de HEAD (o mesmo que HEAD^) +$ git show HEAD^2 # mostra o segundo pai de HEAD +------------------------------------- + +Você também pode dar aos commits nomes à sua escolha; após executar + +------------------------------------- +$ git tag v2.5 1b2e1d63ff +------------------------------------- + +você pode se referir a 1b2e1d63ff pelo nome "v2.5". Se você pretende +compartilhar esse nome com outras pessoas (por exemplo, para identificar +uma versão de lançamento), você deveria criar um objeto "tag", e talvez +assiná-lo; veja linkgit:git-tag[1] para detalhes. + +Qualquer comando git que precise conhecer um commit pode receber +quaisquer desses nomes. Por exemplo: + +------------------------------------- +$ git diff v2.5 HEAD # compara o HEAD atual com v2.5 +$ git branch stable v2.5 # inicia um novo ramo chamado "stable" baseado + # em v2.5 +$ git reset --hard HEAD^ # reseta seu ramo atual e seu diretório de + # trabalho a seu estado em HEAD^ +------------------------------------- + +Seja cuidadoso com o último comando: além de perder quaisquer mudanças +em seu diretório de trabalho, ele também remove todos os commits +posteriores desse ramo. Se esse ramo é o único ramo contendo esses +commits, eles serão perdidos. Também, não use 'git-reset' num ramo +publicamente visível de onde outros desenvolvedores puxam, já que vai +forçar unificações desnecessárias para que outros desenvolvedores limpem +a história. Se você precisa desfazer mudanças que você empurrou, use +'git-revert' no lugar. + +O comando 'git-grep' pode buscar strings em qualquer versão de seu +projeto, então + +------------------------------------- +$ git grep "hello" v2.5 +------------------------------------- + +procura por todas as ocorrências de "hello" em v2.5. + +Se você deixar de fora o nome do commit, 'git-grep' irá procurar +quaisquer dos arquivos que ele gerencia no diretório corrente. Então + +------------------------------------- +$ git grep "hello" +------------------------------------- + +é uma forma rápida de buscar somente os arquivos que são rastreados pelo +git. + +Muitos comandos git também recebem um conjunto de commits, o que pode +ser especificado de várias formas. Aqui estão alguns exemplos com 'git-log': + +------------------------------------- +$ git log v2.5..v2.6 # commits entre v2.5 e v2.6 +$ git log v2.5.. # commits desde v2.5 +$ git log --since="2 weeks ago" # commits das últimas 2 semanas +$ git log v2.5.. Makefile # commits desde v2.5 que modificam + # Makefile +------------------------------------- + +Você também pode dar ao 'git-log' um "intervalo" de commits onde o +primeiro não é necessariamente um ancestral do segundo; por exemplo, se +as pontas dos ramos "stable" e "master" divergiram de um commit +comum algum tempo atrás, então + +------------------------------------- +$ git log stable..master +------------------------------------- + +irá listar os commits feitos no ramo "master" mas não no ramo +"stable", enquanto + +------------------------------------- +$ git log master..stable +------------------------------------- + +irá listar a lista de commits feitos no ramo "stable" mas não no ramo +"master". + +O comando 'git-log' tem uma fraqueza: ele precisa mostrar os commits em +uma lista. Quando a história tem linhas de desenvolvimento que +divergiram e então foram unificadas novamente, a ordem em que 'git-log' +apresenta essas mudanças é irrelevante. + +A maioria dos projetos com múltiplos contribuidores (como o kernel +Linux, ou o próprio git) tem unificações frequentes, e 'gitk' faz um +trabalho melhor de visualizar sua história. Por exemplo, + +------------------------------------- +$ gitk --since="2 weeks ago" drivers/ +------------------------------------- + +permite a você navegar em quaisquer commits desde as últimas duas semanas +de commits que modificaram arquivos sob o diretório "drivers". (Nota: +você pode ajustar as fontes do gitk segurando a tecla control enquanto +pressiona "-" ou "+".) + +Finalmente, a maioria dos comandos que recebem nomes de arquivo permitirão +também, opcionalmente, preceder qualquer nome de arquivo por um +commit, para especificar uma versão particular do arquivo: + +------------------------------------- +$ git diff v2.5:Makefile HEAD:Makefile.in +------------------------------------- + +Você pode usar 'git-show' para ver tal arquivo: + +------------------------------------- +$ git show v2.5:Makefile +------------------------------------- + +Próximos passos +---------- + +Este tutorial deve ser o bastante para operar controle de revisão +distribuído básico para seus projetos. No entanto, para entender +plenamente a profundidade e o poder do git você precisa entender duas +idéias simples nas quais ele se baseia: + + * A base de objetos é um sistema bem elegante usado para armazenar a + história de seu projeto--arquivos, diretórios, e commits. + + * O arquivo de índice é um cache do estado de uma árvore de diretório, + usado para criar commits, restaurar diretórios de trabalho, e + armazenar as várias árvores envolvidas em uma unificação. + +A parte dois deste tutorial explica a base de objetos, o arquivo de +índice, e algumas outras coisinhas que você vai precisar pra usar o +máximo do git. Você pode encontrá-la em linkgit:gittutorial-2[7]. + +Se você não quiser continuar com o tutorial agora nesse momento, algumas +outras digressões que podem ser interessantes neste ponto são: + + * linkgit:git-format-patch[1], linkgit:git-am[1]: Estes convertem + séries de commits em patches para email, e vice-versa, úteis para + projetos como o kernel Linux que dependem fortemente de patches + enviados por email. + + * linkgit:git-bisect[1]: Quando há uma regressão em seu projeto, uma + forma de rastrear um bug é procurando pela história para encontrar o + commit culpado. Git bisect pode ajudar a executar uma busca binária + por esse commit. Ele é inteligente o bastante para executar uma + busca próxima da ótima mesmo no caso de uma história complexa + não-linear com muitos ramos unificados. + + * link:everyday.html[GIT diariamente com 20 e tantos comandos] + + * linkgit:gitcvs-migration[7]: Git para usuários de CVS. + +VEJA TAMBÉM +-------- +linkgit:gittutorial-2[7], +linkgit:gitcvs-migration[7], +linkgit:gitcore-tutorial[7], +linkgit:gitglossary[7], +linkgit:git-help[1], +link:everyday.html[git diariamente], +link:user-manual.html[O Manual do Usuário git] + +GIT +--- +Parte da suite linkgit:git[1]. diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 2efe7a4..b26c281 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -35,12 +35,32 @@ Functions Convenience functions that encapsulate a sequence of start_command() followed by finish_command(). The argument argv specifies the program and its arguments. The argument opt is zero - or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, or - `RUN_COMMAND_STDOUT_TO_STDERR` that correspond to the members - .no_stdin, .git_cmd, .stdout_to_stderr of `struct child_process`. + or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, + `RUN_COMMAND_STDOUT_TO_STDERR`, or `RUN_SILENT_EXEC_FAILURE` + that correspond to the members .no_stdin, .git_cmd, + .stdout_to_stderr, .silent_exec_failure of `struct child_process`. The argument dir corresponds the member .dir. The argument env corresponds to the member .env. +The functions above do the following: + +. If a system call failed, errno is set and -1 is returned. A diagnostic + is printed. + +. If the program was not found, then -1 is returned and errno is set to + ENOENT; a diagnostic is printed only if .silent_exec_failure is 0. + +. Otherwise, the program is run. If it terminates regularly, its exit + code is returned. No diagnistic is printed, even if the exit code is + non-zero. + +. If the program terminated due to a signal, then the return value is the + signal number - 128, ie. it is negative and so indicates an unusual + condition; a diagnostic is printed. This return value can be passed to + exit(2), which will report the same code to the parent process that a + POSIX shell's $? would report for a program that died from the signal. + + `start_async`:: Run a function asynchronously. Takes a pointer to a `struct @@ -143,6 +163,11 @@ string pointers (NULL terminated) in .env: To specify a new initial working directory for the sub-process, specify it in the .dir member. +If the program cannot be found, the functions return -1 and set +errno to ENOENT. Normally, an error message is printed, but if +.silent_exec_failure is set to 1, no message is printed for this +special error condition. + * `struct async` diff --git a/Documentation/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt index e3ddf91..55b7286 100644 --- a/Documentation/technical/api-tree-walking.txt +++ b/Documentation/technical/api-tree-walking.txt @@ -1,12 +1,145 @@ tree walking API ================ -Talk about <tree-walk.h>, things like +The tree walking API is used to traverse and inspect trees. -* struct tree_desc -* init_tree_desc -* tree_entry_extract -* update_tree_entry -* get_tree_entry +Data Structures +--------------- -(JC, Linus) +`struct name_entry`:: + + An entry in a tree. Each entry has a sha1 identifier, pathname, and + mode. + +`struct tree_desc`:: + + A semi-opaque data structure used to maintain the current state of the + walk. ++ +* `buffer` is a pointer into the memory representation of the tree. It always +points at the current entry being visited. + +* `size` counts the number of bytes left in the `buffer`. + +* `entry` points to the current entry being visited. + +`struct traverse_info`:: + + A structure used to maintain the state of a traversal. ++ +* `prev` points to the traverse_info which was used to descend into the +current tree. If this is the top-level tree `prev` will point to +a dummy traverse_info. + +* `name` is the entry for the current tree (if the tree is a subtree). + +* `pathlen` is the length of the full path for the current tree. + +* `conflicts` can be used by callbacks to maintain directory-file conflicts. + +* `fn` is a callback called for each entry in the tree. See Traversing for more +information. + +* `data` can be anything the `fn` callback would want to use. + +Initializing +------------ + +`init_tree_desc`:: + + Initialize a `tree_desc` and decode its first entry. The buffer and + size parameters are assumed to be the same as the buffer and size + members of `struct tree`. + +`fill_tree_descriptor`:: + + Initialize a `tree_desc` and decode its first entry given the sha1 of + a tree. Returns the `buffer` member if the sha1 is a valid tree + identifier and NULL otherwise. + +`setup_traverse_info`:: + + Initialize a `traverse_info` given the pathname of the tree to start + traversing from. The `base` argument is assumed to be the `path` + member of the `name_entry` being recursed into unless the tree is a + top-level tree in which case the empty string ("") is used. + +Walking +------- + +`tree_entry`:: + + Visit the next entry in a tree. Returns 1 when there are more entries + left to visit and 0 when all entries have been visited. This is + commonly used in the test of a while loop. + +`tree_entry_len`:: + + Calculate the length of a tree entry's pathname. This utilizes the + memory structure of a tree entry to avoid the overhead of using a + generic strlen(). + +`update_tree_entry`:: + + Walk to the next entry in a tree. This is commonly used in conjunction + with `tree_entry_extract` to inspect the current entry. + +`tree_entry_extract`:: + + Decode the entry currently being visited (the one pointed to by + `tree_desc's` `entry` member) and return the sha1 of the entry. The + `pathp` and `modep` arguments are set to the entry's pathname and mode + respectively. + +`get_tree_entry`:: + + Find an entry in a tree given a pathname and the sha1 of a tree to + search. Returns 0 if the entry is found and -1 otherwise. The third + and fourth parameters are set to the entry's sha1 and mode + respectively. + +Traversing +---------- + +`traverse_trees`:: + + Traverse `n` number of trees in parallel. The `fn` callback member of + `traverse_info` is called once for each tree entry. + +`traverse_callback_t`:: + The arguments passed to the traverse callback are as follows: ++ +* `n` counts the number of trees being traversed. + +* `mask` has its nth bit set if something exists in the nth entry. + +* `dirmask` has its nth bit set if the nth tree's entry is a directory. + +* `entry` is an array of size `n` where the nth entry is from the nth tree. + +* `info` maintains the state of the traversal. + ++ +Returning a negative value will terminate the traversal. Otherwise the +return value is treated as an update mask. If the nth bit is set the nth tree +will be updated and if the bit is not set the nth tree entry will be the +same in the next callback invocation. + +`make_traverse_path`:: + + Generate the full pathname of a tree entry based from the root of the + traversal. For example, if the traversal has recursed into another + tree named "bar" the pathname of an entry "baz" in the "bar" + tree would be "bar/baz". + +`traverse_path_len`:: + + Calculate the length of a pathname returned by `make_traverse_path`. + This utilizes the memory structure of a tree entry to avoid the + overhead of using a generic strlen(). + +Authors +------- + +Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds +<torvalds@linux-foundation.org> diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index 48bb97f..53aa0c8 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -42,10 +42,12 @@ compared, but this is not enabled by default because this member is not stable on network filesystems. With `USE_NSEC` compile-time option, `st_mtim.tv_nsec` and `st_ctim.tv_nsec` members are also compared, but this is not enabled by default -because the value of this member becomes meaningless once the -inode is evicted from the inode cache on filesystems that do not -store it on disk. - +because in-core timestamps can have finer granularity than +on-disk timestamps, resulting in meaningless changes when an +inode is evicted from the inode cache. See commit 8ce13b0 +of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git +([PATCH] Sync in core time granuality with filesystems, +2005-01-04). Racy git -------- diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 5355ebc..d813ceb 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -67,3 +67,21 @@ For example, with this: a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be rewritten in any context that takes a URL to be "git://git.host.xz/repo.git". +If you want to rewrite URLs for push only, you can create a +configuration section of the form: + +------------ + [url "<actual url base>"] + pushInsteadOf = <other url base> +------------ + +For example, with this: + +------------ + [url "ssh://example.org/"] + pushInsteadOf = git://example.org/ +------------ + +a URL like "git://example.org/path/to/repo.git" will be rewritten to +"ssh://example.org/path/to/repo.git" for pushes, but pulls will still +use the original URL. |