diff options
Diffstat (limited to 'Documentation')
35 files changed, 640 insertions, 67 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index cc83610588..0d9ffb4ad9 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -46,6 +46,7 @@ all: html man html: $(DOC_HTML) +$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN7): asciidoc.conf man: man1 man7 man1: $(DOC_MAN1) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 8601949e80..90722c21fa 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -49,7 +49,7 @@ People on the git mailing list need to be able to read and comment on the changes you are submitting. It is important for a developer to be able to "quote" your changes, using standard e-mail tools, so that they may comment on specific portions of -your code. For this reason, all patches should be submited +your code. For this reason, all patches should be submitted "inline". WARNING: Be wary of your MUAs word-wrap corrupting your patch. Do not cut-n-paste your patch; you can lose tabs that way if you are not careful. diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 7ce71510de..8196d787ab 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -9,6 +9,8 @@ [attributes] caret=^ +startsb=[ +endsb=] ifdef::backend-docbook[] [gitlink-inlinemacro] diff --git a/Documentation/config.txt b/Documentation/config.txt index a04c5adf8e..465eb13e76 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -91,6 +91,18 @@ core.warnAmbiguousRefs:: If true, git will warn you if the ref name you passed it is ambiguous and might match multiple refs in the .git/refs/ tree. True by default. +core.compression:: + An integer -1..9, indicating the compression level for objects that + are not in a pack file. -1 is the zlib and git default. 0 means no + compression, and 1..9 are various speed/size tradeoffs, 9 being + slowest. + +core.legacyheaders:: + A boolean which enables the legacy object header format in case + you want to interoperate with old clients accessing the object + database directly (where the "http://" and "rsync://" protocols + count as direct access). + alias.*:: Command aliases for the gitlink:git[1] command wrapper - e.g. after defining "alias.last = cat-file commit HEAD", the invocation @@ -104,10 +116,31 @@ apply.whitespace:: Tells `git-apply` how to handle whitespaces, in the same way as the '--whitespace' option. See gitlink:git-apply[1]. +diff.color:: + When true (or `always`), always use colors in patch. + When false (or `never`), never. When set to `auto`, use + colors only when the output is to the terminal. + +diff.color.<slot>:: + Use customized color for diff colorization. `<slot>` + specifies which part of the patch to use the specified + color, and is one of `plain` (context text), `meta` + (metainformation), `frag` (hunk header), `old` (removed + lines), or `new` (added lines). The value for these + configuration variables can be one of: `normal`, `bold`, + `dim`, `ul`, `blink`, `reverse`, `reset`, `black`, + `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, or + `white`. + diff.renameLimit:: The number of files to consider when performing the copy/rename detection; equivalent to the git diff option '-l'. +diff.renames:: + Tells git to detect renames. If set to any boolean value, it + will enable basic rename detection. If set to "copies" or + "copy", it will detect copies, as well. + format.headers:: Additional email headers to include in a patch to be submitted by mail. See gitlink:git-format-patch[1]. @@ -166,6 +199,10 @@ merge.summary:: Whether to include summaries of merged commits in newly created merge commit messages. False by default. +pack.window:: + The size of the window used by gitlink:git-pack-objects[1] when no + window size is given on the command line. Defaults to 10. + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. @@ -181,6 +218,17 @@ showbranch.default:: The default set of branches for gitlink:git-show-branch[1]. See gitlink:git-show-branch[1]. +tar.umask:: + By default, git-link:git-tar-tree[1] sets file and directories modes + to 0666 or 0777. While this is both useful and acceptable for projects + such as the Linux Kernel, it might be excessive for other projects. + With this variable, it becomes possible to tell + git-link:git-tar-tree[1] to apply a specific umask to the modes above. + The special value "user" indicates that the user's current umask will + be used. This should be enough for most projects, as it will lead to + the same permissions as git-link:git-checkout[1] would use. The default + value remains 0, which means world read-write. + user.email:: Your email address to be recorded in any newly created commits. Can be overridden by the 'GIT_AUTHOR_EMAIL' and 'GIT_COMMITTER_EMAIL' diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 1fbca83141..d2b0bd38de 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -93,7 +93,7 @@ machine where the repository is hosted. If you don't want to give them a full shell on the machine, there is a restricted shell which only allows users to do git pushes and pulls; see gitlink:git-shell[1]. -Put all the committers should in the same group, and make the repository +Put all the committers in the same group, and make the repository writable by that group: ------------------------------------------------ diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index f523ec2fbe..47ba9a403a 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -4,18 +4,21 @@ -u:: Synonym for "-p". +--raw:: + Generate the raw format. + --patch-with-raw:: - Generate patch but keep also the default raw diff output. + Synonym for "-p --raw". --stat:: - Generate a diffstat instead of a patch. + Generate a diffstat. --summary:: Output a condensed summary of extended header information such as creations, renames and mode changes. --patch-with-stat:: - Generate patch and prepend its diffstat. + Synonym for "-p --stat". -z:: \0 line termination on output @@ -26,10 +29,25 @@ --name-status:: Show only names and status of changed files. +--color:: + Show colored diff. + +--no-color:: + Turn off colored diff, even when the configuration file + gives the default to color output. + +--no-renames:: + Turn off rename detection, even when the configuration + file gives the default to do so. + --full-index:: Instead of the first handful characters, show full object name of pre- and post-image blob on the "index" - line when generating a patch format output. + line when generating a patch format output. + +--binary:: + In addition to --full-index, output "binary diff" that + can be applied with "git apply". --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object @@ -94,5 +112,11 @@ Swap two inputs; that is, show differences from index or on-disk file to tree contents. +--text:: + Treat all files as text. + +-a:: + Shorthand for "--text". + For more detailed explanation on these common options, see also link:diffcore.html[diffcore documentation]. diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 0fe66f2d0c..517a86b238 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -15,9 +15,9 @@ SYNOPSIS DESCRIPTION ----------- Updates the index file for given paths, or all modified files if -'-a' is specified, and makes a commit object. The command -VISUAL and EDITOR environment variables to edit the commit log -message. +'-a' is specified, and makes a commit object. The command specified +by either the VISUAL or EDITOR environment variables are used to edit +the commit log message. Several environment variable are used during commits. They are documented in gitlink:git-commit-tree[1]. diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 56bd3e517d..092d0d6730 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,7 +8,7 @@ git-cvsexportcommit - Export a commit to a CVS checkout SYNOPSIS -------- -'git-cvsexportcommmit' [-h] [-v] [-c] [-p] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID +'git-cvsexportcommit' [-h] [-v] [-c] [-p] [-a] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID DESCRIPTION @@ -36,9 +36,13 @@ OPTIONS commit if any hunks fail to apply or there were other problems. -p:: - Be pedantic (paranoid) when applying patches. Invokes patch with + Be pedantic (paranoid) when applying patches. Invokes patch with --fuzz=0 +-a:: + Add authorship information. Adds Author line, and Committer (if + different from Author) to the message. + -f:: Force the merge even if the files are not up to date. diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index 481b8b3aa0..7248b35d95 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -37,7 +37,7 @@ omit diff output for unmerged entries and just show "Unmerged". commit with these flags. -q:: - Remain silent even on nonexisting files + Remain silent even on nonexistent files Output format ------------- diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 7ab2080376..228c4d95bd 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -8,24 +8,24 @@ git-diff - Show changes between commits, commit and working tree, etc SYNOPSIS -------- -'git-diff' [ --diff-options ] <ent>{0,2} [<path>...] +'git-diff' [ --diff-options ] <tree-ish>{0,2} [<path>...] DESCRIPTION ----------- -Show changes between two ents, an ent and the working tree, an -ent and the index file, or the index file and the working tree. +Show changes between two trees, a tree and the working tree, a +tree and the index file, or the index file and the working tree. The combination of what is compared with what is determined by -the number of ents given to the command. +the number of trees given to the command. -* When no <ent> is given, the working tree and the index - file is compared, using `git-diff-files`. +* When no <tree-ish> is given, the working tree and the index + file are compared, using `git-diff-files`. -* When one <ent> is given, the working tree and the named - tree is compared, using `git-diff-index`. The option +* When one <tree-ish> is given, the working tree and the named + tree are compared, using `git-diff-index`. The option `--cached` can be given to compare the index file and the named tree. -* When two <ent>s are given, these two trees are compared +* When two <tree-ish>s are given, these two trees are compared using `git-diff-tree`. OPTIONS diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 4ca0014dac..67425dc035 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -9,8 +9,9 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--attach] +'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--attach] [--thread] [-s | --signoff] [--diff-options] [--start-number <n>] + [--in-reply-to=Message-Id] <since>[..<until>] DESCRIPTION @@ -35,6 +36,10 @@ they are created in the current working directory. If -n is specified, instead of "[PATCH] Subject", the first line is formatted as "[PATCH n/m] Subject". +If given --thread, git-format-patch will generate In-Reply-To and +References headers to make the second and subsequent patch mails appear +as replies to the first mail; this also generates a Message-Id header to +reference. OPTIONS ------- @@ -63,6 +68,15 @@ OPTIONS --attach:: Create attachments instead of inlining patches. +--thread:: + Add In-Reply-To and References headers to make the second and + subsequent mails appear as replies to the first. Also generates + the Message-Id header to reference. + +--in-reply-to=Message-Id:: + Make the first mail (or all the mails with --no-thread) appear as a + reply to the given Message-Id, which avoids breaking threads to + provide a new patch series. CONFIGURATION ------------- diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 8a150d861f..0a4fc14b97 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -25,7 +25,7 @@ DESCRIPTION ----------- This command creates an empty git repository - basically a `.git` directory with subdirectories for `objects`, `refs/heads`, `refs/tags`, and -templated files. +template files. An initial `HEAD` file that references the HEAD of the master branch is also created. diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt new file mode 100644 index 0000000000..7dd393b97f --- /dev/null +++ b/Documentation/git-instaweb.txt @@ -0,0 +1,84 @@ +git-instaweb(1) +=============== + +NAME +---- +git-instaweb - instantly browse your working repository in gitweb + +SYNOPSIS +-------- +'git-instaweb' [--local] [--httpd=<httpd>] [--port=<port>] [--browser=<browser>] + +'git-instaweb' [--start] [--stop] [--restart] + +DESCRIPTION +----------- +A simple script to setup gitweb and a web server for browsing the local +repository. + +OPTIONS +------- + +-l|--local:: + Only bind the web server to the local IP (127.0.0.1). + +-d|--httpd:: + 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 and apache2 are the only supported servers. + (Default: lighttpd) + +-m|--module-path:: + The module path (only needed if httpd is Apache). + (Default: /usr/lib/apache2/modules) + +-p|--port:: + The port number to bind the httpd to. (Default: 1234) + +-b|--browser:: + + The web browser command-line to execute to view the gitweb page. + If blank, the URL of the gitweb instance will be printed to + stdout. (Default: 'firefox') + +--start:: + Start the httpd instance and exit. This does not generate + any of the configuration files for spawning a new instance. + +--stop:: + Stop the httpd instance and exit. This does not generate + any of the configuration files for spawning a new instance, + nor does it close the browser. + +--restart:: + Restart the httpd instance and exit. This does not generate + any of the configuration files for spawning a new instance. + +CONFIGURATION +------------- + +You may specify configuration in your .git/config + +----------------------------------------------------------------------- +[instaweb] + local = true + httpd = apache2 -f + port = 4321 + browser = konqueror + modulepath = /usr/lib/apache2/modules + +----------------------------------------------------------------------- + +Author +------ +Written by Eric Wong <normalperson@yhbt.net> + +Documentation +-------------- +Documentation by Eric Wong <normalperson@yhbt.net>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 4d8a2ad2d7..8520b97111 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -207,7 +207,7 @@ An exclude pattern is of the following format: An example: -------------------------------------------------------------- - $ cat .git/ignore + $ cat .git/info/exclude # ignore objects and archives, anywhere in the tree. *.[oa] $ cat Documentation/.gitignore @@ -217,7 +217,7 @@ An example: !foo.html $ git-ls-files --ignored \ --exclude='Documentation/*.[0-9]' \ - --exclude-from=.git/ignore \ + --exclude-from=.git/info/exclude \ --exclude-per-directory=.gitignore -------------------------------------------------------------- diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index 209e36bacb..5a17801f6a 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -25,7 +25,7 @@ OPTIONS -b:: If any file doesn't begin with a From line, assume it is a - single mail message instead of signalling error. + single mail message instead of signaling error. -d<prec>:: Instead of the default 4 digits with leading zeros, diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 4ce799b520..bebf30ad3d 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -83,7 +83,7 @@ your local modifications interfere with the merge, again, it stops before touching anything. So in the above two "failed merge" case, you do not have to -worry about lossage of data --- you simply were not ready to do +worry about loss of data --- you simply were not ready to do a merge, so no merge happened at all. You may want to finish whatever you were in the middle of doing, and retry the same pull after you are done and ready. diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 39a1434a0e..37fbf66efb 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -26,14 +26,14 @@ OPTIONS List all commits reachable from all refs --stdin:: - Read from stdin, append "(<rev_name>)" to all sha1's of name'able + Read from stdin, append "(<rev_name>)" to all sha1's of nameable commits, and pass to stdout EXAMPLE ------- Given a commit, find out where it is relative to the local refs. Say somebody -wrote you about that phantastic commit 33db5f4d9027a10e477ccf054b2c1ab94f74c85a. +wrote you about that fantastic commit 33db5f4d9027a10e477ccf054b2c1ab94f74c85a. Of course, you look into the commit, but that only tells you what happened, but not the context. diff --git a/Documentation/git-p4import.txt b/Documentation/git-p4import.txt index 0858e5efbe..ee9e8fa909 100644 --- a/Documentation/git-p4import.txt +++ b/Documentation/git-p4import.txt @@ -128,7 +128,7 @@ Tags A git tag of the form p4/xx is created for every change imported from the Perforce repository where xx is the Perforce changeset number. Therefore after the import you can use git to access any commit by its -Perforce number, eg. git show p4/327. +Perforce number, e.g. git show p4/327. The tag associated with the HEAD commit is also how `git-p4import` determines if there are new changes to incrementally import from the @@ -143,7 +143,7 @@ may delete the tags. Notes ----- -You can interrupt the import (eg. ctrl-c) at any time and restart it +You can interrupt the import (e.g. ctrl-c) at any time and restart it without worry. Author information is automatically determined by querying the diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index 8fb0659438..7d54b17e37 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -29,7 +29,7 @@ OPTIONS --all:: - Processes all packs. Any filenames on the commandline are ignored. + Processes all packs. Any filenames on the command line are ignored. --alt-odb:: Don't require objects present in packs from alternate object diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index d5b5ca167c..56afd64f42 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -67,7 +67,7 @@ Some short-cut notations are also supported. -f, \--force:: Usually, the command refuses to update a remote ref that is - not a descendent of the local ref used to overwrite it. + not a descendant of the local ref used to overwrite it. This flag disables the check. This can cause the remote repository to lose commits; use it with care. diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index 803c0d5cae..b03d66f61c 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -119,8 +119,8 @@ you can set the filemode to true with % git repo-config core.filemode true ------------ -The hypothetic proxy command entries actually have a postfix to discern -to what URL they apply. Here is how to change the entry for kernel.org +The hypothetical proxy command entries actually have a postfix to discern +what URL they apply to. Here is how to change the entry for kernel.org to "ssh". ------------ diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index ad6d14c55a..f60eacd93e 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -15,6 +15,7 @@ SYNOPSIS [ \--sparse ] [ \--no-merges ] [ \--remove-empty ] + [ \--not ] [ \--all ] [ \--topo-order ] [ \--parents ] @@ -37,6 +38,14 @@ not in 'baz'". A special notation <commit1>..<commit2> can be used as a short-hand for {caret}<commit1> <commit2>. +Another special notation is <commit1>...<commit2> which is useful for +merges. The resulting set of commits is the symmetric difference +between the two operands. The following two commands are equivalent: + +------------ +$ git-rev-list A B --not $(git-merge-base --all A B) +$ git-rev-list A...B +------------ OPTIONS ------- @@ -47,6 +56,9 @@ OPTIONS Print the contents of the commit in raw-format; each record is separated with a NUL character. +--parents:: + Print the parents of the commit. + --objects:: Print the object IDs of any object referenced by the listed commits. 'git-rev-list --objects foo ^bar' thus means "send me all object IDs @@ -55,7 +67,7 @@ OPTIONS --objects-edge:: Similar to `--objects`, but also print the IDs of - excluded commits refixed with a `-` character. This is + excluded commits prefixed with a `-` character. This is used by `git-pack-objects` to build 'thin' pack, which records objects in deltified form based on objects contained in these excluded commits to reduce network @@ -93,6 +105,14 @@ OPTIONS --remove-empty:: Stop when a given path disappears from the tree. +--no-merges:: + Do not print commits with more than one parent. + +--not:: + Reverses the meaning of the '{caret}' prefix (or lack + thereof) for all following revision specifiers, up to + the next `--not`. + --all:: Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the command line as <commit>. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 627cde8520..b761b4b965 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -156,11 +156,6 @@ syntax. and dereference the tag recursively until a non-tag object is found. -'git-rev-parse' also accepts a prefix '{caret}' to revision parameter, -which is passed to 'git-rev-list'. Two revision parameters -concatenated with '..' is a short-hand for writing a range -between them. I.e. 'r1..r2' is equivalent to saying '{caret}r1 r2' - Here is an illustration, by Jon Loeliger. Both node B and C are a commit parents of commit node A. Parent commits are ordered left-to-right. @@ -168,9 +163,9 @@ left-to-right. G H I J \ / \ / D E F - \ | / - \ | / - \|/ + \ | / \ + \ | / | + \|/ | B C \ / \ / @@ -188,6 +183,40 @@ left-to-right. J = F^2 = B^3^2 = A^^3^2 +SPECIFYING RANGES +----------------- + +History traversing commands such as `git-log` operate on a set +of commits, not just a single commit. To these commands, +specifying a single revision with the notation described in the +previous section means the set of commits reachable from that +commit, following the commit ancestry chain. + +To exclude commits reachable from a commit, a prefix `{caret}` +notation is used. E.g. "`{caret}r1 r2`" means commits reachable +from `r2` but exclude the ones reachable from `r1`. + +This set operation appears so often that there is a shorthand +for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is +the difference of two sets (subtract the set of commits +reachable from `r1` from the set of commits reachable from +`r2`). + +A similar notation "`r1\...r2`" is called symmetric difference +of `r1` and `r2` and is defined as +"`r1 r2 --not $(git-merge-base --all r1 r2)`". +It it the set of commits that are reachable from either one of +`r1` or `r2` but not from both. + +Here are a few examples: + + D A B D + D F A B C D F + ^A G B D + ^A F B C F + G...I C D F G I + ^B G I C D F G I + Author ------ Written by Linus Torvalds <torvalds@osdl.org> and diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index f115b45ef6..a2445a48fc 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -52,6 +52,11 @@ OPTIONS appear in topological order (i.e., descendant commits are shown before their parents). +--sparse:: + By default, the output omits merges that are reachable + from only one tip being shown. This option makes them + visible. + --more=<n>:: Usually the command stops output upon showing the commit that is the common ancestor of all the branches. This diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt new file mode 100644 index 0000000000..7d86809844 --- /dev/null +++ b/Documentation/git-svn.txt @@ -0,0 +1,319 @@ +git-svn(1) +========== + +NAME +---- +git-svn - bidirectional operation between a single Subversion branch and git + +SYNOPSIS +-------- +'git-svn' <command> [options] [arguments] + +DESCRIPTION +----------- +git-svn is a simple conduit for changesets between a single Subversion +branch and git. + +git-svn is not to be confused with git-svnimport. The were designed +with very different goals in mind. + +git-svn is designed for an individual developer who wants a +bidirectional flow of changesets between a single branch in Subversion +and an arbitrary number of branches in git. git-svnimport is designed +for read-only operation on repositories that match a particular layout +(albeit the recommended one by SVN developers). + +For importing svn, git-svnimport is potentially more powerful when +operating on repositories organized under the recommended +trunk/branch/tags structure, and should be faster, too. + +git-svn mostly ignores the very limited view of branching that +Subversion has. This allows git-svn to be much easier to use, +especially on repositories that are not organized in a manner that +git-svnimport is designed for. + +COMMANDS +-------- +init:: + Creates an empty git repository with additional metadata + directories for git-svn. The Subversion URL must be specified + as a command-line argument. + +fetch:: + Fetch unfetched revisions from the Subversion URL we are + tracking. refs/remotes/git-svn will be updated to the + latest revision. + + Note: You should never attempt to modify the remotes/git-svn + branch outside of git-svn. Instead, create a branch from + remotes/git-svn and work on that branch. Use the 'commit' + command (see below) to write git commits back to + remotes/git-svn. + + See 'Additional Fetch Arguments' if you are interested in + manually joining branches on commit. + +commit:: + Commit specified commit or tree objects to SVN. This relies on + your imported fetch data being up-to-date. This makes + absolutely no attempts to do patching when committing to SVN, it + simply overwrites files with those specified in the tree or + commit. All merging is assumed to have taken place + independently of git-svn functions. + +rebuild:: + Not a part of daily usage, but this is a useful command if + you've just cloned a repository (using git-clone) that was + tracked with git-svn. Unfortunately, git-clone does not clone + git-svn metadata and the svn working tree that git-svn uses for + its operations. This rebuilds the metadata so git-svn can + resume fetch operations. A Subversion URL may be optionally + specified at the command-line if the directory/repository you're + tracking has moved or changed protocols. + +show-ignore:: + Recursively finds and lists the svn:ignore property on + directories. The output is suitable for appending to + the $GIT_DIR/info/exclude file. + +OPTIONS +------- +-r <ARG>:: +--revision <ARG>:: + Only used with the 'fetch' command. + + Takes any valid -r<argument> svn would accept and passes it + directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax + is also supported. This is passed directly to svn, see svn + documentation for more details. + + This can allow you to make partial mirrors when running fetch. + +-:: +--stdin:: + Only used with the 'commit' command. + + Read a list of commits from stdin and commit them in reverse + order. Only the leading sha1 is read from each line, so + git-rev-list --pretty=oneline output can be used. + +--rmdir:: + Only used with the 'commit' command. + + Remove directories from the SVN tree if there are no files left + behind. SVN can version empty directories, and they are not + removed by default if there are no files left in them. git + cannot version empty directories. Enabling this flag will make + the commit to SVN act like git. + + repo-config key: svn.rmdir + +-e:: +--edit:: + Only used with the 'commit' command. + + Edit the commit message before committing to SVN. This is off by + default for objects that are commits, and forced on when committing + tree objects. + + repo-config key: svn.edit + +-l<num>:: +--find-copies-harder:: + Both of these are only used with the 'commit' command. + + They are both passed directly to git-diff-tree see + git-diff-tree(1) for more information. + + repo-config key: svn.l + repo-config key: svn.findcopiesharder + +-A<filename>:: +--authors-file=<filename>:: + + Syntax is compatible with the files used by git-svnimport and + git-cvsimport: + +------------------------------------------------------------------------ +loginname = Joe User <user@example.com> +------------------------------------------------------------------------ + + If this option is specified and git-svn encounters an SVN + committer name that does not exist in the authors-file, git-svn + will abort operation. The user will then have to add the + appropriate entry. Re-running the previous git-svn command + after the authors-file is modified should continue operation. + + repo-config key: svn.authors-file + +ADVANCED OPTIONS +---------------- +-b<refname>:: +--branch <refname>:: + Used with 'fetch' or 'commit'. + + This can be used to join arbitrary git branches to remotes/git-svn + on new commits where the tree object is equivalent. + + When used with different GIT_SVN_ID values, tags and branches in + SVN can be tracked this way, as can some merges where the heads + end up having completely equivalent content. This can even be + used to track branches across multiple SVN _repositories_. + + This option may be specified multiple times, once for each + branch. + + repo-config key: svn.branch + +-i<GIT_SVN_ID>:: +--id <GIT_SVN_ID>:: + This sets GIT_SVN_ID (instead of using the environment). See + the section on "Tracking Multiple Repositories or Branches" for + more information on using GIT_SVN_ID. + +COMPATIBILITY OPTIONS +--------------------- +--upgrade:: + Only used with the 'rebuild' command. + + Run this if you used an old version of git-svn that used + "git-svn-HEAD" instead of "remotes/git-svn" as the branch + for tracking the remote. + +--no-ignore-externals:: + Only used with the 'fetch' and 'rebuild' command. + + By default, git-svn passes --ignore-externals to svn to avoid + fetching svn:external trees into git. Pass this flag to enable + externals tracking directly via git. + + Versions of svn that do not support --ignore-externals are + automatically detected and this flag will be automatically + enabled for them. + + Otherwise, do not enable this flag unless you know what you're + doing. + + repo-config key: svn.noignoreexternals + +Basic Examples +~~~~~~~~~~~~~~ + +Tracking and contributing to an Subversion managed-project: + +------------------------------------------------------------------------ +# Initialize a tree (like git init-db): + git-svn init http://svn.foo.org/project/trunk +# Fetch remote revisions: + git-svn fetch +# Create your own branch to hack on: + git checkout -b my-branch remotes/git-svn +# Commit only the git commits you want to SVN: + git-svn commit <tree-ish> [<tree-ish_2> ...] +# Commit all the git commits from my-branch that don't exist in SVN: + git-svn commit remotes/git-svn..my-branch +# Something is committed to SVN, pull the latest into your branch: + git-svn fetch && git pull . remotes/git-svn +# Append svn:ignore settings to the default git exclude file: + git-svn show-ignore >> .git/info/exclude +------------------------------------------------------------------------ + +DESIGN PHILOSOPHY +----------------- +Merge tracking in Subversion is lacking and doing branched development +with Subversion is cumbersome as a result. git-svn completely forgoes +any automated merge/branch tracking on the Subversion side and leaves it +entirely up to the user on the git side. It's simply not worth it to do +a useful translation when the original signal is weak. + +TRACKING MULTIPLE REPOSITORIES OR BRANCHES +------------------------------------------ +This is for advanced users, most users should ignore this section. + +Because git-svn does not care about relationships between different +branches or directories in a Subversion repository, git-svn has a simple +hack to allow it to track an arbitrary number of related _or_ unrelated +SVN repositories via one git repository. Simply set the GIT_SVN_ID +environment variable to a name other other than "git-svn" (the default) +and git-svn will ignore the contents of the $GIT_DIR/git-svn directory +and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that +invocation. The interface branch will be remotes/$GIT_SVN_ID, instead of +remotes/git-svn. Any remotes/$GIT_SVN_ID branch should never be modified +by the user outside of git-svn commands. + +ADDITIONAL FETCH ARGUMENTS +-------------------------- +This is for advanced users, most users should ignore this section. + +Unfetched SVN revisions may be imported as children of existing commits +by specifying additional arguments to 'fetch'. Additional parents may +optionally be specified in the form of sha1 hex sums at the +command-line. Unfetched SVN revisions may also be tied to particular +git commits with the following syntax: + + svn_revision_number=git_commit_sha1 + +This allows you to tie unfetched SVN revision 375 to your current HEAD:: + + `git-svn fetch 375=$(git-rev-parse HEAD)` + +Advanced Example: Tracking a Reorganized Repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you're tracking a directory that has moved, or otherwise been +branched or tagged off of another directory in the repository and you +care about the full history of the project, then you can read this +section. + +This is how Yann Dirson tracked the trunk of the ufoai directory when +the /trunk directory of his repository was moved to /ufoai/trunk and +he needed to continue tracking /ufoai/trunk where /trunk left off. + +------------------------------------------------------------------------ + # This log message shows when the repository was reorganized: + r166 | ydirson | 2006-03-02 01:36:55 +0100 (Thu, 02 Mar 2006) | 1 line + Changed paths: + D /trunk + A /ufoai/trunk (from /trunk:165) + + # First we start tracking the old revisions: + GIT_SVN_ID=git-oldsvn git-svn init \ + https://svn.sourceforge.net/svnroot/ufoai/trunk + GIT_SVN_ID=git-oldsvn git-svn fetch -r1:165 + + # And now, we continue tracking the new revisions: + GIT_SVN_ID=git-newsvn git-svn init \ + https://svn.sourceforge.net/svnroot/ufoai/ufoai/trunk + GIT_SVN_ID=git-newsvn git-svn fetch \ + 166=`git-rev-parse refs/remotes/git-oldsvn` +------------------------------------------------------------------------ + +BUGS +---- +If somebody commits a conflicting changeset to SVN at a bad moment +(right before you commit) causing a conflict and your commit to fail, +your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied. The +easiest thing to do is probably just to rm -rf $GIT_DIR/git-svn/tree and +run 'rebuild'. + +We ignore all SVN properties except svn:executable. Too difficult to +map them since we rely heavily on git write-tree being _exactly_ the +same on both the SVN and git working trees and I prefer not to clutter +working trees with metadata files. + +svn:keywords can't be ignored in Subversion (at least I don't know of +a way to ignore them). + +Renamed and copied directories are not detected by git and hence not +tracked when committing to SVN. I do not plan on adding support for +this as it's quite difficult and time-consuming to get working for all +the possible corner cases (git doesn't do it, either). Renamed and +copied files are fully supported if they're similar enough for git to +detect them. + +Author +------ +Written by Eric Wong <normalperson@yhbt.net>. + +Documentation +------------- +Written by Eric Wong <normalperson@yhbt.net>. diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index f2675c4193..7a99acf2ec 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -37,7 +37,20 @@ OPTIONS Instead of making a tar archive from local repository, retrieve a tar archive from a remote repository. -Examples +CONFIGURATION +------------- +By default, file and directories modes are set to 0666 or 0777. It is +possible to change this by setting the "umask" variable in the +repository configuration as follows : + +[tar] + umask = 002 ;# group friendly + +The special umask value "user" indicates that the user's current umask +will be used instead. The default value remains 0, which means world +readable/writable files and directories. + +EXAMPLES -------- git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -):: diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt index d79523f56d..0914cbb0ba 100644 --- a/Documentation/git-tools.txt +++ b/Documentation/git-tools.txt @@ -42,7 +42,7 @@ History Viewers - *gitk* (shipped with git-core) - gitk is a simple TK GUI for browsing history of GIT repositories easily. + gitk is a simple Tk GUI for browsing history of GIT repositories easily. - *gitview* (contrib/) diff --git a/Documentation/git-upload-tar.txt b/Documentation/git-upload-tar.txt index a1019a0231..394af62015 100644 --- a/Documentation/git-upload-tar.txt +++ b/Documentation/git-upload-tar.txt @@ -17,7 +17,7 @@ to the other end over the git protocol. This command is usually not invoked directly by the end user. The UI for the protocol is on the 'git-tar-tree' side, and the -program pair is meant to be used to get a tar achive from a +program pair is meant to be used to get a tar archive from a remote repository. diff --git a/Documentation/git.txt b/Documentation/git.txt index 51f20c6e67..ce3058182f 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -478,7 +478,7 @@ Configuration Mechanism Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file is used to hold per-repository configuration options. It is a -simple text file modelled after `.ini` format familiar to some +simple text file modeled after `.ini` format familiar to some people. Here is an example: ------------ @@ -615,6 +615,13 @@ git Diffs gitlink:git-diff-files[1]; gitlink:git-diff-tree[1] +other +~~~~~ +'GIT_TRACE':: + If this variable is set git will print `trace:` messages on + stderr telling about alias expansion, built-in command + execution and external command execution. + Discussion[[Discussion]] ------------------------ include::README[] diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index 116ddb7fbf..14449ca8ba 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -86,7 +86,7 @@ directory:: ent:: Favorite synonym to "tree-ish" by some total geeks. See `http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth - explanation. + explanation. Avoid this term, not to confuse people. fast forward:: A fast-forward is a special type of merge where you have diff --git a/Documentation/howto/isolate-bugs-with-bisect.txt b/Documentation/howto/isolate-bugs-with-bisect.txt index edbcd4c661..926bbdc3cb 100644 --- a/Documentation/howto/isolate-bugs-with-bisect.txt +++ b/Documentation/howto/isolate-bugs-with-bisect.txt @@ -28,7 +28,7 @@ Then do and at this point "git bisect" will churn for a while, and tell you what the mid-point between those two commits are, and check that state out as -the head of the bew "bisect" branch. +the head of the new "bisect" branch. Compile and reboot. diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.txt index c2d4a91c7c..fcd64e9b9b 100644 --- a/Documentation/howto/rebase-from-internal-branch.txt +++ b/Documentation/howto/rebase-from-internal-branch.txt @@ -124,7 +124,7 @@ up your changes, along with other changes. The two commits #2' and #3' in the above picture record the same changes your e-mail submission for #2 and #3 contained, but -probably with the new sign-off line added by the upsteam +probably with the new sign-off line added by the upstream maintainer and definitely with different committer and ancestry information, they are different objects from #2 and #3 commits. diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index b52dfdc308..275d18bb54 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -120,9 +120,11 @@ info/grafts:: info/exclude:: This file, by convention among Porcelains, stores the - exclude pattern list. `git status` looks at it, but - otherwise it is not looked at by any of the core git - commands. + exclude pattern list. `.gitignore` is the per-directory + ignore file. `git status`, `git add`, `git rm` and `git + clean` look at it but the core git commands do not look + at it. See also: gitlink:git-ls-files[1] `--exclude-from` + and `--exclude-per-directory`. remotes:: Stores shorthands to be used to give URL and default diff --git a/Documentation/technical/pack-heuristics.txt b/Documentation/technical/pack-heuristics.txt index 9aadd5cee5..103eb5d989 100644 --- a/Documentation/technical/pack-heuristics.txt +++ b/Documentation/technical/pack-heuristics.txt @@ -73,7 +73,7 @@ The traditional insight: <pasky> yes -And Bable-like confusion flowed. +And Babel-like confusion flowed. <njs`> oh, hmm, and I'm not sure what this sliding window means either @@ -257,7 +257,7 @@ proclaim it a non-issue. Good style too! (type, basename, size)). Then we walk through this list, and calculate a delta of - each object against the last n (tunable paramater) objects, + each object against the last n (tunable parameter) objects, and pick the smallest of these deltas. Vastly simplified, but the essence is there! @@ -395,7 +395,7 @@ used as setup for a later optimization, which is a real word: do "object name->location in packfile" translation. <njs`> I'm assuming the real win for delta-ing large->small is - more homogenous statistics for gzip to run over? + more homogeneous statistics for gzip to run over? (You have to put the bytes in one place or another, but putting them in a larger blob wins on compression) @@ -448,7 +448,7 @@ design options, etc. Bugs happen, but they are "simple" bugs. And bugs that actually get some object store detail wrong are almost always - so obious that they never go anywhere. + so obvious that they never go anywhere. <njs`> Yeah. diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 74774134e3..26ecba53fb 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -10,20 +10,21 @@ to name the remote repository: - https://host.xz/path/to/repo.git/ - git://host.xz/path/to/repo.git/ - git://host.xz/~user/path/to/repo.git/ -- ssh://host.xz/path/to/repo.git/ -- ssh://host.xz/~user/path/to/repo.git/ -- ssh://host.xz/~/path/to/repo.git +- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/ +- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/ +- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git =============================================================== -SSH Is the default transport protocol and also supports an -scp-like syntax. Both syntaxes support username expansion, +SSH is the default transport protocol. You can optionally specify +which user to log-in as, and an alternate, scp-like syntax is also +supported. Both syntaxes support username expansion, as does the native git protocol. The following three are identical to the last three above, respectively: =============================================================== -- host.xz:/path/to/repo.git/ -- host.xz:~user/path/to/repo.git/ -- host.xz:path/to/repo.git +- {startsb}user@{endsb}host.xz:/path/to/repo.git/ +- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/ +- {startsb}user@{endsb}host.xz:path/to/repo.git =============================================================== To sync with a local directory, use: @@ -47,7 +48,7 @@ Then such a short-hand is specified in place of <repository> without <refspec> parameters on the command line, <refspec> specified on `Push:` lines or `Pull:` lines are used for `git-push` and `git-fetch`/`git-pull`, -respectively. Multiple `Push:` and and `Pull:` lines may +respectively. Multiple `Push:` and `Pull:` lines may be specified for additional branch mappings. The name of a file in `$GIT_DIR/branches` directory can be |