diff options
Diffstat (limited to 'Documentation')
83 files changed, 926 insertions, 241 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index a3bca86cb0..f4cbf7e159 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,4 +1,7 @@ -MAN1_TXT=$(wildcard git-*.txt) gitk.txt +MAN1_TXT= \ + $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ + $(wildcard git-*.txt)) \ + gitk.txt MAN7_TXT=git.txt DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) @@ -11,6 +14,7 @@ ARTICLES += howto-index ARTICLES += repository-layout ARTICLES += hooks ARTICLES += everyday +ARTICLES += git-tools # with their own formatting rules. SP_ARTICLES = glossary howto/revert-branch-rebase diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 9ccb8f72ed..318b04fdeb 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -4,8 +4,8 @@ it for the core GIT to make sure people understand what they are doing when they write "Signed-off-by" line. But the patch submission requirements are a lot more relaxed -here, because the core GIT is thousand times smaller ;-). So -here is only the relevant bits. +here on the technical/contents front, because the core GIT is +thousand times smaller ;-). So here is only the relevant bits. (1) Make separate commits for logically separate changes. @@ -18,13 +18,19 @@ repository. It is a good discipline. Describe the technical detail of the change(s). -If your description starts to get long, that's a sign that you +If your description starts to get too long, that's a sign that you probably need to split up your commit to finer grained pieces. +Oh, another thing. I am picky about whitespaces. Make sure your +changes do not trigger errors with the sample pre-commit hook shipped +in templates/hooks--pre-commit. -(2) Generate your patch using git/cogito out of your commits. -git diff tools generate unidiff which is the preferred format. +(2) Generate your patch using git tools out of your commits. + +git based diff tools (git, Cogito, and StGIT included) generate +unidiff which is the preferred format. + You do not have to be afraid to use -M option to "git diff" or "git format-patch", if your patch involves file renames. The receiving end can handle them just fine. @@ -33,20 +39,22 @@ Please make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch after generating it, to ensure accuracy. Before sending out, please make sure it cleanly applies to the "master" -branch head. +branch head. If you are preparing a work based on "next" branch, +that is fine, but please mark it as such. (3) Sending your patches. -People on the git mailing list needs to be able to read and +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 submitting -e-mail "inline". WARNING: Be wary of your MUAs word-wrap -corrupting your patch. Do not cut-n-paste your patch. +your code. For this reason, all patches should be submited +"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. -It is common convention to prefix your subject line with +It is a common convention to prefix your subject line with [PATCH]. This lets people easily distinguish patches from other e-mail discussions. diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index fa0877d483..7ce71510de 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -18,6 +18,16 @@ ifdef::backend-docbook[] {0#</citerefentry>} endif::backend-docbook[] +ifdef::backend-docbook[] +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +[listingblock] +<example><title>{title}</title> +<literallayout> +| +</literallayout> +{title#}</example> +endif::backend-docbook[] + ifdef::backend-xhtml11[] [gitlink-inlinemacro] <a href="{target}.html">{target}{0?({0})}</a> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 7e293834d1..ae24547c8a 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -3,7 +3,7 @@ git-add(1) NAME ---- -git-add - Add files to the index file. +git-add - Add files to the index file SYNOPSIS -------- @@ -65,6 +65,9 @@ git-add git-*.sh:: (i.e. you are listing the files explicitly), it does not add `subdir/git-foo.sh` to the index. +See Also +-------- +gitlink:git-rm[1] Author ------ diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 02cabc935e..910457d3b3 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,7 +9,8 @@ git-am - Apply a series of patches in a mailbox SYNOPSIS -------- [verse] -'git-am' [--signoff] [--dotest=<dir>] [--utf8] [--binary] [--3way] <mbox>... +'git-am' [--signoff] [--dotest=<dir>] [--utf8] [--binary] [--3way] + [--interactive] [--whitespace=<option>] <mbox>... 'git-am' [--skip | --resolved] DESCRIPTION @@ -46,6 +47,10 @@ OPTIONS Skip the current patch. This is only meaningful when restarting an aborted patch. +--whitespace=<option>:: + This flag is passed to the `git-apply` program that applies + the patch. + --interactive:: Run interactively, just like git-applymbox. @@ -80,7 +85,7 @@ names. SEE ALSO -------- -gitlink:git-applymbox[1], gitlink:git-applypatch[1]. +gitlink:git-applymbox[1], gitlink:git-applypatch[1], gitlink:git-apply[1]. Author diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 75076b6121..1c64a1aa82 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply] [--no-add] [--index-info] [--allow-binary-replacement] [-z] [-pNUM] + [--whitespace=<nowarn|warn|error|error-all|strip>] [<patch>...] DESCRIPTION @@ -97,6 +98,35 @@ OPTIONS result. This allows binary files to be patched in a very limited way. +--whitespace=<option>:: + When applying a patch, detect a new or modified line + that ends with trailing whitespaces (this includes a + line that solely consists of whitespaces). By default, + the command outputs warning messages and applies the + patch. + When `git-apply` is used for statistics and not applying a + patch, it defaults to `nowarn`. + You can use different `<option>` to control this + behaviour: ++ +* `nowarn` turns off the trailing whitespace warning. +* `warn` outputs warnings for a few such errors, but applies the + patch (default). +* `error` outputs warnings for a few such errors, and refuses + to apply the patch. +* `error-all` is similar to `error` but shows all errors. +* `strip` outputs warnings for a few such errors, strips out the + trailing whitespaces and applies the patch. + + +Configuration +------------- + +apply.whitespace:: + When no `--whitespace` flag is given from the command + line, this configuration item is used as the default. + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-applypatch.txt b/Documentation/git-applypatch.txt index 5b9037de9f..2b1ff1454b 100644 --- a/Documentation/git-applypatch.txt +++ b/Documentation/git-applypatch.txt @@ -3,7 +3,7 @@ git-applypatch(1) NAME ---- -git-applypatch - Apply one patch extracted from an e-mail. +git-applypatch - Apply one patch extracted from an e-mail SYNOPSIS diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index 023d3ae7b9..5a13187a87 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -9,7 +9,7 @@ git-archimport - Import an Arch repository into git SYNOPSIS -------- [verse] -`git-archimport` [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] +'git-archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] <archive/branch> [ <archive/branch> ] DESCRIPTION diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index b1bc8272eb..71ecd858aa 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -3,20 +3,24 @@ git-branch(1) NAME ---- -git-branch - Create a new branch, or remove an old one. +git-branch - Create a new branch, or remove an old one SYNOPSIS -------- -'git-branch' [(-d | -D) <branchname>] | [[-f] <branchname> [<start-point>]] +[verse] +'git-branch' [[-f] <branchname> [<start-point>]] +'git-branch' (-d | -D) <branchname> DESCRIPTION ----------- If no argument is provided, show available branches and mark current branch with star. Otherwise, create a new branch of name <branchname>. - If a starting point is also specified, that will be where the branch is created, otherwise it will be created at the current HEAD. +With a `-d` or `-D` option, `<branchname>` will be deleted. + + OPTIONS ------- -d:: @@ -39,7 +43,7 @@ OPTIONS Examples ~~~~~~~~ -Start development off of a know tag:: +Start development off of a known tag:: + ------------ $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index f7f84c644e..7dc1bdb6ef 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -3,7 +3,7 @@ git-check-ref-format(1) NAME ---- -git-check-ref-format - Make sure ref name is well formed. +git-check-ref-format - Make sure ref name is well formed SYNOPSIS -------- diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 2a1e526c6a..09bd6a5535 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -10,7 +10,10 @@ SYNOPSIS -------- [verse] 'git-checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] - [--stage=<number>] [--] <file>... + [--stage=<number>|all] + [--temp] + [-z] [--stdin] + [--] [<file>]\* DESCRIPTION ----------- @@ -41,9 +44,24 @@ OPTIONS When creating files, prepend <string> (usually a directory including a trailing /) ---stage=<number>:: +--stage=<number>|all:: Instead of checking out unmerged entries, copy out the files from named stage. <number> must be between 1 and 3. + Note: --stage=all automatically implies --temp. + +--temp:: + Instead of copying the files to the working directory + write the content to temporary files. The temporary name + associations will be written to stdout. + +--stdin:: + Instead of taking list of paths from the command line, + read list of paths from the standard input. Paths are + separated by LF (i.e. one path per line) by default. + +-z:: + Only meaningful with `--stdin`; paths are separated with + NUL character instead of LF. --:: Do not interpret any more arguments as options. @@ -64,13 +82,58 @@ $ find . -name '*.h' -print0 | xargs -0 git-checkout-index -f -- which will force all existing `*.h` files to be replaced with their cached copies. If an empty command line implied "all", then this would -force-refresh everything in the index, which was not the point. +force-refresh everything in the index, which was not the point. But +since git-checkout-index accepts --stdin it would be faster to use: + +---------------- +$ find . -name '*.h' -print0 | git-checkout-index -f -z --stdin +---------------- The `--` is just a good idea when you know the rest will be filenames; it will prevent problems with a filename of, for example, `-a`. Using `--` is probably a good policy in scripts. +Using --temp or --stage=all +--------------------------- +When `--temp` is used (or implied by `--stage=all`) +`git-checkout-index` will create a temporary file for each index +entry being checked out. The index will not be updated with stat +information. These options can be useful if the caller needs all +stages of all unmerged entries so that the unmerged files can be +processed by an external merge tool. + +A listing will be written to stdout providing the association of +temporary file names to tracked path names. The listing format +has two variations: + + . tempname TAB path RS ++ +The first format is what gets used when `--stage` is omitted or +is not `--stage=all`. The field tempname is the temporary file +name holding the file content and path is the tracked path name in +the index. Only the requested entries are output. + + . stage1temp SP stage2temp SP stage3tmp TAB path RS ++ +The second format is what gets used when `--stage=all`. The three +stage temporary fields (stage1temp, stage2temp, stage3temp) list the +name of the temporary file if there is a stage entry in the index +or `.` if there is no stage entry. Paths which only have a stage 0 +entry will always be omitted from the output. + +In both formats RS (the record separator) is newline by default +but will be the null byte if -z was passed on the command line. +The temporary file names are always safe strings; they will never +contain directory separators or whitespace characters. The path +field is always relative to the current directory and the temporary +file names are always relative to the top level directory. + +If the object being copied out to a temporary file is a symbolic +link the content of the link will be written to a normal file. It is +up to the end-user or the Porcelain to make use of this information. + + EXAMPLES -------- To update and refresh only the files already checked out:: diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index df9a618674..985bb2f827 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -3,19 +3,22 @@ git-checkout(1) NAME ---- -git-checkout - Checkout and switch to a branch. +git-checkout - Checkout and switch to a branch SYNOPSIS -------- -'git-checkout' [-f] [-b <new_branch>] [-m] [<branch>] [<paths>...] +[verse] +'git-checkout' [-f] [-b <new_branch>] [-m] [<branch>] +'git-checkout' [-m] [<branch>] <paths>... DESCRIPTION ----------- -When <paths> are not given, this command switches branches, by +When <paths> are not given, this command switches branches by updating the index and working tree to reflect the specified branch, <branch>, and updating HEAD to be <branch> or, if -specified, <new_branch>. +specified, <new_branch>. Using -b will cause <new_branch> to +be created. When <paths> are given, this command does *not* switch branches. It updates the named paths in the working tree from @@ -29,17 +32,17 @@ given paths before updating the working tree. OPTIONS ------- -f:: - Force an re-read of everything. + Force a re-read of everything. -b:: Create a new branch and start it at <branch>. -m:: - If you have local modifications to a file that is - different between the current branch and the branch you - are switching to, the command refuses to switch - branches, to preserve your modifications in context. - With this option, a three-way merge between the current + If you have local modifications to one or more files that + are different between the current branch and the branch to + which you are switching, the command refuses to switch + branches in order to preserve your modifications in context. + However, with this option, a three-way merge between the current branch, your working tree contents, and the new branch is done, and you will be on the new branch. + @@ -82,7 +85,7 @@ $ git checkout -- hello.c ------------ . After working in a wrong branch, switching to the correct -branch you would want to is done with: +branch would be done using: + ------------ $ git checkout mytopic diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 4f323fa42a..bfa950ca19 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -3,7 +3,7 @@ git-cherry-pick(1) NAME ---- -git-cherry-pick - Apply the change introduced by an existing commit. +git-cherry-pick - Apply the change introduced by an existing commit SYNOPSIS -------- diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index af87966e51..9a5e37186f 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -3,7 +3,7 @@ git-cherry(1) NAME ---- -git-cherry - Find commits not merged upstream. +git-cherry - Find commits not merged upstream SYNOPSIS -------- diff --git a/Documentation/git-clone-pack.txt b/Documentation/git-clone-pack.txt index 39906fc450..09f43eefe4 100644 --- a/Documentation/git-clone-pack.txt +++ b/Documentation/git-clone-pack.txt @@ -3,7 +3,7 @@ git-clone-pack(1) NAME ---- -git-clone-pack - Clones a repository by receiving packed objects. +git-clone-pack - Clones a repository by receiving packed objects SYNOPSIS diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 684e4bdf69..9ac54c282c 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -3,7 +3,7 @@ git-clone(1) NAME ---- -git-clone - Clones a repository. +git-clone - Clones a repository SYNOPSIS diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 5b1b4d3780..d04b342a95 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -18,6 +18,10 @@ Updates the index file for given paths, or all modified files if VISUAL and EDITOR environment variables to edit the commit log message. +Several environment variable are used during commits. They are +documented in gitlink:git-commit-tree[1]. + + This command can run `commit-msg`, `pre-commit`, and `post-commit` hooks. See link:hooks.html[hooks] for more information. @@ -85,27 +89,12 @@ OPTIONS <file>...:: Files to be committed. The meaning of these is different between `--include` and `--only`. Without - either, it defaults `--include` semantics. + either, it defaults `--only` semantics. If you make a commit and then found a mistake immediately after that, you can recover from it with gitlink:git-reset[1]. -WARNING -------- - -The 1.2.0 and its maintenance series 1.2.X will keep the -traditional `--include` semantics as the default when neither -`--only` nor `--include` is specified and `paths...` are given. -This *will* change during the development towards 1.3.0 in the -'master' branch of `git.git` repository. If you are using this -command in your scripts, and you depend on the traditional -`--include` semantics, please update them to explicitly ask for -`--include` semantics. Also if you are used to making partial -commit using `--include` semantics, please train your fingers to -say `git commit --include paths...` (or `git commit -i paths...`). - - Discussion ---------- @@ -121,7 +110,7 @@ even the command is invoked from a subdirectory. That is, update the specified paths to the index and then commit the whole tree. -`git commit --only paths...` largely bypasses the index file and +`git commit paths...` largely bypasses the index file and commits only the changes made to the specified paths. It has however several safety valves to prevent confusion. diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 36888d98bf..47216f488b 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -3,7 +3,7 @@ git-count-objects(1) NAME ---- -git-count-objects - Reports on unpacked objects. +git-count-objects - Reports on unpacked objects SYNOPSIS -------- diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index dfe86ceea3..b0c6d7c303 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -22,6 +22,12 @@ repository, or incrementally import into an existing one. Splitting the CVS log into patch sets is done by 'cvsps'. At least version 2.1 is required. +You should *never* do any work of your own on the branches that are +created by git-cvsimport. The initial import will create and populate a +"master" branch from the CVS repository's main branch which you're free +to work with; after that, you need to 'git merge' incremental imports, or +any CVS branches, yourself. + OPTIONS ------- -d <CVSROOT>:: @@ -93,21 +99,24 @@ If you need to pass multiple options, separate them with a comma. CVS by default uses the unix username when writing its commit logs. Using this option and an author-conv-file in this format - ++ +--------- exon=Andreas Ericsson <ae@op5.se> spawn=Simon Pawn <spawn@frog-pond.org> - git-cvsimport will make it appear as those authors had - their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly - all along. - - For convenience, this data is saved to $GIT_DIR/cvs-authors - each time the -A option is provided and read from that same - file each time git-cvsimport is run. - - It is not recommended to use this feature if you intend to - export changes back to CVS again later with - git-link[1]::git-cvsexportcommit. +--------- ++ +git-cvsimport will make it appear as those authors had +their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly +all along. ++ +For convenience, this data is saved to $GIT_DIR/cvs-authors +each time the -A option is provided and read from that same +file each time git-cvsimport is run. ++ +It is not recommended to use this feature if you intend to +export changes back to CVS again later with +git-link[1]::git-cvsexportcommit. OUTPUT ------ diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt new file mode 100644 index 0000000000..4dc13c35db --- /dev/null +++ b/Documentation/git-cvsserver.txt @@ -0,0 +1,148 @@ +git-cvsserver(1) +================ + +NAME +---- +git-cvsserver - A CVS server emulator for git + +SYNOPSIS +-------- +[verse] +export CVS_SERVER=git-cvsserver +'cvs' -d :ext:user@server/path/repo.git co <HEAD_name> + +DESCRIPTION +----------- + +This application is a CVS emulation layer for git. + +It is highly functional. However, not all methods are implemented, +and for those methods that are implemented, +not all switches are implemented. + +Testing has been done using both the CLI CVS client, and the Eclipse CVS +plugin. Most functionality works fine with both of these clients. + +LIMITATIONS +----------- + +Currently cvsserver works over SSH connections for read/write clients, and +over pserver for anonymous CVS access. + +CVS clients cannot tag, branch or perform GIT merges. + +INSTALLATION +------------ + +1. If you are going to offer anonymous CVS access via pserver, add a line in + /etc/inetd.conf like + + cvspserver stream tcp nowait nobody git-cvsserver pserver + + Note: In some cases, you need to pass the 'pserver' argument twice for + git-cvsserver to see it. So the line would look like + + cvspserver stream tcp nowait nobody git-cvsserver pserver pserver + + No special setup is needed for SSH access, other than having GIT tools + in the PATH. If you have clients that do not accept the CVS_SERVER + env variable, you can rename git-cvsserver to cvs. + +2. For each repo that you want accessible from CVS you need to edit config in + the repo and add the following section. + + [gitcvs] + enabled=1 + # optional for debugging + logfile=/path/to/logfile + + Note: you need to ensure each user that is going to invoke git-cvsserver has + write access to the log file and to the git repository. When offering anon + access via pserver, this means that the nobody user should have write access + to at least the sqlite database at the root of the repository. + +3. On the client machine you need to set the following variables. + CVSROOT should be set as per normal, but the directory should point at the + appropriate git repo. For example: + + For SSH access, CVS_SERVER should be set to git-cvsserver + + Example: + + export CVSROOT=:ext:user@server:/var/git/project.git + export CVS_SERVER=git-cvsserver + +4. For SSH clients that will make commits, make sure their .bashrc file + sets the GIT_AUTHOR and GIT_COMMITTER variables. + +5. Clients should now be able to check out the project. Use the CVS 'module' + name to indicate what GIT 'head' you want to check out. Example: + + cvs co -d project-master master + +Eclipse CVS Client Notes +------------------------ + +To get a checkout with the Eclipse CVS client: + +1. Select "Create a new project -> From CVS checkout" +2. Create a new location. See the notes below for details on how to choose the + right protocol. +3. Browse the 'modules' available. It will give you a list of the heads in + the repository. You will not be able to browse the tree from there. Only + the heads. +4. Pick 'HEAD' when it asks what branch/tag to check out. Untick the + "launch commit wizard" to avoid committing the .project file. + +Protocol notes: If you are using anonymous acces via pserver, just select that. +Those using SSH access should choose the 'ext' protocol, and configure 'ext' +access on the Preferences->Team->CVS->ExtConnection pane. Set CVS_SERVER to +'git-cvsserver'. Not that password support is not good when using 'ext', +you will definitely want to have SSH keys setup. + +Alternatively, you can just use the non-standard extssh protocol that Eclipse +offer. In that case CVS_SERVER is ignored, and you will have to replace +the cvs utility on the server with git-cvsserver or manipulate your .bashrc +so that calling 'cvs' effectively calls git-cvsserver. + +Clients known to work +--------------------- + +CVS 1.12.9 on Debian +CVS 1.11.17 on MacOSX (from Fink package) +Eclipse 3.0, 3.1.2 on MacOSX (see Eclipse CVS Client Notes) +TortoiseCVS + +Operations supported +-------------------- + +All the operations required for normal use are supported, including +checkout, diff, status, update, log, add, remove, commit. +Legacy monitoring operations are not supported (edit, watch and related). +Exports and tagging (tags and branches) are not supported at this stage. + +The server will set the -k mode to binary when relevant. In proper GIT +tradition, the contents of the files are always respected. +No keyword expansion or newline munging is supported. + +Dependencies +------------ + +git-cvsserver depends on DBD::SQLite. + +Copyright and Authors +--------------------- + +This program is copyright The Open University UK - 2006. + +Authors: Martyn Smith <martyn@catalyst.net.nz> + Martin Langhoff <martin@catalyst.net.nz> + with ideas and patches from participants of the git-list <git@vger.kernel.org>. + +Documentation +-------------- +Documentation by Martyn Smith <martyn@catalyst.net.nz> and Martin Langhoff <martin@catalyst.net.nz> Matthias Urlichs <smurf@smurf.noris.de>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 2cc6075fb0..924a676a6a 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -3,7 +3,7 @@ git-daemon(1) NAME ---- -git-daemon - A really simple server for git repositories. +git-daemon - A really simple server for git repositories SYNOPSIS -------- diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 0efe82ae1e..7a253eaf28 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -3,7 +3,7 @@ git-describe(1) NAME ---- -git-describe - Show the most recent tag that is reachable from a commit. +git-describe - Show the most recent tag that is reachable from a commit SYNOPSIS diff --git a/Documentation/git-diff-stages.txt b/Documentation/git-diff-stages.txt index 28c60fc7e4..3273918627 100644 --- a/Documentation/git-diff-stages.txt +++ b/Documentation/git-diff-stages.txt @@ -3,7 +3,7 @@ git-diff-stages(1) NAME ---- -git-diff-stages - Compares content and mode of blobs between stages in an unmerged index file. +git-diff-stages - Compares content and mode of blobs between stages in an unmerged index file SYNOPSIS diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index ca41634022..890931c891 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -3,7 +3,7 @@ git-diff(1) NAME ---- -git-diff - Show changes between commits, commit and working tree, etc. +git-diff - Show changes between commits, commit and working tree, etc SYNOPSIS diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index b507e9b648..bff9aa6939 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -3,12 +3,12 @@ git-fetch-pack(1) NAME ---- -git-fetch-pack - Receive missing objects from another repository. +git-fetch-pack - Receive missing objects from another repository SYNOPSIS -------- -git-fetch-pack [-q] [-k] [--exec=<git-upload-pack>] [<host>:]<directory> [<refs>...] +'git-fetch-pack' [-q] [-k] [--exec=<git-upload-pack>] [<host>:]<directory> [<refs>...] DESCRIPTION ----------- diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index a67dc340fd..a9e86fd26b 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -3,7 +3,7 @@ git-fetch(1) NAME ---- -git-fetch - Download objects and a head from another repository. +git-fetch - Download objects and a head from another repository SYNOPSIS diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 9ac0636850..7cc7fafc1d 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -3,13 +3,13 @@ git-format-patch(1) NAME ---- -git-format-patch - Prepare patches for e-mail submission. +git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git-format-patch' [-n | -k] [-o <dir> | --stdout] [-s] [-c] +'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--attach] [-s] [-c] [--diff-options] <his> [<mine>] DESCRIPTION @@ -60,6 +60,18 @@ OPTIONS standard output, instead of saving them into a file per patch and implies --mbox. +--attach:: + Create attachments instead of inlining patches. + + +CONFIGURATION +------------- +You can specify extra mail header lines to be added to each +message in the repository configuration as follows: + +[format] + headers = "Organization: git-foo\n" + EXAMPLES -------- diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt index 387b435484..93ce9dcc92 100644 --- a/Documentation/git-fsck-objects.txt +++ b/Documentation/git-fsck-objects.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git-fsck-objects' [--tags] [--root] [--unreachable] [--cache] - [--standalone | --full] [--strict] [<object>*] + [--full] [--strict] [<object>*] DESCRIPTION ----------- @@ -38,21 +38,14 @@ index file and all SHA1 references in .git/refs/* as heads. Consider any object recorded in the index also as a head node for an unreachability trace. ---standalone:: - Limit checks to the contents of GIT_OBJECT_DIRECTORY - ($GIT_DIR/objects), making sure that it is consistent and - complete without referring to objects found in alternate - object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES, - nor packed git archives found in $GIT_DIR/objects/pack; - cannot be used with --full. - --full:: Check not just objects in GIT_OBJECT_DIRECTORY ($GIT_DIR/objects), but also the ones found in alternate - object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES, + object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES + or $GIT_DIR/objects/info/alternates, and in packed git archives found in $GIT_DIR/objects/pack and corresponding pack subdirectories in alternate - object pools; cannot be used with --standalone. + object pools. --strict:: Enable more strict checking, namely to catch a file mode diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 30b1fbf6e7..48805b651c 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -3,7 +3,7 @@ git-get-tar-commit-id(1) NAME ---- -git-get-tar-commit-id - Extract commit ID from an archive created using git-tar-tree. +git-get-tar-commit-id - Extract commit ID from an archive created using git-tar-tree SYNOPSIS diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index bf4b592f48..d55456ae93 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -3,7 +3,7 @@ git-grep(1) NAME ---- -git-grep - print lines matching a pattern +git-grep - Print lines matching a pattern SYNOPSIS @@ -24,13 +24,13 @@ OPTIONS <option>...:: Either an option to pass to `grep` or `git-ls-files`. - - The following are the specific `git-ls-files` options - that may be given: `-o`, `--cached`, `--deleted`, `--others`, - `--killed`, `--ignored`, `--modified`, `--exclude=*`, - `--exclude-from=*`, and `--exclude-per-directory=*`. - - All other options will be passed to `grep`. ++ +The following are the specific `git-ls-files` options +that may be given: `-o`, `--cached`, `--deleted`, `--others`, +`--killed`, `--ignored`, `--modified`, `--exclude=\*`, +`--exclude-from=\*`, and `--exclude-per-directory=\*`. ++ +All other options will be passed to `grep`. <pattern>:: The pattern to look for. The first non option is taken diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 0924931dc1..04e8d00436 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -3,7 +3,7 @@ git-hash-object(1) NAME ---- -git-hash-object - Computes object ID and optionally creates a blob from a file. +git-hash-object - Computes object ID and optionally creates a blob from a file SYNOPSIS diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index c7066d66f3..7e1f894a92 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -3,7 +3,7 @@ git-http-push(1) NAME ---- -git-http-push - Push missing objects using HTTP/DAV. +git-http-push - Push missing objects using HTTP/DAV SYNOPSIS diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index ea4d849aa3..aeb1115af9 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -14,7 +14,8 @@ SYNOPSIS OPTIONS ------- --template=<template_directory>:: - Provide the directory in from which templates will be used. + Provide the directory from which templates will be used. + The default template directory is `/usr/share/git-core/templates`. --shared:: Specify that the git repository is to be shared amongst several users. @@ -22,9 +23,17 @@ OPTIONS DESCRIPTION ----------- -This simply creates an empty git repository - basically a `.git` directory -and `.git/object/??/`, `.git/refs/heads` and `.git/refs/tags` directories, -and links `.git/HEAD` symbolically to `.git/refs/heads/master`. +This command creates an empty git repository - basically a `.git` directory +with subdirectories for `objects`, `refs/heads`, `refs/tags`, and +templated files. +An initial `HEAD` file that references the HEAD of the master branch +is also created. + +If `--template=<template_directory>` is specified, `<template_directory>` +is used as the source of the template files rather than the default. +The template files include some directory structure, some suggested +"exclude patterns", and copies of non-executing "hook" files. The +suggested patterns and hook files are all modifiable and extensible. If the `$GIT_DIR` environment variable is set then it specifies a path to use instead of `./.git` for the base of the repository. @@ -38,7 +47,6 @@ repository. When specifying `--shared` the config variable "core.sharedRepositor is set to 'true' so that directories under `$GIT_DIR` are made group writable (and g+sx, since the git group may be not the primary group of all users). - Running `git-init-db` in an existing repository is safe. It will not overwrite things that are already there. The primary reason for rerunning `git-init-db` is to pick up newly added templates. diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index 03156f218b..f52a9d7f68 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -3,7 +3,7 @@ git-lost-found(1) NAME ---- -git-lost-found - Recover lost refs that luckily have not yet been pruned. +git-lost-found - Recover lost refs that luckily have not yet been pruned SYNOPSIS -------- diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index fe5341295c..796d049be6 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -8,13 +8,15 @@ git-ls-files - Information about files in the index/working directory SYNOPSIS -------- -'git-ls-files' [-z] [-t] +[verse] +'git-ls-files' [-z] [-t] [-v] (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\* (-[c|d|o|i|s|u|k|m])\* [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] - [--exclude-per-directory=<file>] - [--full-name] [--] [<file>]\* + [--exclude-per-directory=<file>] + [--error-unmatch] + [--full-name] [--abbrev] [--] [<file>]\* DESCRIPTION ----------- @@ -50,6 +52,9 @@ OPTIONS If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents. +--no-empty-directory:: + Do not list empty directories. Has no effect without --directory. + -u|--unmerged:: Show unmerged files in the output (forces --stage) @@ -72,6 +77,10 @@ OPTIONS read additional exclude patterns that apply only to the directory and its subdirectories in <file>. +--error-unmatch:: + If any <file> does not appear in the index, treat this as an + error (return 1). + -t:: Identify the file status with the following tags (followed by a space) at the start of each line: @@ -82,12 +91,21 @@ OPTIONS K:: to be killed ?:: other +-v:: + Similar to `-t`, but use lowercase letters for files + that are marked as 'always matching index'. + --full-name:: When run from a subdirectory, the command usually outputs paths relative to the current directory. This option forces paths to be output relative to the project top directory. +--abbrev[=<n>]:: + Instead of showing the full 40-byte hexadecimal object + lines, show only handful hexdigits prefix. + Non default number of digits can be specified with --abbrev=<n>. + --:: Do not interpret any more arguments as options. diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index 66fe60f998..ae4c1a250e 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -3,7 +3,7 @@ git-ls-remote(1) NAME ---- -git-ls-remote - Look at references other repository has. +git-ls-remote - Look at references other repository has SYNOPSIS diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index b92a8b2db1..018c401953 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -3,12 +3,14 @@ git-ls-tree(1) NAME ---- -git-ls-tree - Lists the contents of a tree object. +git-ls-tree - Lists the contents of a tree object SYNOPSIS -------- -'git-ls-tree' [-d] [-r] [-t] [-z] [--name-only] [--name-status] <tree-ish> [paths...] +'git-ls-tree' [-d] [-r] [-t] [-z] + [--name-only] [--name-status] [--full-name] [--abbrev=[<n>]] + <tree-ish> [paths...] DESCRIPTION ----------- @@ -40,6 +42,11 @@ OPTIONS --name-status:: List only filenames (instead of the "long" output), one per line. +--abbrev[=<n>]:: + Instead of showing the full 40-byte hexadecimal object + lines, show only handful hexdigits prefix. + Non default number of digits can be specified with --abbrev=<n>. + paths:: When paths are given, show them (note that this isn't really raw pathnames, but rather a list of patterns to match). Otherwise diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 8890754740..ea0a06557f 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -3,7 +3,7 @@ git-mailinfo(1) NAME ---- -git-mailinfo - Extracts patch from a single e-mail message. +git-mailinfo - Extracts patch from a single e-mail message SYNOPSIS diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index e0703e9dfa..209e36bacb 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -3,7 +3,7 @@ git-mailsplit(1) NAME ---- -git-mailsplit - Totally braindamaged mbox splitter program. +git-mailsplit - Totally braindamaged mbox splitter program SYNOPSIS -------- diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index d242b39654..207c43a631 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -3,7 +3,7 @@ git-mv(1) NAME ---- -git-mv - Script used to move or rename a file, directory or symlink. +git-mv - Move or rename a file, directory or symlink SYNOPSIS diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index e37b0b8f97..68707083be 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -3,7 +3,7 @@ git-name-rev(1) NAME ---- -git-name-rev - Find symbolic names for given revs. +git-name-rev - Find symbolic names for given revs SYNOPSIS diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 4cb2e83faa..4991f88c92 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -3,7 +3,7 @@ git-pack-objects(1) NAME ---- -git-pack-objects - Create a packed archive of objects. +git-pack-objects - Create a packed archive of objects SYNOPSIS @@ -101,7 +101,7 @@ Documentation ------------- Documentation by Junio C Hamano -See-Also +See Also -------- gitlink:git-repack[1] gitlink:git-prune-packed[1] diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index 9fe86aef98..8fb0659438 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -3,12 +3,12 @@ git-pack-redundant(1) NAME ---- -git-pack-redundant - Program used to find redundant pack files. +git-pack-redundant - Program used to find redundant pack files SYNOPSIS -------- -'git-pack-redundant [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >' +'git-pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > DESCRIPTION ----------- @@ -46,7 +46,7 @@ Documentation -------------- Documentation by Lukas Sandström <lukass@etek.chalmers.se> -See-Also +See Also -------- gitlink:git-pack-objects[1] gitlink:git-repack[1] diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index c8bd197779..723b8ccbf6 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -3,7 +3,7 @@ git-patch-id(1) NAME ---- -git-patch-id - Generate a patch ID. +git-patch-id - Generate a patch ID SYNOPSIS -------- diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt index 915d3f8a06..a00060c507 100644 --- a/Documentation/git-peek-remote.txt +++ b/Documentation/git-peek-remote.txt @@ -3,7 +3,7 @@ git-peek-remote(1) NAME ---- -git-peek-remote - Lists the references in a remote repository. +git-peek-remote - Lists the references in a remote repository SYNOPSIS diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 37c53a91de..234882685d 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -40,7 +40,7 @@ Documentation -------------- Documentation by Ryan Anderson <ryan@michonline.com> -See-Also +See Also -------- gitlink:git-pack-objects[1] gitlink:git-repack[1] diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 20175f4b9a..51577fcbe6 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -3,7 +3,7 @@ git-pull(1) NAME ---- -git-pull - Pull and merge from another repository. +git-pull - Pull and merge from another repository SYNOPSIS diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 6f4a48a109..d5b5ca167c 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -3,7 +3,7 @@ git-push(1) NAME ---- -git-push - Update remote refs along with associated objects. +git-push - Update remote refs along with associated objects SYNOPSIS diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 6fbd6d9368..844cfda8d2 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,7 +8,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git-read-tree' (<tree-ish> | [[-m | --reset] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) +'git-read-tree' (<tree-ish> | [[-m [--aggressive]| --reset] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION @@ -50,6 +50,19 @@ OPTIONS trees that are not directly related to the current working tree status into a temporary index file. +--aggressive:: + Usually a three-way merge by `git-read-tree` resolves + the merge for really trivial cases and leaves other + cases unresolved in the index, so that Porcelains can + implement different merge policies. This flag makes the + command to resolve a few more cases internally: ++ +* when one side removes a path and the other side leaves the path + unmodified. The resolution is to remove that path. +* when both sides remove a path. The resolution is to remove that path. +* when both sides adds a path identically. The resolution + is to add that path. + <tree-ish#>:: The id of the tree object(s) to be read/merged. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 16c158f439..4a7e67a4d2 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -3,22 +3,74 @@ git-rebase(1) NAME ---- -git-rebase - Rebase local commits to new upstream head. +git-rebase - Rebase local commits to new upstream head SYNOPSIS -------- -'git-rebase' <upstream> [<head>] +'git-rebase' [--onto <newbase>] <upstream> [<branch>] DESCRIPTION ----------- -Rebases local commits to the new head of the upstream tree. +git-rebase applies to <upstream> (or optionally to <newbase>) commits +from <branch> that do not appear in <upstream>. When <branch> is not +specified it defaults to the current branch (HEAD). + +When git-rebase is complete, <branch> will be updated to point to the +newly created line of commit objects, so the previous line will not be +accessible unless there are other references to it already. + +Assume the following history exists and the current branch is "topic": + + A---B---C topic + / + D---E---F---G master + +From this point, the result of either of the following commands: + + git-rebase master + git-rebase master topic + +would be: + + A'--B'--C' topic + / + D---E---F---G master + +While, starting from the same point, the result of either of the following +commands: + + git-rebase --onto master~1 master + git-rebase --onto master~1 master topic + +would be: + + A'--B'--C' topic + / + D---E---F---G master + +In case of conflict, git-rebase will stop at the first problematic commit +and leave conflict markers in the tree. After resolving the conflict manually +and updating the index with the desired resolution, you can continue the +rebasing process with + + git am --resolved --3way + +Alternatively, you can undo the git-rebase with + + git reset --hard ORIG_HEAD + rm -r .dotest OPTIONS ------- +<newbase>:: + Starting point at which to create the new commits. If the + --onto option is not specified, the starting point is + <upstream>. + <upstream>:: Upstream branch to compare against. -<head>:: +<branch>:: Working branch; defaults to HEAD. Author diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt index 62405358fc..aca60120c8 100644 --- a/Documentation/git-relink.txt +++ b/Documentation/git-relink.txt @@ -3,7 +3,7 @@ git-relink(1) NAME ---- -git-relink - Hardlink common objects in local repositories. +git-relink - Hardlink common objects in local repositories SYNOPSIS -------- diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 6c0f792dad..d2f9a44382 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -63,7 +63,7 @@ Documentation -------------- Documentation by Ryan Anderson <ryan@michonline.com> -See-Also +See Also -------- gitlink:git-pack-objects[1] gitlink:git-prune-packed[1] diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index 33fcde452a..26759a8071 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -3,11 +3,12 @@ git-repo-config(1) NAME ---- -git-repo-config - Get and set options in .git/config. +git-repo-config - Get and set options in .git/config SYNOPSIS -------- +[verse] 'git-repo-config' [type] name [value [value_regex]] 'git-repo-config' [type] --replace-all name [value [value_regex]] 'git-repo-config' [type] --get name [value_regex] diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 2463ec91d5..478a5fd6b7 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -3,7 +3,7 @@ git-request-pull(1) NAME ---- -git-request-pull - Generates a summary of pending changes. +git-request-pull - Generates a summary of pending changes SYNOPSIS -------- diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index b4e737e660..b7b9798bf9 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -3,7 +3,7 @@ git-reset(1) NAME ---- -git-reset - Reset current HEAD to the specified state. +git-reset - Reset current HEAD to the specified state SYNOPSIS -------- diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 1c6146c764..8255ae1bce 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -16,9 +16,9 @@ SYNOPSIS [ \--no-merges ] [ \--remove-empty ] [ \--all ] - [ [ \--merge-order [ \--show-breaks ] ] | [ \--topo-order ] ] + [ \--topo-order ] [ \--parents ] - [ \--objects [ \--unpacked ] ] + [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] [ \--bisect ] <commit>... [ \-- <paths>... ] @@ -53,6 +53,14 @@ OPTIONS which I need to download if I have the commit object 'bar', but not 'foo'". +--objects-edge:: + Similar to `--objects`, but also print the IDs of + excluded commits refixed 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 + traffic. + --unpacked:: Only useful with `--objects`; print the object IDs that are not in packs. @@ -94,57 +102,10 @@ OPTIONS topological order (i.e. descendant commits are shown before their parents). ---merge-order:: - When specified the commit history is decomposed into a unique - sequence of minimal, non-linear epochs and maximal, linear epochs. - Non-linear epochs are then linearised by sorting them into merge - order, which is described below. -+ -Maximal, linear epochs correspond to periods of sequential development. -Minimal, non-linear epochs correspond to periods of divergent development -followed by a converging merge. The theory of epochs is described in more -detail at -link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/]. -+ -The merge order for a non-linear epoch is defined as a linearisation for which -the following invariants are true: -+ - 1. if a commit P is reachable from commit N, commit P sorts after commit N - in the linearised list. - 2. if Pi and Pj are any two parents of a merge M (with i < j), then any - commit N, such that N is reachable from Pj but not reachable from Pi, - sorts before all commits reachable from Pi. -+ -Invariant 1 states that later commits appear before earlier commits they are -derived from. -+ -Invariant 2 states that commits unique to "later" parents in a merge, appear -before all commits from "earlier" parents of a merge. - ---show-breaks:: - Each item of the list is output with a 2-character prefix consisting - of one of: (|), (^), (=) followed by a space. -+ -Commits marked with (=) represent the boundaries of minimal, non-linear epochs -and correspond either to the start of a period of divergent development or to -the end of such a period. -+ -Commits marked with (|) are direct parents of commits immediately preceding -the marked commit in the list. -+ -Commits marked with (^) are not parents of the immediately preceding commit. -These "breaks" represent necessary discontinuities implied by trying to -represent an arbitrary DAG in a linear form. -+ -`--show-breaks` is only valid if `--merge-order` is also specified. - - Author ------ Written by Linus Torvalds <torvalds@osdl.org> -Original *--merge-order* logic by Jon Seymour <jon.seymour@gmail.com> - Documentation -------------- Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 1662e06561..8b95df0c6e 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -3,7 +3,7 @@ git-rev-parse(1) NAME ---- -git-rev-parse - Pick out and massage parameters. +git-rev-parse - Pick out and massage parameters SYNOPSIS @@ -80,7 +80,7 @@ OPTIONS --git-dir:: Show `$GIT_DIR` if defined else show the path to the .git directory. ---short, short=number:: +--short, --short=number:: Instead of outputting the full SHA1 values of object names try to abbriviate them to a shorter unique name. When no length is specified 7 is used. The minimum length is 4. diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index e27c6808b3..71f7815d65 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -3,7 +3,7 @@ git-revert(1) NAME ---- -git-revert - Revert an existing commit. +git-revert - Revert an existing commit SYNOPSIS -------- diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt new file mode 100644 index 0000000000..c9c3088424 --- /dev/null +++ b/Documentation/git-rm.txt @@ -0,0 +1,92 @@ +git-rm(1) +========= + +NAME +---- +git-rm - Remove files from the working tree and from the index + +SYNOPSIS +-------- +'git-rm' [-f] [-n] [-v] [--] <file>... + +DESCRIPTION +----------- +A convenience wrapper for git-update-index --remove. For those coming +from cvs, git-rm provides an operation similar to "cvs rm" or "cvs +remove". + + +OPTIONS +------- +<file>...:: + Files to remove from the index and optionally, from the + working tree as well. + +-f:: + Remove files from the working tree as well as from the index. + +-n:: + Don't actually remove the file(s), just show if they exist in + the index. + +-v:: + Be verbose. + +--:: + This option can be used to separate command-line options from + the list of files, (useful when filenames might be mistaken + for command-line options). + + +DISCUSSION +---------- + +The list of <file> given to the command is fed to `git-ls-files` +command to list files that are registered in the index and +are not ignored/excluded by `$GIT_DIR/info/exclude` file or +`.gitignore` file in each directory. This means two things: + +. You can put the name of a directory on the command line, and the + command will remove all files in it and its subdirectories (the + directories themselves are never removed from the working tree); + +. Giving the name of a file that is not in the index does not + remove that file. + + +EXAMPLES +-------- +git-rm Documentation/\\*.txt:: + + Removes all `\*.txt` files from the index that are under the + `Documentation` directory and any of its subdirectories. The + files are not removed from the working tree. ++ +Note that the asterisk `\*` is quoted from the shell in this +example; this lets the command include the files from +subdirectories of `Documentation/` directory. + +git-rm -f git-*.sh:: + + Remove all git-*.sh scripts that are in the index. The files + are removed from the index, and (because of the -f option), + from the working tree as well. Because this example lets the + shell expand the asterisk (i.e. you are listing the files + explicitly), it does not remove `subdir/git-foo.sh`. + +See Also +-------- +gitlink:git-add[1] + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 00537d8907..8c58685e28 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -24,6 +24,9 @@ OPTIONS ------- The options available are: +--cc:: + Specify a starting "Cc:" value for each email. + --chain-reply-to, --no-chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with "--no-chain-reply-to", all emails after @@ -48,6 +51,9 @@ The options available are: Only necessary if --compose is also set. If --compose is not set, this will be prompted for. +--no-signed-off-by-cc:: + Do not add emails foudn in Signed-off-by: lines to the cc list. + --quiet:: Make git-send-email less verbose. One line per email should be all that is output. @@ -61,6 +67,10 @@ The options available are: Only necessary if --compose is also set. If --compose is not set, this will be prompted for. +--suppress-from:: + Do not add the From: address to the cc: list, if it shows up in a From: + line. + --to:: Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 577f06a214..08e0705303 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -3,7 +3,7 @@ git-send-pack(1) NAME ---- -git-send-pack - Push missing objects packed. +git-send-pack - Push missing objects packed SYNOPSIS diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 6ef59acf50..6742c9bfcf 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -3,7 +3,7 @@ git-sh-setup(1) NAME ---- -git-sh-setup - Common git shell script setup code. +git-sh-setup - Common git shell script setup code SYNOPSIS -------- diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 3f4d804cca..cc4266d83b 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -8,7 +8,7 @@ git-shell - Restricted login shell for GIT over SSH only SYNOPSIS -------- -'git-shell -c <command> <argument>' +'git-shell' -c <command> <argument> DESCRIPTION ----------- diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 65ca77fbf6..54fb922ba9 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -3,12 +3,12 @@ git-shortlog(1) NAME ---- -git-shortlog - Summarize 'git log' output. +git-shortlog - Summarize 'git log' output SYNOPSIS -------- -'git-log --pretty=short | git shortlog' +git-log --pretty=short | 'git-shortlog' DESCRIPTION ----------- diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 7b1a9c9875..f115b45ef6 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -3,14 +3,14 @@ git-show-branch(1) NAME ---- -git-show-branch - Show branches and their commits. +git-show-branch - Show branches and their commits SYNOPSIS -------- [verse] -git-show-branch [--all] [--heads] [--tags] [--topo-order] [--current] - [--more=<n> | --list | --independent | --merge-base] - [--no-name | --sha1-name] [<rev> | <glob>]... +'git-show-branch' [--all] [--heads] [--tags] [--topo-order] [--current] + [--more=<n> | --list | --independent | --merge-base] + [--no-name | --sha1-name] [<rev> | <glob>]... DESCRIPTION ----------- @@ -141,7 +141,7 @@ it, having the following in the configuration file may help: ------------ -With this,`git show-branch` without extra parameters would show +With this, `git show-branch` without extra parameters would show only the primary branches. In addition, if you happen to be on your topic branch, it is shown as well. diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 9c359a448e..2b4df3f96f 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -3,7 +3,7 @@ git-show(1) NAME ---- -git-show - Show one commit with difference it introduces. +git-show - Show one commit with difference it introduces SYNOPSIS diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 753fc0866d..e446f4812e 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -3,7 +3,7 @@ git-status(1) NAME ---- -git-status - Show working tree status. +git-status - Show working tree status SYNOPSIS diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 528a1b6ce3..3a03dd0410 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -3,7 +3,7 @@ git-stripspace(1) NAME ---- -git-stripspace - Filter out empty lines. +git-stripspace - Filter out empty lines SYNOPSIS diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt index 63e28b89d5..b1b87c2fcd 100644 --- a/Documentation/git-svnimport.txt +++ b/Documentation/git-svnimport.txt @@ -9,11 +9,13 @@ git-svnimport - Import a SVN repository into git SYNOPSIS -------- +[verse] 'git-svnimport' [ -o <branch-for-HEAD> ] [ -h ] [ -v ] [ -d | -D ] - [ -C <GIT_repository> ] [ -i ] [ -u ] [-l limit_rev] - [ -b branch_subdir ] [ -T trunk_subdir ] [ -t tag_subdir ] - [ -s start_chg ] [ -m ] [ -M regex ] - <SVN_repository_URL> [ <path> ] + [ -C <GIT_repository> ] [ -i ] [ -u ] [-l limit_rev] + [ -b branch_subdir ] [ -T trunk_subdir ] [ -t tag_subdir ] + [ -s start_chg ] [ -m ] [ -r ] [ -M regex ] + [ -I <ignorefile_name> ] [ -A <author_file> ] + <SVN_repository_URL> [ <path> ] DESCRIPTION @@ -61,6 +63,34 @@ When importing incrementally, you might need to edit the .git/svn2git file. the git repository. Use this option if you want to import into a different branch. +-r:: + Prepend 'rX: ' to commit messages, where X is the imported + subversion revision. + +-I <ignorefile_name>:: + Import the svn:ignore directory property to files with this + name in each directory. (The Subversion and GIT ignore + syntaxes are similar enough that using the Subversion patterns + directly with "-I .gitignore" will almost always just work.) + +-A <author_file>:: + Read a file with lines on the form ++ +------ + username = User's Full Name <email@addr.es> + +------ ++ +and use "User's Full Name <email@addr.es>" as the GIT +author and committer for Subversion commits made by +"username". If encountering a commit made by a user not in the +list, abort. ++ +For convenience, this data is saved to $GIT_DIR/svn-authors +each time the -A option is provided, and read from that same +file each time git-svnimport is run with an existing GIT +repository without -A. + -m:: Attempt to detect merges based on the commit message. This option will enable default regexes that try to capture the name source diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index e8892bb0b0..45476c2e41 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -3,16 +3,18 @@ git-tag(1) NAME ---- -git-tag - Create a tag object signed with GPG +git-tag - Create a tag object signed with GPG SYNOPSIS -------- +[verse] 'git-tag' [-a | -s | -u <key-id>] [-f | -d] [-m <msg>] <name> [<head>] +'git-tag' -l [<pattern>] DESCRIPTION ----------- -Adds a 'tag' reference in .git/refs/tags/ +Adds a 'tag' reference in `.git/refs/tags/` Unless `-f` is given, the tag must not yet exist in `.git/refs/tags/` directory. @@ -32,6 +34,9 @@ GnuPG key for signing. `-d <tag>` deletes the tag. +`-l <pattern>` lists tags that match the given pattern (or all +if no pattern is given). + OPTIONS ------- -a:: @@ -49,6 +54,9 @@ OPTIONS -d:: Delete an existing tag with the given name +-l <pattern>:: + List tags that match the given pattern (or all if no pattern is given). + -m <msg>:: Use the given tag message (instead of prompting) diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt new file mode 100644 index 0000000000..00e57a69ae --- /dev/null +++ b/Documentation/git-tools.txt @@ -0,0 +1,97 @@ +A short git tools survey +======================== + + +Introduction +------------ + +Apart from git contrib/ area there are some others third-party tools +you may want to look. + +This document presents a brief summary of each tool and the corresponding +link. + + +Alternative/Augmentative Procelains +----------------------------------- + + - *Cogito* (http://www.kernel.org/pub/software/scm/cogito/) + + Cogito is a version control system layered on top of the git tree history + storage system. It aims at seamless user interface and ease of use, + providing generally smoother user experience than the "raw" Core GIT + itself and indeed many other version control systems. + + + - *pg* (http://www.spearce.org/category/projects/scm/pg/) + + pg is a shell script wrapper around GIT to help the user manage a set of + patches to files. pg is somewhat like quilt or StGIT, but it does have a + slightly different feature set. + + + - *StGit* (http://www.procode.org/stgit/) + + Stacked GIT provides a quilt-like patch management functionality in the + GIT environment. You can easily manage your patches in the scope of GIT + until they get merged upstream. + + +History Viewers +--------------- + + - *gitk* (shipped with git-core) + + gitk is a simple TK GUI for browsing history of GIT repositories easily. + + + - *gitview* (contrib/) + + gitview is a GTK based repository browser for git + + + - *gitweb* (ftp://ftp.kernel.org/pub/software/scm/gitweb/) + + GITweb provides full-fledged web interface for GIT repositories. + + + - *qgit* (http://digilander.libero.it/mcostalba/) + + QGit is a git/StGIT GUI viewer built on Qt/C++. QGit could be used + to browse history and directory tree, view annotated files, commit + changes cherry picking single files or applying patches. + Currently it is the fastest and most feature rich among the git + viewers and commit tools. + + + +Foreign SCM interface +--------------------- + + - *git-svn* (contrib/) + + git-svn is a simple conduit for changesets between a single Subversion + branch and git. + + + - *quilt2git / git2quilt* (http://home-tj.org/wiki/index.php/Misc) + + These utilities convert patch series in a quilt repository and commit + series in git back and forth. + + +Others +------ + + - *(h)gct* (http://www.cyd.liu.se/users/~freku045/gct/) + + Commit Tool or (h)gct is a GUI enabled commit tool for git and + Mercurial (hg). It allows the user to view diffs, select which files + to committed (or ignored / reverted) write commit messages and + perform the commit itself. + + - *git.el* (contrib/) + + This is an Emacs interface for git. The user interface is modeled on + pcl-cvs. It has been developed on Emacs 21 and will probably need some + tweaking to work on XEmacs. diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index 31ea34d229..18280628a1 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -3,7 +3,7 @@ git-unpack-objects(1) NAME ---- -git-unpack-objects - Unpack objects from a packed archive. +git-unpack-objects - Unpack objects from a packed archive SYNOPSIS diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index c74311dabd..0a1b0ad56d 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -8,11 +8,14 @@ git-update-index - Modifies the index or directory cache SYNOPSIS -------- +[verse] 'git-update-index' [--add] [--remove | --force-remove] [--replace] [--refresh [-q] [--unmerged] [--ignore-missing]] [--cacheinfo <mode> <object> <file>]\* [--chmod=(+|-)x] + [--assume-unchanged | --no-assume-unchanged] + [--really-refresh] [--info-only] [--index-info] [-z] [--stdin] [--verbose] @@ -65,6 +68,18 @@ OPTIONS --chmod=(+|-)x:: Set the execute permissions on the updated files. +--assume-unchanged, --no-assume-unchanged:: + When these flags are specified, the object name recorded + for the paths are not updated. Instead, these options + sets and unsets the "assume unchanged" bit for the + paths. When the "assume unchanged" bit is on, git stops + checking the working tree files for possible + modifications, so you need to manually unset the bit to + tell git when you change the working tree file. This is + sometimes helpful when working with a big project on a + filesystem that has very slow lstat(2) system call + (e.g. cifs). + --info-only:: Do not create objects in the object database for all <file> arguments that follow this flag; just insert @@ -193,6 +208,37 @@ $ git ls-files -s ------------ +Using "assume unchanged" bit +---------------------------- + +Many operations in git depend on your filesystem to have an +efficient `lstat(2)` implementation, so that `st_mtime` +information for working tree files can be cheaply checked to see +if the file contents have changed from the version recorded in +the index file. Unfortunately, some filesystems have +inefficient `lstat(2)`. If your filesystem is one of them, you +can set "assume unchanged" bit to paths you have not changed to +cause git not to do this check. Note that setting this bit on a +path does not mean git will check the contents of the file to +see if it has changed -- it makes git to omit any checking and +assume it has *not* changed. When you make changes to working +tree files, you have to explicitly tell git about it by dropping +"assume unchanged" bit, either before or after you modify them. + +In order to set "assume unchanged" bit, use `--assume-unchanged` +option. To unset, use `--no-assume-unchanged`. + +The command looks at `core.ignorestat` configuration variable. When +this is true, paths updated with `git-update-index paths...` and +paths updated with other git commands that update both index and +working tree (e.g. `git-apply --index`, `git-checkout-index -u`, +and `git-read-tree -u`) are automatically marked as "assume +unchanged". Note that "assume unchanged" bit is *not* set if +`git-update-index --refresh` finds the working tree file matches +the index (use `git-update-index --really-refresh` if you want +to mark them as "assume unchanged"). + + Examples -------- To update and refresh only the files already checked out: @@ -201,6 +247,35 @@ To update and refresh only the files already checked out: $ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh ---------------- +On an inefficient filesystem with `core.ignorestat` set: + +------------ +$ git update-index --really-refresh <1> +$ git update-index --no-assume-unchanged foo.c <2> +$ git diff --name-only <3> +$ edit foo.c +$ git diff --name-only <4> +M foo.c +$ git update-index foo.c <5> +$ git diff --name-only <6> +$ edit foo.c +$ git diff --name-only <7> +$ git update-index --no-assume-unchanged foo.c <8> +$ git diff --name-only <9> +M foo.c + +<1> forces lstat(2) to set "assume unchanged" bits for paths + that match index. +<2> mark the path to be edited. +<3> this does lstat(2) and finds index matches the path. +<4> this does lstat(2) and finds index does not match the path. +<5> registering the new version to index sets "assume unchanged" bit. +<6> and it is assumed unchanged. +<7> even after you edit it. +<8> you can tell about the change after the fact. +<9> now it checks with lstat(2) and finds it has been changed. +------------ + Configuration ------------- @@ -213,6 +288,9 @@ in the index and the file mode on the filesystem if they differ only on executable bit. On such an unfortunate filesystem, you may need to use `git-update-index --chmod=`. +The command looks at `core.ignorestat` configuration variable. See +'Using "assume unchanged" bit' section above. + See Also -------- diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 69715aa061..475237f19e 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -7,7 +7,7 @@ git-update-ref - update the object name stored in a ref safely SYNOPSIS -------- -`git-update-ref` <ref> <newvalue> [<oldvalue>] +'git-update-ref' <ref> <newvalue> [<oldvalue>] DESCRIPTION ----------- diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 3d8f8ef667..4795e98754 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -3,7 +3,7 @@ git-upload-pack(1) NAME ---- -git-upload-pack - Send missing objects packed. +git-upload-pack - Send missing objects packed SYNOPSIS diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index c22d34f5fb..90cb157be5 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -8,7 +8,7 @@ git-var - Print the git users identity SYNOPSIS -------- -git-var [ -l | <variable> ] +'git-var' [ -l | <variable> ] DESCRIPTION ----------- diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index d032280e7c..4962d6975f 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -3,7 +3,7 @@ git-verify-pack(1) NAME ---- -git-verify-pack - Validate packed git archive files. +git-verify-pack - Validate packed git archive files SYNOPSIS diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index b8a73c47af..0f9bdb58dc 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -3,7 +3,7 @@ git-verify-tag(1) NAME ---- -git-verify-tag - Check the GPG signature of tag. +git-verify-tag - Check the GPG signature of tag SYNOPSIS -------- diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 6c150b0264..641cb7ea97 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -3,7 +3,7 @@ git-whatchanged(1) NAME ---- -git-whatchanged - Show logs with difference each commit introduces. +git-whatchanged - Show logs with difference each commit introduces SYNOPSIS @@ -47,9 +47,9 @@ OPTIONS By default, differences for merge commits are not shown. With this flag, show differences to that commit from all of its parents. - - However, it is not very useful in general, although it - *is* useful on a file-by-file basis. ++ +However, it is not very useful in general, although it +*is* useful on a file-by-file basis. Examples -------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 2d0ca9d8ed..fe34f50dc5 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -20,15 +20,16 @@ brings your stuff to the plumbing). OPTIONS ------- --version:: - prints the git suite version that the 'git' program came from. + Prints the git suite version that the 'git' program came from. --help:: - prints the synopsis and a list of available commands. - If a git command is named this option will bring up the - man-page for that command. + Prints the synopsis and a list of the most commonly used + commands. If a git command is named this option will bring up + the man-page for that command. If the option '--all' or '-a' is + given then all available commands are printed. --exec-path:: - path to wherever your core git programs are installed. + Path to wherever your core git programs are installed. This can also be controlled by setting the GIT_EXEC_PATH environment variable. If no path is given 'git' will print the current setting and then exit. @@ -328,6 +329,9 @@ gitlink:git-revert[1]:: gitlink:git-shortlog[1]:: Summarizes 'git log' output. +gitlink:git-show[1]:: + Show one commit log and its diff. + gitlink:git-show-branch[1]:: Show branches and their commits. @@ -517,16 +521,14 @@ HEAD:: a valid head 'name' (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). -<snap>:: - a valid snapshot 'name' - (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`). - File/Directory Structure ------------------------ Please see link:repository-layout.html[repository layout] document. +Read link:hooks.html[hooks] for more details about each hook. + Higher level SCMs may provide and manage additional information in the `$GIT_DIR`. diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index 4ad1920ec1..3824a9517c 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -97,16 +97,31 @@ send out a commit notification e-mail. update ------ -This hook is invoked by `git-receive-pack`, which is invoked -when a `git push` is done against the repository. It takes -three parameters, name of the ref being updated, old object name -stored in the ref, and the new objectname to be stored in the -ref. Exiting with non-zero status from this hook prevents -`git-receive-pack` from updating the ref. - -This can be used to prevent 'forced' update on certain refs by +This hook is invoked by `git-receive-pack` on the remote repository, +which is happens when a `git push` is done on a local repository. +Just before updating the ref on the remote repository, the update hook +is invoked. It's exit status determins the success or failure of +the ref update. + +The hook executes once for each ref to be updated, and takes +three parameters: + - the name of the ref being updated, + - the old object name stored in the ref, + - and the new objectname to be stored in the ref. + +A zero exit from the update hook allows the ref to be updated. +Exiting with a non-zero status prevents `git-receive-pack` +from updating the ref. + +This hook can be used to prevent 'forced' update on certain refs by making sure that the object name is a commit object that is a descendant of the commit object named by the old object name. +That is, to enforce a "fast forward only" policy. + +It could also be used to log the old..new status. However, it +does not know the entire set of branches, so it would end up +firing one e-mail per ref when used naively, though. + Another use suggested on the mailing list is to use this hook to implement access control which is finer grained than the one based on filesystem group. @@ -115,20 +130,30 @@ The standard output of this hook is sent to /dev/null; if you want to report something to the git-send-pack on the other end, you can redirect your output to your stderr. + post-update ----------- -This hook is invoked by `git-receive-pack`, which is invoked -when a `git push` is done against the repository. It takes -variable number of parameters; each of which is the name of ref -that was actually updated. +This hook is invoked by `git-receive-pack` on the remote repository, +which is happens when a `git push` is done on a local repository. +It executes on the remote repository once after all the refs have +been updated. + +It takes a variable number of parameters, each of which is the +name of ref that was actually updated. This hook is meant primarily for notification, and cannot affect the outcome of `git-receive-pack`. +The post-update hook can tell what are the heads that were pushed, +but it does not know what their original and updated values are, +so it is a poor place to do log old..new. + The default post-update hook, when enabled, runs `git-update-server-info` to keep the information used by dumb -transport up-to-date. +transports (eg, http) up-to-date. If you are publishing +a git repository that is accessible via http, you should +probably enable this hook. The standard output of this hook is sent to /dev/null; if you want to report something to the git-send-pack on the other end, diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index 1f19bf86dd..98fbe7db52 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -89,6 +89,8 @@ hooks:: commands. A handful of sample hooks are installed when `git init-db` is run, but all of them are disabled by default. To enable, they need to be made executable. + Read link:hooks.html[hooks] for more details about + each hook. index:: The current index file for the repository. It is diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 66680d76bd..fa79b016c7 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -309,7 +309,7 @@ git diff HEAD^^ HEAD^ ------------------------------------- shows the difference between that previous state and the state two -commits ago. Also, HEAD~5 can be used as a shorthand for HEAD^^^^^, +commits ago. Also, HEAD~5 can be used as a shorthand for HEAD{caret}{caret}{caret}{caret}{caret}, and more generally HEAD~n can refer to the nth previous commit. Commits representing merges have more than one parent, and you can specify which parent to follow in that case; see |