diff options
Diffstat (limited to 'Documentation')
28 files changed, 655 insertions, 756 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index fe9a91d6a3..e53d333e5c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -21,6 +21,7 @@ ARTICLES += git-tools ARTICLES += git-bisect-lk2009 # with their own formatting rules. SP_ARTICLES = user-manual +SP_ARTICLES += howto/new-command SP_ARTICLES += howto/revert-branch-rebase SP_ARTICLES += howto/using-merge-subtree SP_ARTICLES += howto/using-signed-tag-in-pull-request @@ -31,7 +32,6 @@ SP_ARTICLES += howto/separating-topic-branches SP_ARTICLES += howto/revert-a-faulty-merge SP_ARTICLES += howto/recover-corrupted-blob-object SP_ARTICLES += howto/rebuild-from-update-hook -SP_ARTICLES += howto/rebuild-from-update-hook SP_ARTICLES += howto/rebase-from-internal-branch SP_ARTICLES += howto/maintain-git API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) diff --git a/Documentation/RelNotes/1.8.1.1.txt b/Documentation/RelNotes/1.8.1.1.txt new file mode 100644 index 0000000000..0dc37dcdd4 --- /dev/null +++ b/Documentation/RelNotes/1.8.1.1.txt @@ -0,0 +1,36 @@ +Git 1.8.1.1 Release Notes +========================= + +Fixes since v1.8.1 +------------------ + + * After failing to create a temporary file using mkstemp(), failing + pathname was not reported correctly on some platforms. + + * http transport was wrong to ask for the username when the + authentication is done by certificate identity. + + * After "git add -N" and then writing a tree object out of the + index, the cache-tree data structure got corrupted. + + * "git pack-refs" that ran in parallel to another process that + created new refs had a race that can lose new ones. + + * When a line to be wrapped has a solid run of non space characters + whose length exactly is the wrap width, "git shortlog -w" failed + to add a newline after such a line. + + * "gitweb", when sorting by age to show repositories with new + activities first, used to sort repositories with absolutely + nothing in it early, which was not very useful. + + * Some scripted programs written in Python did not get updated when + PYTHON_PATH changed. + + * We have been carrying a translated and long-unmaintained copy of an + old version of the tutorial; removed. + + * Portability issues in many self-test scripts have been addressed. + + +Also contains other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.8.1.txt b/Documentation/RelNotes/1.8.1.txt new file mode 100644 index 0000000000..d6f9555923 --- /dev/null +++ b/Documentation/RelNotes/1.8.1.txt @@ -0,0 +1,241 @@ +Git v1.8.1 Release Notes +======================== + +Backward compatibility notes +---------------------------- + +In the next major release (not *this* one), we will change the +behavior of the "git push" command. + +When "git push [$there]" does not say what to push, we have used the +traditional "matching" semantics so far (all your branches were sent +to the remote as long as there already are branches of the same name +over there). We will use the "simple" semantics that pushes the +current branch to the branch with the same name, only when the current +branch is set to integrate with that remote branch. There is a user +preference configuration variable "push.default" to change this, and +"git push" will warn about the upcoming change until you set this +variable in this release. + +"git branch --set-upstream" is deprecated and may be removed in a +relatively distant future. "git branch [-u|--set-upstream-to]" has +been introduced with a saner order of arguments to replace it. + + +Updates since v1.8.0 +-------------------- + +UI, Workflows & Features + + * Command-line completion scripts for tcsh and zsh have been added. + + * "git-prompt" scriptlet (in contrib/completion) can be told to paint + pieces of the hints in the prompt string in colors. + + * Some documentation pages that used to ship only in the plain text + format are now formatted in HTML as well. + + * We used to have a workaround for a bug in ancient "less" that + causes it to exit without any output when the terminal is resized. + The bug has been fixed in "less" version 406 (June 2007), and the + workaround has been removed in this release. + + * When "git checkout" checks out a branch, it tells the user how far + behind (or ahead) the new branch is relative to the remote tracking + branch it builds upon. The message now also advises how to sync + them up by pushing or pulling. This can be disabled with the + advice.statusHints configuration variable. + + * "git config --get" used to diagnose presence of multiple + definitions of the same variable in the same configuration file as + an error, but it now applies the "last one wins" rule used by the + internal configuration logic. Strictly speaking, this may be an + API regression but it is expected that nobody will notice it in + practice. + + * A new configuration variable "diff.context" can be used to + give the default number of context lines in the patch output, to + override the hardcoded default of 3 lines. + + * "git format-patch" learned the "--notes=<ref>" option to give + notes for the commit after the three-dash lines in its output. + + * "git log -p -S<string>" now looks for the <string> after applying + the textconv filter (if defined); earlier it inspected the contents + of the blobs without filtering. + + * "git log --grep=<pcre>" learned to honor the "grep.patterntype" + configuration set to "perl". + + * "git replace -d <object>" now interprets <object> as an extended + SHA-1 (e.g. HEAD~4 is allowed), instead of only accepting full hex + object name. + + * "git rm $submodule" used to punt on removing a submodule working + tree to avoid losing the repository embedded in it. Because + recent git uses a mechanism to separate the submodule repository + from the submodule working tree, "git rm" learned to detect this + case and removes the submodule working tree when it is safe to do so. + + * "git send-email" used to prompt for the sender address, even when + the committer identity is well specified (e.g. via user.name and + user.email configuration variables). The command no longer gives + this prompt when not necessary. + + * "git send-email" did not allow non-address garbage strings to + appear after addresses on Cc: lines in the patch files (and when + told to pick them up to find more recipients), e.g. + + Cc: Stable Kernel <stable@k.org> # for v3.2 and up + + The command now strips " # for v3.2 and up" part before adding the + remainder of this line to the list of recipients. + + * "git submodule add" learned to add a new submodule at the same + path as the path where an unrelated submodule was bound to in an + existing revision via the "--name" option. + + * "git submodule sync" learned the "--recursive" option. + + * "diff.submodule" configuration variable can be used to give custom + default value to the "git diff --submodule" option. + + * "git symbolic-ref" learned the "-d $symref" option to delete the + named symbolic ref, which is more intuitive way to spell it than + "update-ref -d --no-deref $symref". + + +Foreign Interface + + * "git cvsimport" can be told to record timezones (other than GMT) + per-author via its author info file. + + * The remote helper interface to interact with subversion + repositories (one of the GSoC 2012 projects) has been merged. + + * A new remote-helper interface for Mercurial has been added to + contrib/remote-helpers. + + * The documentation for git(1) was pointing at a page at an external + site for the list of authors that no longer existed. The link has + been updated to point at an alternative site. + + +Performance, Internal Implementation, etc. + + * Compilation on Cygwin with newer header files are supported now. + + * A couple of low-level implementation updates on MinGW. + + * The logic to generate the initial advertisement from "upload-pack" + (i.e. what is invoked by "git fetch" on the other side of the + connection) to list what refs are available in the repository has + been optimized. + + * The logic to find set of attributes that match a given path has + been optimized. + + * Use preloadindex in "git diff-index" and "git update-index", which + has a nice speedup on systems with slow stat calls (and even on + Linux). + + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.8.0 +------------------ + +Unless otherwise noted, all the fixes since v1.8.0 in the maintenance +track are contained in this release (see release notes to them for +details). + + * The configuration parser had an unnecessary hardcoded limit on + variable names that was not checked consistently. + + * The "say" function in the test scaffolding incorrectly allowed + "echo" to interpret "\a" as if it were a C-string asking for a + BEL output. + + * "git mergetool" feeds /dev/null as a common ancestor when dealing + with an add/add conflict, but p4merge backend cannot handle + it. Work it around by passing a temporary empty file. + + * "git log -F -E --grep='<ere>'" failed to use the given <ere> + pattern as extended regular expression, and instead looked for the + string literally. + + * "git grep -e pattern <tree>" asked the attribute system to read + "<tree>:.gitattributes" file in the working tree, which was + nonsense. + + * A symbolic ref refs/heads/SYM was not correctly removed with "git + branch -d SYM"; the command removed the ref pointed by SYM + instead. + + * Update "remote tracking branch" in the documentation to + "remote-tracking branch". + + * "git pull --rebase" run while the HEAD is detached tried to find + the upstream branch of the detached HEAD (which by definition + does not exist) and emitted unnecessary error messages. + + * The refs/replace hierarchy was not mentioned in the + repository-layout docs. + + * Various rfc2047 quoting issues around a non-ASCII name on the + From: line in the output from format-patch have been corrected. + + * Sometimes curl_multi_timeout() function suggested a wrong timeout + value when there is no file descriptor to wait on and the http + transport ended up sleeping for minutes in select(2) system call. + A workaround has been added for this. + + * For a fetch refspec (or the result of applying wildcard on one), + we always want the RHS to map to something inside "refs/" + hierarchy, but the logic to check it was not exactly right. + (merge 5c08c1f jc/maint-fetch-tighten-refname-check later to maint). + + * "git diff -G<pattern>" did not honor textconv filter when looking + for changes. + + * Some HTTP servers ask for auth only during the actual packing phase + (not in ls-remote phase); this is not really a recommended + configuration, but the clients used to fail to authenticate with + such servers. + (merge 2e736fd jk/maint-http-half-auth-fetch later to maint). + + * "git p4" used to try expanding malformed "$keyword$" that spans + across multiple lines. + + * Syntax highlighting in "gitweb" was not quite working. + + * RSS feed from "gitweb" had a xss hole in its title output. + + * "git config --path $key" segfaulted on "[section] key" (a boolean + "true" spelled without "=", not "[section] key = true"). + + * "git checkout -b foo" while on an unborn branch did not say + "Switched to a new branch 'foo'" like other cases. + + * Various codepaths have workaround for a common misconfiguration to + spell "UTF-8" as "utf8", but it was not used uniformly. Most + notably, mailinfo (which is used by "git am") lacked this support. + + * We failed to mention a file without any content change but whose + permission bit was modified, or (worse yet) a new file without any + content in the "git diff --stat" output. + + * When "--stat-count" hides a diffstat for binary contents, the total + number of added and removed lines at the bottom was computed + incorrectly. + + * When "--stat-count" hides a diffstat for unmerged paths, the total + number of affected files at the bottom of the "diff --stat" output + was computed incorrectly. + + * "diff --shortstat" miscounted the total number of affected files + when there were unmerged paths. + + * "update-ref -d --deref SYM" to delete a ref through a symbolic ref + that points to it did not remove it correctly. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c34c9d12c6..75935d500d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -174,7 +174,8 @@ message starts, you can put a "From: " line to name that person. You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter" -material between the three dash lines and the diffstat. +material between the three dash lines and the diffstat. Git-notes +can also be inserted using the `--notes` option. Do not attach the patch as a MIME attachment, compressed or not. Do not let your e-mail client send quoted-printable. Do not let diff --git a/Documentation/config.txt b/Documentation/config.txt index d1de85778c..bf8f911e1f 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -160,9 +160,10 @@ advice.*:: it resulted in a non-fast-forward error. statusHints:: Show directions on how to proceed from the current - state in the output of linkgit:git-status[1] and in + state in the output of linkgit:git-status[1], in the template shown when writing commit messages in - linkgit:git-commit[1]. + linkgit:git-commit[1], and in the help message shown + by linkgit:git-checkout[1] when switching branch. commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to merge to avoid overwriting local changes. @@ -538,14 +539,14 @@ core.pager:: `LESS` variable to some other value. Alternately, these settings can be overridden on a project or global basis by setting the `core.pager` option. - Setting `core.pager` has no affect on the `LESS` + Setting `core.pager` has no effect on the `LESS` environment variable behaviour above, so if you want to override git's default settings this way, you need to be explicit. For example, to disable the S option in a backward compatible manner, set `core.pager` - to `less -+$LESS -FRX`. This will be passed to the - shell by git, which will translate the final command to - `LESS=FRSX less -+FRSX -FRX`. + to `less -+S`. This will be passed to the shell by + git, which will translate the final command to + `LESS=FRSX less -+S`. core.whitespace:: A comma separated list of common whitespace problems to diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index c2b94f9446..4314ad0fbb 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -56,6 +56,10 @@ diff.statGraphWidth:: Limit the width of the graph part in --stat output. If set, applies to all commands generating --stat output except format-patch. +diff.context:: + Generate diffs with <n> lines of context instead of the default + of 3. This value is overridden by the -U option. + diff.external:: If this config variable is set, diff generation is not performed using the internal diff machinery, but using the @@ -103,6 +107,13 @@ diff.suppressBlankEmpty:: A boolean to inhibit the standard behavior of printing a space before each empty output line. Defaults to false. +diff.submodule:: + Specify the format in which differences in submodules are + shown. The "log" format lists the commits in the range like + linkgit:git-submodule[1] `summary` does. The "short" format + format just shows the names of the commits at the beginning + and end of the range. Defaults to short. + diff.wordRegex:: A POSIX Extended Regular Expression used to determine what is a "word" when performing word-by-word difference calculations. Character diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 1fb6f2d4e9..39f2c5074c 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -170,7 +170,8 @@ any of those replacements occurred. the commits in the range like linkgit:git-submodule[1] `summary` does. Omitting the `--submodule` option or specifying `--submodule=short`, uses the 'short' format. This format just shows the names of the commits - at the beginning and end of the range. + at the beginning and end of the range. Can be tweaked via the + `diff.submodule` configuration variable. --color[=<when>]:: Show colored diff. diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 19cbb9098f..7bdb039d5e 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -109,6 +109,10 @@ OPTIONS format. See linkgit:git-status[1] for details. Implies `--dry-run`. +--long:: + When doing a dry-run, give the output in a the long-format. + Implies `--dry-run`. + -z:: --null:: When showing `short` or `porcelain` status output, terminate diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index eaea079165..9ae2508f3f 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -240,6 +240,10 @@ GIT_CONFIG:: Using the "--global" option forces this to ~/.gitconfig. Using the "--system" option forces this to $(prefix)/etc/gitconfig. +GIT_CONFIG_NOSYSTEM:: + Whether to skip reading settings from the system-wide + $(prefix)/etc/gitconfig file. See linkgit:git[1] for details. + See also <<FILES>>. diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 6695ab3b4b..98d9881d7e 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -137,17 +137,19 @@ This option can be used several times to provide several detection regexes. -A <author-conv-file>:: CVS by default uses the Unix username when writing its commit logs. Using this option and an author-conv-file - in this format + maps the name recorded in CVS to author name, e-mail and + optional timezone: + --------- exon=Andreas Ericsson <ae@op5.se> - spawn=Simon Pawn <spawn@frog-pond.org> + spawn=Simon Pawn <spawn@frog-pond.org> America/Chicago --------- + 'git cvsimport' will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly -all along. +all along. If a timezone is specified, GIT_AUTHOR_DATE will +have the corresponding offset applied. + For convenience, this data is saved to `$GIT_DIR/cvs-authors` each time the '-A' option is provided and read from that same diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 6d43f56279..259dce4994 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -20,7 +20,7 @@ SYNOPSIS [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] [--to=<email>] [--cc=<email>] - [--cover-letter] [--quiet] + [--cover-letter] [--quiet] [--notes[=<ref>]] [<common diff options>] [ <since> | <revision range> ] @@ -191,6 +191,18 @@ will want to ensure that threading is disabled for `git send-email`. containing the shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--notes[=<ref>]:: + Append the notes (see linkgit:git-notes[1]) for the commit + after the three-dash line. ++ +The expected use case of this is to write supporting explanation for +the commit that does not belong to the commit log message proper, +and include it with the patch submission. While one can simply write +these explanations after `format-patch` has run but before sending, +keeping them as git notes allows them to be maintained between versions +of the patch series (but see the discussion of the `notes.rewrite` +configuration options in linkgit:git-notes[1] to use this workflow). + --[no]-signature=<signature>:: Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index b95aafae2d..46ef0466be 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -39,6 +39,10 @@ message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (<refname>):" (or "Notes:" for `refs/notes/commits`). +Notes can also be added to patches prepared with `git format-patch` by +using the `--notes` option. Such notes are added as a patch commentary +after a three dash separator line. + To change which notes are shown by 'git log', see the "notes.displayRef" configuration in linkgit:git-log[1]. diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 4f81a5bf9d..6d696e0f90 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -88,53 +88,17 @@ Each remote helper is expected to support only a subset of commands. The operations a helper supports are declared to git in the response to the `capabilities` command (see COMMANDS, below). -'option':: - For specifying settings like `verbosity` (how much output to - write to stderr) and `depth` (how much history is wanted in the - case of a shallow clone) that affect how other commands are - carried out. - -'connect':: - For fetching and pushing using git's native packfile protocol - that requires a bidirectional, full-duplex connection. - -'push':: - For listing remote refs and pushing specified objects from the - local object store to remote refs. - -'fetch':: - For listing remote refs and fetching the associated history to - the local object store. - -'import':: - For listing remote refs and fetching the associated history as - a fast-import stream. - -'refspec' <refspec>:: - This modifies the 'import' capability, allowing the produced - fast-import stream to modify refs in a private namespace - instead of writing to refs/heads or refs/remotes directly. - It is recommended that all importers providing the 'import' - capability use this. -+ -A helper advertising the capability -`refspec refs/heads/*:refs/svn/origin/branches/*` -is saying that, when it is asked to `import refs/heads/topic`, the -stream it outputs will update the `refs/svn/origin/branches/topic` -ref. -+ -This capability can be advertised multiple times. The first -applicable refspec takes precedence. The left-hand of refspecs -advertised with this capability must cover all refs reported by -the list command. If no 'refspec' capability is advertised, -there is an implied `refspec *:*`. +In the following, we list all defined capabilities and for +each we list which commands a helper with that capability +must provide. Capabilities for Pushing -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ 'connect':: Can attempt to connect to 'git receive-pack' (for pushing), - 'git upload-pack', etc for communication using the - packfile protocol. + 'git upload-pack', etc for communication using + git's native packfile protocol. This + requires a bidirectional, full-duplex connection. + Supported commands: 'connect'. @@ -144,16 +108,26 @@ Supported commands: 'connect'. + Supported commands: 'list for-push', 'push'. -If a helper advertises both 'connect' and 'push', git will use -'connect' if possible and fall back to 'push' if the helper requests -so when connecting (see the 'connect' command under COMMANDS). +'export':: + Can discover remote refs and push specified objects from a + fast-import stream to remote refs. ++ +Supported commands: 'list for-push', 'export'. + +If a helper advertises 'connect', git will use it if possible and +fall back to another capability if the helper requests so when +connecting (see the 'connect' command under COMMANDS). +When choosing between 'push' and 'export', git prefers 'push'. +Other frontends may have some other order of preference. + Capabilities for Fetching -~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^ 'connect':: Can try to connect to 'git upload-pack' (for fetching), 'git receive-pack', etc for communication using the - packfile protocol. + git's native packfile protocol. This + requires a bidirectional, full-duplex connection. + Supported commands: 'connect'. @@ -175,14 +149,27 @@ connecting (see the 'connect' command under COMMANDS). When choosing between 'fetch' and 'import', git prefers 'fetch'. Other frontends may have some other order of preference. +Miscellaneous capabilities +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +'option':: + For specifying settings like `verbosity` (how much output to + write to stderr) and `depth` (how much history is wanted in the + case of a shallow clone) that affect how other commands are + carried out. + 'refspec' <refspec>:: - This modifies the 'import' capability. + This modifies the 'import' capability, allowing the produced + fast-import stream to modify refs in a private namespace + instead of writing to refs/heads or refs/remotes directly. + It is recommended that all importers providing the 'import' + capability use this. + -A helper advertising +A helper advertising the capability `refspec refs/heads/*:refs/svn/origin/branches/*` -in its capabilities is saying that, when it handles -`import refs/heads/topic`, the stream it outputs will update the -`refs/svn/origin/branches/topic` ref. +is saying that, when it is asked to `import refs/heads/topic`, the +stream it outputs will update the `refs/svn/origin/branches/topic` +ref. + This capability can be advertised multiple times. The first applicable refspec takes precedence. The left-hand of refspecs @@ -190,6 +177,34 @@ advertised with this capability must cover all refs reported by the list command. If no 'refspec' capability is advertised, there is an implied `refspec *:*`. +'bidi-import':: + This modifies the 'import' capability. + The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers + to retrieve information about blobs and trees that already exist in + fast-import's memory. This requires a channel from fast-import to the + remote-helper. + If it is advertised in addition to "import", git establishes a pipe from + fast-import to the remote-helper's stdin. + It follows that git and fast-import are both connected to the + remote-helper's stdin. Because git can send multiple commands to + the remote-helper it is required that helpers that use 'bidi-import' + buffer all 'import' commands of a batch before sending data to fast-import. + This is to prevent mixing commands and fast-import responses on the + helper's stdin. + +'export-marks' <file>:: + This modifies the 'export' capability, instructing git to dump the + internal marks table to <file> when complete. For details, + read up on '--export-marks=<file>' in linkgit:git-fast-export[1]. + +'import-marks' <file>:: + This modifies the 'export' capability, instructing git to load the + marks specified in <file> before processing any input. For details, + read up on '--import-marks=<file>' in linkgit:git-fast-export[1]. + + + + COMMANDS -------- @@ -198,9 +213,11 @@ 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. Each capability may be preceded with '*', - which marks them mandatory for git version using the remote - helper to understand (unknown mandatory capability is fatal - error). + which marks them mandatory for git versions using the remote + helper to understand. Any unknown mandatory capability is a + fatal error. ++ +Support for this command is mandatory. 'list':: Lists the refs, one per line, in the format "<value> <name> @@ -210,9 +227,20 @@ Commands are given by the caller on the helper's standard input, one per line. the name; unrecognized attributes are ignored. The list ends with a blank line. + -If 'push' is supported this may be called as 'list for-push' -to obtain the current refs prior to sending one or more 'push' -commands to the helper. +See REF LIST ATTRIBUTES for a list of currently defined attributes. ++ +Supported if the helper has the "fetch" or "import" capability. + +'list for-push':: + Similar to 'list', except that it is used if and only if + the caller wants to the resulting ref list to prepare + push commands. + A helper supporting both push and fetch can use this + to distinguish for which operation the output of 'list' + is going to be used, possibly reducing the amount + of work that needs to be performed. ++ +Supported if the helper has the "push" or "export" capability. 'option' <name> <value>:: Sets the transport helper option <name> to <value>. Outputs a @@ -222,6 +250,8 @@ commands to the helper. for it). Options should be set before other commands, and may influence the behavior of those commands. + +See OPTIONS for a list of currently defined options. ++ Supported if the helper has the "option" capability. 'fetch' <sha1> <name>:: @@ -230,7 +260,7 @@ Supported if the helper has the "option" capability. per line, terminated with a blank line. Outputs a single blank line when all fetch commands in the same batch are complete. Only objects which were reported - in the ref list with a sha1 may be fetched this way. + in the output of 'list' with a sha1 may be fetched this way. + Optionally may output a 'lock <file>' line indicating a file under GIT_DIR/objects/pack which is keeping a pack until refs can be @@ -286,8 +316,29 @@ terminated with a blank line. For each batch of 'import', the remote helper should produce a fast-import stream terminated by a 'done' command. + +Note that if the 'bidi-import' capability is used the complete batch +sequence has to be buffered before starting to send data to fast-import +to prevent mixing of commands and fast-import responses on the helper's +stdin. ++ Supported if the helper has the "import" capability. +'export':: + Instructs the remote helper that any subsequent input is + part of a fast-import stream (generated by 'git fast-export') + containing objects which should be pushed to the remote. ++ +Especially useful for interoperability with a foreign versioning +system. ++ +The 'export-marks' and 'import-marks' capabilities, if specified, +affect this command in so far as they are passed on to 'git +fast-export', which then will load/store a table of marks for +local objects. This can be used to implement for incremental +operations. ++ +Supported if the helper has the "export" capability. + 'connect' <service>:: Connects to given service. Standard input and standard output of helper are connected to specified service (git prefix is @@ -313,10 +364,9 @@ capabilities reported by the helper. REF LIST ATTRIBUTES ------------------- -'for-push':: - The caller wants to use the ref list to prepare push - commands. A helper might chose to acquire the ref list by - opening a different type of connection to the destination. +The 'list' command produces a list of refs in which each ref +may be followed by a list of attributes. The following ref list +attributes are defined. 'unchanged':: This ref is unchanged since the last import or fetch, although @@ -324,6 +374,10 @@ REF LIST ATTRIBUTES OPTIONS ------- + +The following options are defined and (under suitable circumstances) +set by git if the remote helper has the 'option' capability. + 'option verbosity' <n>:: Changes the verbosity of messages displayed by the helper. A value of 0 for <n> means that processes operate diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 5d31860eb1..262436b7b1 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -134,6 +134,21 @@ use the following command: git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached ---------------- +Submodules +~~~~~~~~~~ +Only submodules using a gitfile (which means they were cloned +with a git version 1.7.8 or newer) will be removed from the work +tree, as their repository lives inside the .git directory of the +superproject. If a submodule (or one of those nested inside it) +still uses a .git directory, `git rm` will fail - no matter if forced +or not - to protect the submodule's history. + +A submodule is considered up-to-date when the HEAD is the same as +recorded in the index, no tracked files are modified and no untracked +files that aren't ignored are present in the submodules work tree. +Ignored files are deemed expendable and won't stop a submodule's work +tree from being removed. + EXAMPLES -------- `git rm Documentation/\*.txt`:: diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 324117072d..eeb561cf14 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -126,6 +126,10 @@ The --to option must be repeated for each user you want on the to list. + Note that no attempts whatsoever are made to validate the encoding. +--compose-encoding=<encoding>:: + Specify encoding of compose message. Default is the value of the + 'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed. + Sending ~~~~~~~ diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 67e5f53a9e..9f1ef9a463 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -38,6 +38,9 @@ OPTIONS across git versions and regardless of user configuration. See below for details. +--long:: + Give the output in the long-format. This is the default. + -u[<mode>]:: --untracked-files[=<mode>]:: Show untracked files. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index a65f38e184..b1de3bade7 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,7 +9,7 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git submodule' [--quiet] add [-b <branch>] [-f|--force] +'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] @@ -265,6 +265,11 @@ OPTIONS Initialize all submodules for which "git submodule init" has not been called so far before updating. +--name:: + This option is only valid for the add command. It sets the submodule's + name to the given string instead of defaulting to its path. The name + must be valid as a directory name and may not end with a '/'. + --reference <repository>:: This option is only valid for add and update commands. These commands sometimes need to clone a remote repository. In this case, diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 981d3a8fc1..ef68ad2b71 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -3,13 +3,14 @@ git-symbolic-ref(1) NAME ---- -git-symbolic-ref - Read and modify symbolic refs +git-symbolic-ref - Read, modify and delete symbolic refs SYNOPSIS -------- [verse] 'git symbolic-ref' [-m <reason>] <name> <ref> 'git symbolic-ref' [-q] [--short] <name> +'git symbolic-ref' --delete [-q] <name> DESCRIPTION ----------- @@ -21,6 +22,9 @@ argument to see which branch your working tree is on. Given two arguments, creates or updates a symbolic ref <name> to point at the given branch <ref>. +Given `--delete` and an additional argument, deletes the given +symbolic ref. + A symbolic ref is a regular file that stores a string that begins with `ref: refs/`. For example, your `.git/HEAD` is a regular file whose contents is `ref: refs/heads/master`. @@ -28,6 +32,10 @@ a regular file whose contents is `ref: refs/heads/master`. OPTIONS ------- +-d:: +--delete:: + Delete the symbolic ref <name>. + -q:: --quiet:: Do not issue an error message if the <name> is not a diff --git a/Documentation/git.txt b/Documentation/git.txt index b0e8f02851..5bb5cc830d 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,6 +43,11 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: +* link:v1.8.1/git.html[documentation for release 1.8.1] + +* release notes for + link:RelNotes/1.8.1.txt[1.8.1]. + * link:v1.8.0.3/git.html[documentation for release 1.8.0.3] * release notes for @@ -767,6 +772,14 @@ for further details. and read the password from its STDOUT. See also the 'core.askpass' option in linkgit:git-config[1]. +'GIT_CONFIG_NOSYSTEM':: + Whether to skip reading settings from the system-wide + `$(prefix)/etc/gitconfig` file. This environment variable can + be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a + predictable environment for a picky script, or you can set it + temporarily to avoid using a buggy `/etc/gitconfig` file while + waiting for someone with sufficient permissions to fix it. + 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index ba02d4de59..2698f63cf9 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -56,6 +56,7 @@ When more than one pattern matches the path, a later line overrides an earlier line. This overriding is done per attribute. The rules how the pattern matches paths are the same as in `.gitignore` files; see linkgit:gitignore[5]. +Unlike `.gitignore`, negative patterns are forbidden. When deciding what attributes are assigned to a path, git consults `$GIT_DIR/info/attributes` file (which has the highest diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 4effd78902..ab3e91c054 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -18,7 +18,9 @@ working tree, is a text file with a syntax matching the requirements of linkgit:git-config[1]. The file contains one subsection per submodule, and the subsection value -is the name of the submodule. Each submodule section also contains the +is the name of the submodule. The name is set to the path where the +submodule has been added unless it was customized with the '--name' +option of 'git submodule add'. Each submodule section also contains the following required keys: submodule.<name>.path:: diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt new file mode 100644 index 0000000000..36502f6718 --- /dev/null +++ b/Documentation/howto/new-command.txt @@ -0,0 +1,104 @@ +From: Eric S. Raymond <esr@thyrsus.com> +Abstract: This is how-to documentation for people who want to add extension + commands to git. It should be read alongside api-builtin.txt. +Content-type: text/asciidoc + +How to integrate new subcommands +================================ + +This is how-to documentation for people who want to add extension +commands to git. It should be read alongside api-builtin.txt. + +Runtime environment +------------------- + +git subcommands are standalone executables that live in the git exec +path, normally /usr/lib/git-core. The git executable itself is a +thin wrapper that knows where the subcommands live, and runs them by +passing command-line arguments to them. + +(If "git foo" is not found in the git exec path, the wrapper +will look in the rest of your $PATH for it. Thus, it's possible +to write local git extensions that don't live in system space.) + +Implementation languages +------------------------ + +Most subcommands are written in C or shell. A few are written in +Perl. + +While we strongly encourage coding in portable C for portability, +these specific scripting languages are also acceptable. We won't +accept more without a very strong technical case, as we don't want +to broaden the git suite's required dependencies. Import utilities, +surgical tools, remote helpers and other code at the edges of the +git suite are more lenient and we allow Python (and even Tcl/tk), +but they should not be used for core functions. + +This may change in the future. Especially Python is not allowed in +core because we need better Python integration in the git Windows +installer before we can be confident people in that environment +won't experience an unacceptably large loss of capability. + +C commands are normally written as single modules, named after the +command, that link a collection of functions called libgit. Thus, +your command 'git-foo' would normally be implemented as a single +"git-foo.c" (or "builtin/foo.c" if it is to be linked to the main +binary); this organization makes it easy for people reading the code +to find things. + +See the CodingGuidelines document for other guidance on what we consider +good practice in C and shell, and api-builtin.txt for the support +functions available to built-in commands written in C. + +What every extension command needs +---------------------------------- + +You must have a man page, written in asciidoc (this is what git help +followed by your subcommand name will display). Be aware that there is +a local asciidoc configuration and macros which you should use. It's +often helpful to start by cloning an existing page and replacing the +text content. + +You must have a test, written to report in TAP (Test Anything Protocol). +Tests are executables (usually shell scripts) that live in the 't' +subdirectory of the tree. Each test name begins with 't' and a sequence +number that controls where in the test sequence it will be executed; +conventionally the rest of the name stem is that of the command +being tested. + +Read the file t/README to learn more about the conventions to be used +in writing tests, and the test support library. + +Integrating a command +--------------------- + +Here are the things you need to do when you want to merge a new +subcommand into the git tree. + +1. Don't forget to sign off your patch! + +2. Append your command name to one of the variables BUILTIN_OBJS, +EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON. + +3. Drop its test in the t directory. + +4. If your command is implemented in an interpreted language with a +p-code intermediate form, make sure .gitignore in the main directory +includes a pattern entry that ignores such files. Python .pyc and +.pyo files will already be covered. + +5. If your command has any dependency on a particular version of +your language, document it in the INSTALL file. + +6. There is a file command-list.txt in the distribution main directory +that categorizes commands by type, so they can be listed in appropriate +subsections in the documentation's summary command list. Add an entry +for yours. To understand the categories, look at git-cmmands.txt +in the main directory. + +7. Give the maintainer one paragraph to include in the RelNotes file +to describe the new feature; a good place to do so is in the cover +letter [PATCH 0/n]. + +That's all there is to it. diff --git a/Documentation/pt_BR/gittutorial.txt b/Documentation/pt_BR/gittutorial.txt deleted file mode 100644 index beba065252..0000000000 --- a/Documentation/pt_BR/gittutorial.txt +++ /dev/null @@ -1,675 +0,0 @@ -gittutorial(7) -============== - -NOME ----- -gittutorial - Um tutorial de introdução ao git (para versão 1.5.1 ou mais nova) - -SINOPSE --------- -git * - -DESCRIÇÃO ------------ - -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/ ------------------------------------------------- - -Agora que você iniciou seu diretório de trabalho, você deve ter notado que um -novo diretório foi 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 atual (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 ------------------------------------------------- - -Ao executar esse comando, ele irá te pedir uma mensagem descrevendo a mudança, -e, então, irá 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 a história do projeto ------------------------ - -Em qualquer ponto você pode visualizar a história das suas mudanças -usando - ------------------------------------------------- -$ git log ------------------------------------------------- - -Se você também quiser 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/rev-list-options.txt b/Documentation/rev-list-options.txt index ee497430cb..1ec14a068e 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -79,6 +79,11 @@ if it is part of the log message. Match the regexp limiting patterns without regard to letters case. +--basic-regexp:: + + Consider the limiting patterns to be basic regular expressions; + this is the default. + -E:: --extended-regexp:: @@ -91,6 +96,11 @@ if it is part of the log message. Consider the limiting patterns to be fixed strings (don't interpret pattern as a regular expression). +--perl-regexp:: + + Consider the limiting patterns to be Perl-compatible regexp. + Requires libpcre to be compiled in. + --remove-empty:: Stop when a given path disappears from the tree. diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index 1a797812fb..a959517b23 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -53,3 +53,11 @@ Functions `argv_array_clear`:: Free all memory associated with the array and return it to the initial, empty state. + +`argv_array_detach`:: + Detach the argv array from the `struct argv_array`, transfering + ownership of the allocated array and strings. + +`argv_array_free_detached`:: + Free the memory allocated by a `struct argv_array` that was later + detached and is now no longer needed. diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index 95a8bf3846..84686b5c69 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -279,6 +279,22 @@ same behaviour as well. Strip whitespace from a buffer. The second parameter controls if comments are considered contents to be removed or not. +`strbuf_split_buf`:: +`strbuf_split_str`:: +`strbuf_split_max`:: +`strbuf_split`:: + + Split a string or strbuf into a list of strbufs at a specified + terminator character. The returned substrings include the + terminator characters. Some of these functions take a `max` + parameter, which, if positive, limits the output to that + number of substrings. + +`strbuf_list_free`:: + + Free a list of strbufs (for example, the return values of the + `strbuf_split()` functions). + `launch_editor`:: Launch the user preferred editor to edit a file and fill the buffer diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 94d7a2bd99..7386bcab3e 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -38,7 +38,8 @@ member (you need this if you add things later) and you should set the `unsorted_string_list_delete_item`. . Can remove items not matching a criterion from a sorted or unsorted - list using `filter_string_list`. + list using `filter_string_list`, or remove empty strings using + `string_list_remove_empty_items`. . Finally it should free the list using `string_list_clear`. @@ -75,6 +76,12 @@ Functions to be deleted. Preserve the order of the items that are retained. +`string_list_remove_empty_items`:: + + Remove any empty strings from the list. If free_util is true, + call free() on the util members of any items that have to be + deleted. Preserve the order of the items that are retained. + `string_list_longest_prefix`:: Return the longest string within a string_list that is a diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 85651b57ae..1b377dc207 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1787,6 +1787,13 @@ $ git format-patch origin will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD. +`git format-patch` can include an initial "cover letter". You can insert +commentary on individual patches after the three dash line which +`format-patch` places after the commit message but before the patch +itself. If you use `git notes` to track your cover letter material, +`git format-patch --notes` will include the commit's notes in a similar +manner. + You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the linkgit:git-send-email[1] script to automate the process. |