diff options
Diffstat (limited to 'Documentation')
40 files changed, 916 insertions, 366 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index be4f3e1..a1ff2c2 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -9,6 +9,7 @@ ARTICLES += diffcore ARTICLES += howto-index ARTICLES += repository-layout ARTICLES += hooks +ARTICLES += everyday # with their own formatting rules. SP_ARTICLES = glossary howto/revert-branch-rebase diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 57436f0..dc9387b 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -187,7 +187,8 @@ you would use git-rev-list and git-diff-tree like this: We have already talked about the "\--stdin" form of git-diff-tree command that reads the list of commits and compares each commit -with its parents. The git-whatchanged command internally runs +with its parents (otherwise you should go back and read the tutorial). +The git-whatchanged command internally runs the equivalent of the above command, and can be used like this: $ git-whatchanged -p -S'if (frotz) { diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt new file mode 100644 index 0000000..5775cd2 --- /dev/null +++ b/Documentation/everyday.txt @@ -0,0 +1,138 @@ +Everyday GIT With 20 Commands Or So +=================================== + +GIT suite has over 100 commands, and the manual page for each of +them discusses what the command does and how it is used in +detail, but until you know what command should be used in order +to achieve what you want to do, you cannot tell which manual +page to look at, and if you know that already you do not need +the manual. + +Does that mean you need to know all of them before you can use +git? Not at all. Depending on the role you play, the set of +commands you need to know is slightly different, but in any case +what you need to learn is far smaller than the full set of +commands to carry out your day-to-day work. This document is to +serve as a cheat-sheet and a set of pointers for people playing +various roles. + +<<Basic Repository>> commands are needed by people who has a +repository --- that is everybody, because every working tree of +git is a repository. + +In addition, <<Individual Developer (Standalone)>> commands are +essential for anybody who makes a commit, even for somebody who +works alone. + +If you work with other people, you will need commands listed in +<<Individual Developer (Participant)>> section as well. + +People who play <<Integrator>> role need to learn some more +commands in addition to the above. + +<<Repository Administration>> commands are for system +administrators who are responsible to care and feed git +repositories to support developers. + + +Basic Repository[[Basic Repository]] +------------------------------------ + +Everybody uses these commands to feed and care git repositories. + + * gitlink:git-init-db[1] or gitlink:git-clone[1] to create a + new repository. + + * gitlink:git-fsck-objects[1] to validate the repository. + + * gitlink:git-prune[1] to garbage collect crufts in the + repository. + + * gitlink:git-repack[1] to pack loose objects for efficiency. + +Individual Developer (Standalone)[[Individual Developer (Standalone)]] +---------------------------------------------------------------------- + +A standalone individual developer does not exchange patches with +other poeple, and works alone in a single repository, using the +following commands. + + * gitlink:git-show-branch[1] to see where you are. + + * gitlink:git-diff[1] and gitlink:git-status[1] to see what + you are in the middle of doing. + + * gitlink:git-log[1] to see what happened. + + * gitlink:git-whatchanged[1] to find out where things have + come from. + + * gitlink:git-checkout[1] and gitlink:git-branch[1] to switch + branches. + + * gitlink:git-update-index[1] to manage the index file. + + * gitlink:git-commit[1] to advance the current branch. + + * gitlink:git-reset[1] and gitlink:git-checkout[1] (with + pathname parameters) to undo changes. + + * gitlink:git-pull[1] with "." as the remote to merge between + local branches. + + * gitlink:git-rebase[1] to maintain topic branches. + + +Individual Developer (Participant)[[Individual Developer (Participant)]] +------------------------------------------------------------------------ + +A developer working as a participant in a group project needs to +learn how to communicate with others, and uses these commands in +addition to the ones needed by a standalone developer. + + * gitlink:git-pull[1] from "origin" to keep up-to-date with + the upstream. + + * gitlink:git-push[1] to shared repository if you adopt CVS + style shared repository workflow. + + * gitlink:git-format-patch[1] to prepare e-mail submission, if + you adopt Linux kernel-style public forum workflow. + + +Integrator[[Integrator]] +------------------------ + +A fairly central person acting as the integrator in a group +project receives changes made by others, reviews and integrates +them and publishes the result for others to use, using these +commands in addition to the ones needed by participants. + + * gitlink:git-am[1] to apply patches e-mailed in from your + contributors. + + * gitlink:git-pull[1] to merge from your trusted lieutenants. + + * gitlink:git-format-patch[1] to prepare and send suggested + alternative to contributors. + + * gitlink:git-revert[1] to undo botched commits. + + * gitlink:git-push[1] to publish the bleeding edge. + + +Repository Administration[[Repository Administration]] +------------------------------------------------------ + +A repository administrator uses the following tools to set up +and maintain access to the repository by developers. + + * gitlink:git-daemon[1] to allow anonymous download from + repository. + + * gitlink:git-shell[1] can be used as a 'restricted login shell' + for shared central repository users. + + * link:howto/update-hook-example.txt[update hook howto] has a + good example of managing a shared central repository. + diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 1ceed11..6645e82 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -28,7 +28,7 @@ OPTIONS area to store extracted patches. --utf8, --keep:: - Pass `--utf8` and `--keep` flags to `git-mailinfo` (see + Pass `-u` and `-k` flags to `git-mailinfo` (see gitlink:git-mailinfo[1]). --binary:: diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 8a39970..ac4b496 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -8,16 +8,21 @@ git-bisect - Find the change that introduced a bug SYNOPSIS -------- - 'git bisect' start - 'git bisect' bad <rev> - 'git bisect' good <rev> - 'git bisect' reset [<branch>] - 'git bisect' visualize - 'git bisect' replay <logfile> - 'git bisect' log +'git bisect' <subcommand> <options> DESCRIPTION ----------- +The command takes various subcommands, and different options +depending on the subcommand: + + git bisect start [<paths>...] + git bisect bad <rev> + git bisect good <rev> + git bisect reset [<branch>] + git bisect visualize + git bisect replay <logfile> + git bisect log + This command uses 'git-rev-list --bisect' option to help drive the binary search process to find which change introduced a bug, given an old "good" commit object name and a later "bad" commit @@ -26,10 +31,10 @@ object name. The way you use it is: ------------------------------------------------ -git bisect start -git bisect bad # Current version is bad -git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version - # tested that was good +$ git bisect start +$ git bisect bad # Current version is bad +$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version + # tested that was good ------------------------------------------------ When you give at least one bad and one good versions, it will @@ -43,7 +48,7 @@ and check out the state in the middle. Now, compile that kernel, and boot it. Now, let's say that this booted kernel works fine, then just do ------------------------------------------------ -git bisect good # this one is good +$ git bisect good # this one is good ------------------------------------------------ which will now say @@ -62,7 +67,7 @@ kernel rev in "refs/bisect/bad". Oh, and then after you want to reset to the original head, do a ------------------------------------------------ -git bisect reset +$ git bisect reset ------------------------------------------------ to get back to the master branch, instead of being in one of the bisection @@ -72,7 +77,9 @@ not using some old bisection branch). During the bisection process, you can say - git bisect visualize +------------ +$ git bisect visualize +------------ to see the currently remaining suspects in `gitk`. @@ -80,11 +87,40 @@ The good/bad input is logged, and `git bisect log` shows what you have done so far. You can truncate its output somewhere and save it in a file, and run - git bisect replay that-file +------------ +$ git bisect replay that-file +------------ if you find later you made a mistake telling good/bad about a revision. +If in a middle of bisect session, you know what the bisect +suggested to try next is not a good one to test (e.g. the change +the commit introduces is known not to work in your environment +and you know it does not have anything to do with the bug you +are chasing), you may want to find a near-by commit and try that +instead. It goes something like this: + +------------ +$ git bisect good/bad # previous round was good/bad. +Bisecting: 337 revisions left to test after this +$ git bisect visualize # oops, that is uninteresting. +$ git reset --hard HEAD~3 # try 3 revs before what + # was suggested +------------ + +Then compile and test the one you chose to try. After that, +tell bisect what the result was as usual. + +You can further cut down the number of trials if you know what +part of the tree is involved in the problem you are tracking +down, by giving paths parameters when you say `bisect start`, +like this: + +------------ +$ git bisect start arch/i386 include/asm-i386 +------------ + Author ------ diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 5bff486..9f32c65 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -9,7 +9,7 @@ git-checkout-index - Copy files from the index to the working directory SYNOPSIS -------- 'git-checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] - [--] <file>... + [--stage=<number>] [--] <file>... DESCRIPTION ----------- @@ -40,58 +40,80 @@ OPTIONS When creating files, prepend <string> (usually a directory including a trailing /) +--stage=<number>:: + Instead of checking out unmerged entries, copy out the + files from named stage. <number> must be between 1 and 3. + --:: Do not interpret any more arguments as options. The order of the flags used to matter, but not anymore. -Just doing "git-checkout-index" does nothing. You probably meant -"git-checkout-index -a". And if you want to force it, you want -"git-checkout-index -f -a". +Just doing `git-checkout-index` does nothing. You probably meant +`git-checkout-index -a`. And if you want to force it, you want +`git-checkout-index -f -a`. Intuitiveness is not the goal here. Repeatability is. The reason for -the "no arguments means no work" thing is that from scripts you are -supposed to be able to do things like: +the "no arguments means no work" behavior is that from scripts you are +supposed to be able to do: - find . -name '*.h' -print0 | xargs -0 git-checkout-index -f -- +---------------- +$ 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. -To update and refresh only the files already checked out: - - git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh - -Oh, and the "--" is just a good idea when you know the rest will be -filenames. Just so that you wouldn't have a filename of "-a" causing -problems (not possible in the above example, but get used to it in -scripting!). - -The prefix ability basically makes it trivial to use -git-checkout-index as an "export as tree" function. Just read the -desired tree into the index, and do a +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. - git-checkout-index --prefix=git-export-dir/ -a -and git-checkout-index will "export" the index into the specified +EXAMPLES +-------- +To update and refresh only the files already checked out:: ++ +---------------- +$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh +---------------- + +Using `git-checkout-index` to "export an entire tree":: + The prefix ability basically makes it trivial to use + `git-checkout-index` as an "export as tree" function. + Just read the desired tree into the index, and do: ++ +---------------- +$ git-checkout-index --prefix=git-export-dir/ -a +---------------- ++ +`git-checkout-index` will "export" the index into the specified directory. ++ +The final "/" is important. The exported name is literally just +prefixed with the specified string. Contrast this with the +following example. -NOTE The final "/" is important. The exported name is literally just -prefixed with the specified string, so you can also do something like - - git-checkout-index --prefix=.merged- Makefile +Export files with a prefix:: ++ +---------------- +$ git-checkout-index --prefix=.merged- Makefile +---------------- ++ +This will check out the currently cached copy of `Makefile` +into the file `.merged-Makefile`. -to check out the currently cached copy of `Makefile` into the file -`.merged-Makefile` Author ------ Written by Linus Torvalds <torvalds@osdl.org> + Documentation -------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +Documentation by David Greaves, +Junio C Hamano and the git-list <git@vger.kernel.org>. + GIT --- diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 26e0467..4f323fa 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -7,7 +7,7 @@ git-cherry-pick - Apply the change introduced by an existing commit. SYNOPSIS -------- -'git-cherry-pick' [-n] [-r] <commit> +'git-cherry-pick' [--edit] [-n] [-r] <commit> DESCRIPTION ----------- @@ -20,15 +20,19 @@ OPTIONS <commit>:: Commit to cherry-pick. --r:: +-e|--edit:: + With this option, `git-cherry-pick` will let you edit the commit + message prior committing. + +-r|--replay:: Usually the command appends which commit was cherry-picked after the original commit message when making a commit. This option, '--replay', causes it to use the original commit message intact. This is useful when you are reordering the patches in your private tree - before publishing, and is used by 'git rebase'. + before publishing. --n:: +-n|--no-commit:: Usually the command automatically creates a commit with a commit log message stating which commit was cherry-picked. This flag applies the change necessary diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 1edc278..b92cf48 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -7,7 +7,7 @@ git-commit - Record your changes SYNOPSIS -------- -'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>] [-e] <file>... +'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>] [-e] [--] <file>... DESCRIPTION ----------- @@ -22,7 +22,7 @@ information. OPTIONS ------- --a:: +-a|--all:: Update all paths in the index file. -c or -C <commit>:: @@ -39,23 +39,29 @@ OPTIONS -m <msg>:: Use the given <msg> as the commit message. --s:: +-s|--signoff:: Add Signed-off-by line at the end of the commit message. --v:: +-v|--verify:: Look for suspicious lines the commit introduces, and abort committing if there is one. The definition of 'suspicious lines' is currently the lines that has trailing whitespaces, and the lines whose indentation has a SP character immediately followed by a TAB - character. + character. This is the default. --e:: +-n|--no-verify:: + The opposite of `--verify`. + +-e|--edit:: The message taken from file with `-F`, command line with `-m`, and from file with `-C` are usually used as the commit log message unmodified. This option lets you further edit the message taken from these sources. +--:: + Do not interpret any more arguments as options. + <file>...:: Update specified paths in the index file before committing. diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 88bd3b0..f89b251 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -60,7 +60,7 @@ the old cvs2git tool. + If you need to pass multiple options, separate them with a comma. --P:: <cvsps-output-file> +-P <cvsps-output-file>:: Instead of calling cvsps, read the provided cvsps output file. Useful for debugging or when cvsps is being handled outside cvsimport. diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index cadaf59..cf7527f 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -17,14 +17,16 @@ ent 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. -`----------------`--------`-----------------------------`------------------ -Number of ents Options What's Compared Underlying command ---------------------------------------------------------------------------- -0 - index file and working tree git-diff-files -1 --cached ent and index file git-diff-index -1 - ent and working tree git-diff-index -2 - two ents git-diff-tree ---------------------------------------------------------------------------- +* When no <ent> is given, the working tree and the index + file is 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 + `--cached` can be given to compare the index file and + the named tree. + +* When two <ent>s are given, these two trees are compared + using `git-diff-tree`. OPTIONS ------- diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 438240c..d1b45f9 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -18,7 +18,7 @@ the objects necessary to complete them. The ref names and their object names of fetched refs are stored in `.git/FETCH_HEAD`. This information is left for a later merge -operation done by "git resolve" or "git octopus". +operation done by "git merge". OPTIONS diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 7a3abec..abb8fc8 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -8,7 +8,7 @@ git-format-patch - Prepare patches for e-mail submission. SYNOPSIS -------- -'git-format-patch' [-n][-o <dir>|--stdout][-k][--mbox][--diff-options] <his> [<mine>] +'git-format-patch' [-n | -k] [-o <dir> | --stdout] [-s] [-c] [--mbox] [--diff-options] <his> [<mine>] DESCRIPTION ----------- @@ -32,23 +32,34 @@ processing with applymbox. OPTIONS ------- --o <dir>:: +-o|--output-directory <dir>:: Use <dir> to store the resulting files, instead of the current working directory. --n:: +-n|--numbered:: Name output in '[PATCH n/m]' format. --k:: +-k|--keep-subject:: Do not strip/add '[PATCH]' from the first line of the commit log message. ---author, --date:: +-a|--author, -d|--date:: Output From: and Date: headers for commits made by yourself as well. Usually these are output only for commits made by people other than yourself. ---mbox:: +-s|--signoff:: + Add `Signed-off-by:` line to the commit message, using + the committer identity of yourself. + +-c|--check:: + Display suspicious lines in the patch. The definition + of 'suspicious lines' is currently the lines that has + trailing whitespaces, and the lines whose indentation + has a SP character immediately followed by a TAB + character. + +-m|--mbox:: Format the output files for closer to mbox format by adding a phony Unix "From " line, so they can be concatenated together and fed to `git-applymbox`. diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 07d2c42..0924931 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -8,7 +8,7 @@ git-hash-object - Computes object ID and optionally creates a blob from a file. SYNOPSIS -------- -'git-hash-object' [-t <type>] [-w] <any-file-on-the-filesystem> +'git-hash-object' [-t <type>] [-w] [--stdin] [--] <file>... DESCRIPTION ----------- @@ -29,6 +29,9 @@ OPTIONS -w:: Actually write the object into the object database. +--stdin:: + Read the object from standard input instead of from a file. + Author ------ Written by Junio C Hamano <junkio@cox.net> diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 088624f..1116e85 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -14,6 +14,12 @@ DESCRIPTION ----------- Downloads a remote git repository via HTTP. +OPTIONS +------- +commit-id:: + Either the hash or the filename under [URL]/refs/ to + pull. + -c:: Get the commit objects. -t:: diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index ef1826a..4486f0c 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -8,7 +8,14 @@ git-init-db - Creates an empty git repository SYNOPSIS -------- -'git-init-db' +'git-init-db' [--template=<template_directory>] + + +OPTIONS +------- +--template=<template_directory>:: + Provide the directory in from which templates will be used. + DESCRIPTION ----------- @@ -16,14 +23,26 @@ 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`. -If the 'GIT_DIR' environment variable is set then it specifies a path +If the `$GIT_DIR` environment variable is set then it specifies a path to use instead of `./.git` for the base of the repository. -If the object storage directory is specified via the 'GIT_OBJECT_DIRECTORY' +If the object storage directory is specified via the `$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories are created underneath - otherwise the default `$GIT_DIR/objects` directory is used. -"git-init-db" won't hurt an existing repository. +`git-init-db` won't hurt an existing repository. + + +EXAMPLES +-------- + +Start a new git repository for an existing code base:: ++ +---------------- +$ cd /path/to/my/codebase +$ git-init-db +---------------- + Author diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index c0a80d4..66fe60f 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -17,7 +17,7 @@ Displays the references other repository has. OPTIONS ------- ---heads --tags:: +-h|--heads, -t|--tags:: Limit to only refs/heads and refs/tags, respectively. These options are _not_ mutually exclusive; when given both, references stored in refs/heads and refs/tags are diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index ba0438e..b92a8b2 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -8,12 +8,15 @@ git-ls-tree - Lists the contents of a tree object. SYNOPSIS -------- -'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...] +'git-ls-tree' [-d] [-r] [-t] [-z] [--name-only] [--name-status] <tree-ish> [paths...] DESCRIPTION ----------- -Lists the contents of a tree object, like what "/bin/ls -a" does -in the current working directory. +Lists the contents of a given tree object, like what "/bin/ls -a" does +in the current working directory. Note that the usage is subtly different, +though - 'paths' denote just a list of patterns to match, e.g. so specifying +directory name (without '-r') will behave differently, and order of the +arguments does not matter. OPTIONS ------- @@ -21,36 +24,48 @@ OPTIONS Id of a tree-ish. -d:: - show only the named tree entry itself, not its children + Show only the named tree entry itself, not its children. -r:: - recurse into sub-trees + Recurse into sub-trees. + +-t:: + Show tree entries even when going to recurse them. Has no effect + if '-r' was not passed. '-d' implies '-t'. -z:: - \0 line termination on output + \0 line termination on output. + +--name-only:: +--name-status:: + List only filenames (instead of the "long" output), one per line. paths:: - When paths are given, show them. Otherwise implicitly - uses the root level of the tree as the sole path argument. + When paths are given, show them (note that this isn't really raw + pathnames, but rather a list of patterns to match). Otherwise + implicitly uses the root level of the tree as the sole path argument. Output Format ------------- <mode> SP <type> SP <object> TAB <file> -When `-z` option is not used, TAB, LF, and backslash characters -in pathnames are represented as `\t`, `\n`, and `\\`, -respectively. +When the `-z` option is not used, TAB, LF, and backslash characters +in pathnames are represented as `\t`, `\n`, and `\\`, respectively. Author ------ -Written by Linus Torvalds <torvalds@osdl.org> -Completely rewritten from scratch by Junio C Hamano <junkio@cox.net> +Written by Petr Baudis <pasky@suse.cz> +Completely rewritten from scratch by Junio C Hamano <junkio@cox.net>, +another major rewrite by Linus Torvalds <torvalds@osdl.org> Documentation -------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +Documentation by David Greaves, Junio C Hamano and the git-list +<git@vger.kernel.org>. + +This manual page is a stub. You can help the git documentation by expanding it. GIT --- diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 6030642..fbc986a 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -20,7 +20,7 @@ files are passed as arguments 5, 6 and 7. OPTIONS ------- --:: - Interpret all following arguments as filenames. + Do not interpret any more arguments as options. -a:: Run merge against all files in the index that need merging. diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index 3013b8d..d242b39 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -8,12 +8,15 @@ git-mv - Script used to move or rename a file, directory or symlink. SYNOPSIS -------- - 'git-mv' [-f] [-n] <source> <destination> - 'git-mv' [-f] [-n] [-k] <source> ... <destination directory> +'git-mv' <options>... <args>... DESCRIPTION ----------- This script is used to move or rename a file, directory or symlink. + + git-mv [-f] [-n] <source> <destination> + git-mv [-f] [-n] [-k] <source> ... <destination directory> + In the first form, it renames <source>, which must exist and be either a file, symlink or directory, to <destination>. In the second form, the last argument has to be an existing diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index d1e93db..009ec5a 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -8,7 +8,7 @@ git-pack-objects - Create a packed archive of objects. SYNOPSIS -------- -'git-pack-objects' [--local] [--incremental] [--window=N] [--depth=N] {--stdout | base-name} < object-list +'git-pack-objects' [--non-empty] [--local] [--incremental] [--window=N] [--depth=N] {--stdout | base-name} < object-list DESCRIPTION @@ -70,6 +70,10 @@ base-name:: that are packed and not in the local object store (i.e. borrowed from an alternate). +--non-empty:: + Only create a packed archive if it would contain at + least one object. + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 8d96a91..37c53a9 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -9,19 +9,22 @@ residing in a pack file. SYNOPSIS -------- -'git-prune-packed' +'git-prune-packed' [-n] + DESCRIPTION ----------- -This program search the GIT_OBJECT_DIR for all objects that currently exist in -a pack file as well as the independent object directories. +This program search the `$GIT_OBJECT_DIR` for all objects that currently +exist in a pack file as well as the independent object directories. All such extra objects are removed. A pack is a collection of objects, individually compressed, with delta compression applied, stored in a single file, with an associated index file. -Packs are used to reduce the load on mirror systems, backup engines, disk storage, etc. +Packs are used to reduce the load on mirror systems, backup engines, +disk storage, etc. + OPTIONS ------- diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 3367c9b..f694fcb 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -8,15 +8,16 @@ git-prune - Prunes all unreachable objects from the object database SYNOPSIS -------- -'git-prune' [-n] +'git-prune' [-n] [--] [<head>...] DESCRIPTION ----------- -This runs `git-fsck-objects --unreachable` using the heads -specified on the command line (or `$GIT_DIR/refs/heads/\*` and -`$GIT_DIR/refs/tags/\*` if none is specified), and prunes all -unreachable objects from the object database. In addition, it +This runs `git-fsck-objects --unreachable` using all the refs +available in `$GIT_DIR/refs`, optionally with additional set of +objects specified on the command line, and prunes all +objects unreachable from any of these head objects from the object database. +In addition, it prunes the unpacked objects that are also found in packs by running `git prune-packed`. @@ -27,6 +28,24 @@ OPTIONS Do not remove anything; just report what it would remove. +--:: + Do not interpret any more arguments as options. + +<head>...:: + In addition to objects + reachable from any of our references, keep objects + reachable from listed <head>s. + +EXAMPLE +------- + +To prune objects not used by your repository nor another that +borrows from your repository via its +`.git/objects/info/alternates`: + +------------ +$ git prune $(cd ../another && $(git-rev-parse --all)) +------------ Author ------ diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index f45ac5e..2254bac 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -16,6 +16,10 @@ DESCRIPTION Updates remote refs using local refs, while sending objects necessary to complete the given refs. +You can make "interesting" things to happen on the repository +every time you push into it, by setting up 'hooks' there. See +documentation for gitlink:git-receive-pack[1]. + OPTIONS ------- @@ -31,6 +35,7 @@ include::pull-fetch-param.txt[] This flag disables the check. What this means is that the local repository can lose commits; use it with care. + Author ------ Written by Junio C Hamano <junkio@cox.net> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 6e92e4a..6fbd6d9 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,22 +8,22 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git-read-tree' (<tree-ish> | [-m [-u|-i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) +'git-read-tree' (<tree-ish> | [[-m | --reset] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION ----------- Reads the tree information given by <tree-ish> into the index, but does not actually *update* any of the files it "caches". (see: -git-checkout-index) +gitlink:git-checkout-index[1]) Optionally, it can merge a tree into the index, perform a -fast-forward (i.e. 2-way) merge, or a 3-way merge, with the -m -flag. When used with -m, the -u flag causes it to also update +fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m` +flag. When used with `-m`, the `-u` flag causes it to also update the files in the work tree with the result of the merge. -Trivial merges are done by "git-read-tree" itself. Only conflicting paths -will be in unmerged state when "git-read-tree" returns. +Trivial merges are done by `git-read-tree` itself. Only conflicting paths +will be in unmerged state when `git-read-tree` returns. OPTIONS ------- @@ -56,7 +56,7 @@ OPTIONS Merging ------- -If '-m' is specified, "git-read-tree" can perform 3 kinds of +If `-m` is specified, `git-read-tree` can perform 3 kinds of merge, a single tree merge if only 1 tree is given, a fast-forward merge with 2 trees, or a 3-way merge if 3 trees are provided. @@ -65,23 +65,23 @@ provided. Single Tree Merge ~~~~~~~~~~~~~~~~~ If only 1 tree is specified, git-read-tree operates as if the user did not -specify '-m', except that if the original index has an entry for a +specify `-m`, except that if the original index has an entry for a given pathname, and the contents of the path matches with the tree being read, the stat info from the index is used. (In other words, the index's stat()s take precedence over the merged tree's). -That means that if you do a "git-read-tree -m <newtree>" followed by a -"git-checkout-index -f -u -a", the "git-checkout-index" only checks out +That means that if you do a `git-read-tree -m <newtree>` followed by a +`git-checkout-index -f -u -a`, the `git-checkout-index` only checks out the stuff that really changed. -This is used to avoid unnecessary false hits when "git-diff-files" is -run after git-read-tree. +This is used to avoid unnecessary false hits when `git-diff-files` is +run after `git-read-tree`. Two Tree Merge ~~~~~~~~~~~~~~ -Typically, this is invoked as "git-read-tree -m $H $M", where $H +Typically, this is invoked as `git-read-tree -m $H $M`, where $H is the head commit of the current repository, and $M is the head of a foreign tree, which is simply ahead of $H (i.e. we are in a fast forward situation). @@ -94,7 +94,7 @@ the following: 2. The user wants to fast-forward to $M. -In this case, the "git-read-tree -m $H $M" command makes sure +In this case, the `git-read-tree -m $H $M` command makes sure that no local change is lost as the result of this "merge". Here are the "carry forward" rules: @@ -141,13 +141,13 @@ operating under the -u flag. When this form of git-read-tree returns successfully, you can see what "local changes" you made are carried forward by running -"git-diff-index --cached $M". Note that this does not -necessarily match "git-diff-index --cached $H" would have +`git-diff-index --cached $M`. Note that this does not +necessarily match `git-diff-index --cached $H` would have produced before such a two tree merge. This is because of cases 18 and 19 --- if you already had the changes in $M (e.g. maybe -you picked it up via e-mail in a patch form), "git-diff-index ---cached $H" would have told you about the change before this -merge, but it would not show in "git-diff-index --cached $M" +you picked it up via e-mail in a patch form), `git-diff-index +--cached $H` would have told you about the change before this +merge, but it would not show in `git-diff-index --cached $M` output after two-tree merge. @@ -156,31 +156,39 @@ output after two-tree merge. Each "index" entry has two bits worth of "stage" state. stage 0 is the normal one, and is the only one you'd see in any kind of normal use. -However, when you do "git-read-tree" with three trees, the "stage" +However, when you do `git-read-tree` with three trees, the "stage" starts out at 1. This means that you can do - git-read-tree -m <tree1> <tree2> <tree3> +---------------- +$ git-read-tree -m <tree1> <tree2> <tree3> +---------------- and you will end up with an index with all of the <tree1> entries in "stage1", all of the <tree2> entries in "stage2" and all of the -<tree3> entries in "stage3". +<tree3> entries in "stage3". When performing a merge of another +branch into the current branch, we use the common ancestor tree +as <tree1>, the current branch head as <tree2>, and the other +branch head as <tree3>. -Furthermore, "git-read-tree" has special-case logic that says: if you see +Furthermore, `git-read-tree` has special-case logic that says: if you see a file that matches in all respects in the following states, it "collapses" back to "stage0": - stage 2 and 3 are the same; take one or the other (it makes no - difference - the same work has been done on stage 2 and 3) + difference - the same work has been done on our branch in + stage 2 and their branch in stage 3) - stage 1 and stage 2 are the same and stage 3 is different; take - stage 3 (some work has been done on stage 3) + stage 3 (our branch in stage 2 did not do anything since the + ancestor in stage 1 while their branch in stage 3 worked on + it) - stage 1 and stage 3 are the same and stage 2 is different take - stage 2 (some work has been done on stage 2) + stage 2 (we did something while they did nothing) -The "git-write-tree" command refuses to write a nonsensical tree, and it +The `git-write-tree` command refuses to write a nonsensical tree, and it will complain about unmerged entries if it sees a single entry that is not stage 0. @@ -220,12 +228,10 @@ populated. Here is an outline of how the algorithm works: matching "stage1" entry if it exists too. .. all the normal trivial rules .. -You would normally use "git-merge-index" with supplied -"git-merge-one-file" to do this last step. The script -does not touch the files in the work tree, and the entire merge -happens in the index file. In other words, there is no need to -worry about what is in the working directory, since it is never -shown and never used. +You would normally use `git-merge-index` with supplied +`git-merge-one-file` to do this last step. The script updates +the files in the working tree as it merges each path and at the +end of a successful merge. When you start a 3-way merge with an index file that is already populated, it is assumed that it represents the state of the @@ -236,33 +242,54 @@ merge refuses to run if it finds an entry in the original index file that does not match stage 2. This is done to prevent you from losing your work-in-progress -changes. To illustrate, suppose you start from what has been +changes, and mixing your random changes in an unrelated merge +commit. To illustrate, suppose you start from what has been commited last to your repository: - $ JC=`git-rev-parse --verify "HEAD^0"` - $ git-checkout-index -f -u -a $JC +---------------- +$ JC=`git-rev-parse --verify "HEAD^0"` +$ git-checkout-index -f -u -a $JC +---------------- You do random edits, without running git-update-index. And then you notice that the tip of your "upstream" tree has advanced since you pulled from him: - $ git-fetch rsync://.... linus - $ LT=`cat .git/MERGE_HEAD` +---------------- +$ git-fetch git://.... linus +$ LT=`cat .git/FETCH_HEAD` +---------------- Your work tree is still based on your HEAD ($JC), but you have some edits since. Three-way merge makes sure that you have not added or modified index entries since $JC, and if you haven't, then does the right thing. So with the following sequence: - $ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT - $ git-merge-index git-merge-one-file -a - $ echo "Merge with Linus" | \ - git-commit-tree `git-write-tree` -p $JC -p $LT +---------------- +$ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT +$ git-merge-index git-merge-one-file -a +$ echo "Merge with Linus" | \ + git-commit-tree `git-write-tree` -p $JC -p $LT +---------------- -what you would commit is a pure merge between $JC and LT without +what you would commit is a pure merge between $JC and $LT without your work-in-progress changes, and your work tree would be updated to the result of the merge. +However, if you have local changes in the working tree that +would be overwritten by this merge,`git-read-tree` will refuse +to run to prevent your changes from being lost. + +In other words, there is no need to worry about what exists only +in the working tree. When you have local changes in a part of +the project that is not involved in the merge, your changes do +not interfere with the merge, and are kept intact. When they +*do* interfere, the merge does not even start (`git-read-tree` +complains loudly and fails without modifying anything). In such +a case, you can simply continue doing what you were in the +middle of doing, and when your working tree is ready (i.e. you +have finished your work-in-progress), attempt the merge again. + See Also -------- diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 8afde14..60debca 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -71,6 +71,10 @@ packed and is served via a dumb transport. #!/bin/sh exec git-update-server-info +There are other real-world examples of using update and +post-update hooks found in the Documentation/howto directory. + + OPTIONS ------- <directory>:: diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 0c1ae49..9060fe8 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -9,7 +9,7 @@ objects into pack files. SYNOPSIS -------- -'git-repack' [-a] [-d] +'git-repack' [-a] [-d] [-l] [-n] DESCRIPTION ----------- @@ -39,6 +39,13 @@ OPTIONS After packing, if the newly created packs make some existing packs redundant, remove the redundant packs. +-l:: + Pass the `--local` option to `git pack-objects`, see + gitlink:git-pack-objects[1]. + +-n:: + Do not update the server information with + `git update-server-info`. Author ------ diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index feebd81..e27c680 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -7,7 +7,7 @@ git-revert - Revert an existing commit. SYNOPSIS -------- -'git-revert' [-n] <commit> +'git-revert' [--edit | --no-edit] [-n] <commit> DESCRIPTION ----------- @@ -20,7 +20,16 @@ OPTIONS <commit>:: Commit to revert. --n:: +-e|--edit:: + With this option, `git-revert` will let you edit the commit + message prior committing the revert. This is the default if + you run the command from a terminal. + +--no-edit:: + With this option, `git-revert` will not start the commit + message editor. + +-n|--no-commit:: Usually the command automatically creates a commit with a commit log message stating which commit was reverted. This flag applies the change necessary to revert the diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index c6c97b2..ffe64d8 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -7,23 +7,40 @@ git-show-branch - Show branches and their commits. SYNOPSIS -------- -'git-show-branch [--all] [--heads] [--tags] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] <reference>...' +'git-show-branch [--all] [--heads] [--tags] [--topo-order] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [<rev> | <glob>]...' DESCRIPTION ----------- -Shows the head commits from the named <reference> (or all refs under -$GIT_DIR/refs/heads), and displays concise list of commit logs -to show their relationship semi-visually. + +Shows the commit ancestry graph starting from the commits named +with <rev>s or <globs>s (or all refs under $GIT_DIR/refs/heads +and/or $GIT_DIR/refs/tags) semi-visually. + +It cannot show more than 29 branches and commits at a time. + OPTIONS ------- -<reference>:: - Name of the reference under $GIT_DIR/refs/. +<rev>:: + Arbitrary extended SHA1 expression (see `git-rev-parse`) + that typically names a branch HEAD or a tag. + +<glob>:: + A glob pattern that matches branch or tag names under + $GIT_DIR/refs. For example, if you have many topic + branches under $GIT_DIR/refs/heads/topic, giving + `topic/*` would show all of them. --all --heads --tags:: Show all refs under $GIT_DIR/refs, $GIT_DIR/refs/heads, and $GIT_DIR/refs/tags, respectively. +--topo-order:: + By default, the branches and their commits are shown in + reverse chronological order. This option makes them + appear in topological order (i.e., descendant commits + are shown before their parents). + --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-tag.txt b/Documentation/git-tag.txt index 841c9dc..e8892bb 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -10,26 +10,6 @@ SYNOPSIS -------- 'git-tag' [-a | -s | -u <key-id>] [-f | -d] [-m <msg>] <name> [<head>] -OPTIONS -------- --a:: - Make an unsigned, annotated tag object - --s:: - Make a GPG-signed tag, using the default e-mail address's key - --u <key-id>:: - Make a GPG-signed tag, using the given key - --f:: - Replace an existing tag with the given name (instead of failing) - --d:: - Delete an existing tag with the given name - --m <msg>:: - Use the given tag message (instead of prompting) - DESCRIPTION ----------- Adds a 'tag' reference in .git/refs/tags/ @@ -52,6 +32,26 @@ GnuPG key for signing. `-d <tag>` deletes the tag. +OPTIONS +------- +-a:: + Make an unsigned, annotated tag object + +-s:: + Make a GPG-signed tag, using the default e-mail address's key + +-u <key-id>:: + Make a GPG-signed tag, using the given key + +-f:: + Replace an existing tag with the given name (instead of failing) + +-d:: + Delete an existing tag with the given name + +-m <msg>:: + Use the given tag message (instead of prompting) + Author ------ diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index fdcb8be..c74311d 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -123,7 +123,9 @@ merging. To pretend you have a file with mode and sha1 at path, say: - $ git-update-index --cacheinfo mode sha1 path +---------------- +$ git-update-index --cacheinfo mode sha1 path +---------------- '--info-only' is used to register files without placing them in the object database. This is useful for status-only repositories. @@ -134,11 +136,70 @@ in the database but the file isn't available locally. '--info-only' is useful when the file is available, but you do not wish to update the object database. + +Using --index-info +------------------ + +`--index-info` is a more powerful mechanism that lets you feed +multiple entry definitions from the standard input, and designed +specifically for scripts. It can take inputs of three formats: + + . mode SP sha1 TAB path ++ +The first format is what "git-apply --index-info" +reports, and used to reconstruct a partial tree +that is used for phony merge base tree when falling +back on 3-way merge. + + . mode SP type SP sha1 TAB path ++ +The second format is to stuff git-ls-tree output +into the index file. + + . mode SP sha1 SP stage TAB path ++ +This format is to put higher order stages into the +index file and matches git-ls-files --stage output. + +To place a higher stage entry to the index, the path should +first be removed by feeding a mode=0 entry for the path, and +then feeding necessary input lines in the third format. + +For example, starting with this index: + +------------ +$ git ls-files -s +100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0 frotz +------------ + +you can feed the following input to `--index-info`: + +------------ +$ git update-index --index-info +0 0000000000000000000000000000000000000000 frotz +100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz +100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz +------------ + +The first line of the input feeds 0 as the mode to remove the +path; the SHA1 does not matter as long as it is well formatted. +Then the second and third line feeds stage 1 and stage 2 entries +for that path. After the above, we would end up with this: + +------------ +$ git ls-files -s +100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz +100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz +------------ + + Examples -------- To update and refresh only the files already checked out: - git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh +---------------- +$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh +---------------- Configuration @@ -146,12 +207,18 @@ Configuration The command honors `core.filemode` configuration variable. If your repository is on an filesystem whose executable bits are -unreliable, this should be set to 'false'. This causes the -command to ignore differences in file modes recorded in the -index and the file mode on the filesystem if they differ only on +unreliable, this should be set to 'false' (see gitlink:git-repo-config[1]). +This causes the command to ignore differences in file modes recorded +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=`. + +See Also +-------- +gitlink:git-repo-config[1] + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 3d0dea0..527fb30 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -22,7 +22,7 @@ pull decisions. This command generates such auxiliary files. OPTIONS ------- ---force:: +-f|--force:: Update the info files from scratch. diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index cd74ffd..d032280 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -8,7 +8,7 @@ git-verify-pack - Validate packed git archive files. SYNOPSIS -------- -'git-verify-pack' [-v] <pack>.idx ... +'git-verify-pack' [-v] [--] <pack>.idx ... DESCRIPTION @@ -25,6 +25,8 @@ OPTIONS -v:: After verifying the pack, show list of objects contained in the pack. +--:: + Do not interpret any more arguments as options. OUTPUT FORMAT ------------- diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index abee05f..77e12cb 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -14,19 +14,21 @@ DESCRIPTION ----------- Creates a tree object using the current index. -The index must be merged. +The index must be in a fully merged state. -Conceptually, "git-write-tree" sync()s the current index contents +Conceptually, `git-write-tree` sync()s the current index contents into a set of tree files. In order to have that match what is actually in your directory right -now, you need to have done a "git-update-index" phase before you did the -"git-write-tree". +now, you need to have done a `git-update-index` phase before you did the +`git-write-tree`. + OPTIONS ------- --missing-ok:: - Normally "git-write-tree" ensures that the objects referenced by the - directory exist in the object database. This option disables this check. + Normally `git-write-tree` ensures that the objects referenced by the + directory exist in the object database. This option disables this + check. Author ------ diff --git a/Documentation/git.txt b/Documentation/git.txt index a518249..45773db 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -36,31 +36,35 @@ OPTIONS CORE GIT COMMANDS ----------------- Before reading this cover to cover, you may want to take a look -at the link:tutorial.html[tutorial] document. - -The <<Discussion>> section below contains much useful definition and -clarification info - read that first. And of the commands, I suggest -reading gitlink:git-update-index[1] and -gitlink:git-read-tree[1] first - I wish I had! - -If you are migrating from CVS, link:cvs-migration.html[cvs migration] +at the link:tutorial.html[tutorial] document. If you are +migrating from CVS, link:cvs-migration.html[cvs migration] document may be helpful after you finish the tutorial. +The <<Discussion>> section below contains much useful definition +and clarification info - read that first. After that, if you +are interested in using git to manage (version control) +projects, use link:everyday.html[Everyday GIT] as a guide to the +minimum set of commands you need to know for day-to-day work. + After you get the general feel from the tutorial and this overview page, you may want to take a look at the link:howto-index.html[howto] documents. +If you are writing your own Porcelain, you need to be familiar +with most of the low level commands --- I suggest starting from +gitlink:git-update-index[1] and gitlink:git-read-tree[1]. + David Greaves <david@dgreaves.com> 08/05/05 -Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to -reflect recent changes. +Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 and +further on 2005-12-07 to reflect recent changes. Commands Overview ----------------- The git commands can helpfully be split into those that manipulate -the repository, the index and the working fileset, those that +the repository, the index and the files in the working tree, those that interrogate and compare them, and those that moves objects and references between repositories. @@ -79,25 +83,26 @@ gitlink:git-apply[1]:: applies it to the working tree. gitlink:git-checkout-index[1]:: - Copy files from the index to the working directory + Copy files from the index to the working tree. gitlink:git-commit-tree[1]:: - Creates a new commit object + Creates a new commit object. gitlink:git-hash-object[1]:: Computes the object ID from a file. gitlink:git-index-pack[1]:: - Build pack index file for an existing packed archive. + Build pack idx file for an existing packed archive. gitlink:git-init-db[1]:: - Creates an empty git object database + Creates an empty git object database, or reinitialize an + existing one. gitlink:git-merge-index[1]:: - Runs a merge for files needing merging + Runs a merge for files needing merging. gitlink:git-mktag[1]:: - Creates a tag object + Creates a tag object. gitlink:git-pack-objects[1]:: Creates a packed archive of objects. @@ -106,7 +111,7 @@ gitlink:git-prune-packed[1]:: Remove extra objects that are already in pack files. gitlink:git-read-tree[1]:: - Reads tree information into the directory index + Reads tree information into the index. gitlink:git-repo-config[1]:: Get and set options in .git/config. @@ -115,65 +120,65 @@ gitlink:git-unpack-objects[1]:: Unpacks objects out of a packed archive. gitlink:git-update-index[1]:: - Modifies the index or directory cache + Registers files in the working tree to the index. gitlink:git-write-tree[1]:: - Creates a tree from the current index + Creates a tree from the index. Interrogation commands ~~~~~~~~~~~~~~~~~~~~~~ gitlink:git-cat-file[1]:: - Provide content or type information for repository objects + Provide content or type/size information for repository objects. gitlink:git-diff-index[1]:: - Compares content and mode of blobs between the index and repository + Compares content and mode of blobs between the index and repository. gitlink:git-diff-files[1]:: - Compares files in the working tree and the index + Compares files in the working tree and the index. gitlink:git-diff-stages[1]:: - Compares two "merge stages" in the index file. + Compares two "merge stages" in the index. gitlink:git-diff-tree[1]:: - Compares the content and mode of blobs found via two tree objects + Compares the content and mode of blobs found via two tree objects. gitlink:git-fsck-objects[1]:: - Verifies the connectivity and validity of the objects in the database + Verifies the connectivity and validity of the objects in the database. gitlink:git-ls-files[1]:: - Information about files in the index/working directory + Information about files in the index and the working tree. gitlink:git-ls-tree[1]:: - Displays a tree object in human readable form + Displays a tree object in human readable form. gitlink:git-merge-base[1]:: - Finds as good a common ancestor as possible for a merge + Finds as good common ancestors as possible for a merge. gitlink:git-name-rev[1]:: - Find symbolic names for given revs + Find symbolic names for given revs. gitlink:git-rev-list[1]:: - Lists commit objects in reverse chronological order + Lists commit objects in reverse chronological order. gitlink:git-show-index[1]:: Displays contents of a pack idx file. gitlink:git-tar-tree[1]:: - Creates a tar archive of the files in the named tree + Creates a tar archive of the files in the named tree object. gitlink:git-unpack-file[1]:: - Creates a temporary file with a blob's contents + Creates a temporary file with a blob's contents. gitlink:git-var[1]:: - Displays a git logical variable + Displays a git logical variable. gitlink:git-verify-pack[1]:: - Validates packed git archive files + Validates packed git archive files. -The interrogate commands may create files - and you can force them to -touch the working file set - but in general they don't +In general, the interrogate commands do not touch the files in +the working tree. Synching repositories @@ -181,19 +186,24 @@ Synching repositories gitlink:git-clone-pack[1]:: Clones a repository into the current repository (engine - for ssh and local transport) + for ssh and local transport). gitlink:git-fetch-pack[1]:: - Updates from a remote repository. + Updates from a remote repository (engine for ssh and + local transport). gitlink:git-http-fetch[1]:: - Downloads a remote git repository via HTTP + Downloads a remote git repository via HTTP by walking + commit chain. gitlink:git-local-fetch[1]:: - Duplicates another git repository on a local system + Duplicates another git repository on a local system by + walking commit chain. gitlink:git-peek-remote[1]:: - Lists references on a remote repository using upload-pack protocol. + Lists references on a remote repository using + upload-pack protocol (engine for ssh and local + transport). gitlink:git-receive-pack[1]:: Invoked by 'git-send-pack' to receive what is pushed to it. @@ -205,10 +215,11 @@ gitlink:git-shell[1]:: Restricted shell for GIT-only SSH access. gitlink:git-ssh-fetch[1]:: - Pulls from a remote repository over ssh connection + Pulls from a remote repository over ssh connection by + walking commit chain. gitlink:git-ssh-upload[1]:: - Helper "server-side" program used by git-ssh-fetch + Helper "server-side" program used by git-ssh-fetch. gitlink:git-update-server-info[1]:: Updates auxiliary information on a dumb server to help @@ -223,16 +234,16 @@ Porcelain-ish Commands ---------------------- gitlink:git-add[1]:: - Add paths to the index file. + Add paths to the index. gitlink:git-am[1]:: Apply patches from a mailbox, but cooler. gitlink:git-applymbox[1]:: - Apply patches from a mailbox. + Apply patches from a mailbox, original version by Linus. gitlink:git-bisect[1]:: - Find the change that introduced a bug. + Find the change that introduced a bug by binary search. gitlink:git-branch[1]:: Create and Show branches. @@ -259,7 +270,7 @@ gitlink:git-format-patch[1]:: Prepare patches for e-mail submission. gitlink:git-grep[1]:: - Print lines matching a pattern + Print lines matching a pattern. gitlink:git-log[1]:: Shows commit logs. @@ -283,7 +294,7 @@ gitlink:git-push[1]:: Update remote refs along with associated objects. gitlink:git-rebase[1]:: - Rebase local commits to new upstream head. + Rebase local commits to the updated upstream head. gitlink:git-repack[1]:: Pack unpacked objects in a repository. @@ -324,7 +335,7 @@ gitlink:git-archimport[1]:: Import an arch repository into git. gitlink:git-convert-objects[1]:: - Converts old-style git repository + Converts old-style git repository. gitlink:git-cvsimport[1]:: Salvage your data out of another SCM people love to hate. @@ -333,10 +344,10 @@ gitlink:git-lost-found[1]:: Recover lost refs that luckily have not yet been pruned. gitlink:git-merge-one-file[1]:: - The standard helper program to use with "git-merge-index" + The standard helper program to use with `git-merge-index`. gitlink:git-prune[1]:: - Prunes all unreachable objects from the object database + Prunes all unreachable objects from the object database. gitlink:git-relink[1]:: Hardlink common objects in local repositories. @@ -348,10 +359,10 @@ gitlink:git-sh-setup[1]:: Common git shell script setup code. gitlink:git-symbolic-ref[1]:: - Read and modify symbolic refs + Read and modify symbolic refs. gitlink:git-tag[1]:: - An example script to create a tag object signed with GPG + An example script to create a tag object signed with GPG. gitlink:git-update-ref[1]:: Update the object name stored in a ref safely. @@ -375,16 +386,19 @@ gitlink:git-get-tar-commit-id[1]:: Extract commit ID from an archive created using git-tar-tree. gitlink:git-mailinfo[1]:: - Extracts patch from a single e-mail message. + Extracts patch and authorship information from a single + e-mail message, optionally transliterating the commit + message into utf-8. gitlink:git-mailsplit[1]:: - git-mailsplit. + A stupid program to split UNIX mbox format mailbox into + individual pieces of e-mail. gitlink:git-patch-id[1]:: Compute unique ID for a patch. gitlink:git-parse-remote[1]:: - Routines to help parsing $GIT_DIR/remotes/ + Routines to help parsing `$GIT_DIR/remotes/` files. gitlink:git-request-pull[1]:: git-request-pull. @@ -406,22 +420,20 @@ Commands not yet documented --------------------------- gitlink:gitk[1]:: - gitk. + The gitk repository browser. Configuration Mechanism ----------------------- -Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file +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 people. Here is an example: ------------ # -# This is the config file, and -# a '#' or ';' character indicates -# a comment +# A '#' or ';' character indicates a comment. # ; core variables @@ -443,30 +455,30 @@ their operation accordingly. Identifier Terminology ---------------------- <object>:: - Indicates the sha1 identifier for any type of object + Indicates the object name for any type of object. <blob>:: - Indicates a blob object sha1 identifier + Indicates a blob object name. <tree>:: - Indicates a tree object sha1 identifier + Indicates a tree object name. <commit>:: - Indicates a commit object sha1 identifier + Indicates a commit object name. <tree-ish>:: - Indicates a tree, commit or tag object sha1 identifier. A + Indicates a tree, commit or tag object name. A command that takes a <tree-ish> argument ultimately wants to operate on a <tree> object but automatically dereferences <commit> and <tag> objects that point at a <tree>. <type>:: Indicates that an object type is required. - Currently one of: blob/tree/commit/tag + Currently one of: `blob`, `tree`, `commit`, or `tag`. <file>:: - Indicates a filename - always relative to the root of - the tree structure GIT_INDEX_FILE describes. + Indicates a filename - almost always relative to the + root of the tree structure `GIT_INDEX_FILE` describes. Symbolic Identifiers -------------------- @@ -474,17 +486,20 @@ Any git command accepting any <object> can also use the following symbolic notation: HEAD:: - indicates the head of the repository (ie the contents of - `$GIT_DIR/HEAD`) + indicates the head of the current branch (i.e. the + contents of `$GIT_DIR/HEAD`). + <tag>:: - a valid tag 'name'+ - (ie the contents of `$GIT_DIR/refs/tags/<tag>`) + a valid tag 'name' + (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). + <head>:: - a valid head 'name'+ - (ie the contents of `$GIT_DIR/refs/heads/<head>`) + a valid head 'name' + (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). + <snap>:: - a valid snapshot 'name'+ - (ie the contents of `$GIT_DIR/refs/snap/<snap>`) + a valid snapshot 'name' + (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`). File/Directory Structure @@ -493,7 +508,7 @@ File/Directory Structure Please see link:repository-layout.html[repository layout] document. Higher level SCMs may provide and manage additional information in the -GIT_DIR. +`$GIT_DIR`. Terminology @@ -509,7 +524,7 @@ The git Repository ~~~~~~~~~~~~~~~~~~ These environment variables apply to 'all' core git commands. Nb: it is worth noting that they may be used/overridden by SCMS sitting above -git so take care if using Cogito etc +git so take care if using Cogito etc. 'GIT_INDEX_FILE':: This environment allows the specification of an alternate @@ -530,9 +545,9 @@ git so take care if using Cogito etc written to these directories. 'GIT_DIR':: - If the 'GIT_DIR' environment variable is set then it specifies - a path to use instead of `./.git` for the base of the - repository. + If the 'GIT_DIR' environment variable is set then it + specifies a path to use instead of the default `.git` + for the base of the repository. git Commits ~~~~~~~~~~~ @@ -559,7 +574,7 @@ include::../README[] Authors ------- git's founding father is Linus Torvalds <torvalds@osdl.org>. - The current git nurse is Junio C. Hamano <junkio@cox.net>. + The current git nurse is Junio C Hamano <junkio@cox.net>. The git potty was written by Andres Ericsson <ae@op5.se>. General upbringing is handled by the git-list <git@vger.kernel.org>. diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index 07df6b4..520f4c5 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -20,7 +20,7 @@ hash:: object database:: Stores a set of "objects", and an individial object is identified - by its object name. The object usually live in $GIT_DIR/objects/. + by its object name. The objects usually live in `$GIT_DIR/objects/`. blob object:: Untyped object, e.g. the contents of a file. @@ -109,15 +109,15 @@ head:: branch:: A non-cyclical graph of revisions, i.e. the complete history of a particular revision, which is called the branch head. The - branch heads are stored in $GIT_DIR/refs/heads/. + branch heads are stored in `$GIT_DIR/refs/heads/`. ref:: A 40-byte hex representation of a SHA1 pointing to a particular - object. These may be stored in $GIT_DIR/refs/. + object. These may be stored in `$GIT_DIR/refs/`. head ref:: A ref pointing to a head. Often, this is abbreviated to "head". - Head refs are stored in $GIT_DIR/refs/heads/. + Head refs are stored in `$GIT_DIR/refs/heads/`. tree-ish:: A ref pointing to either a commit object, a tree object, or a @@ -125,7 +125,7 @@ tree-ish:: ent:: Favorite synonym to "tree-ish" by some total geeks. See - http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth + `http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth explanation. tag object:: @@ -137,7 +137,7 @@ tag object:: tag:: A ref pointing to a tag or commit object. In contrast to a head, a tag is not changed by a commit. Tags (not tag objects) are - stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with + stored in `$GIT_DIR/refs/tags/`. A git tag has nothing to do with a Lisp tag (which is called object type in git's context). A tag is most typically used to mark a particular point in the commit ancestry chain. diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt index dacaf17..3a33696 100644 --- a/Documentation/howto/update-hook-example.txt +++ b/Documentation/howto/update-hook-example.txt @@ -1,4 +1,4 @@ -From: Junio C Hamano <junkio@cox.net> +From: Junio C Hamano <junkio@cox.net> and Carl Baldwin <cnb@fc.hp.com> Subject: control access to branches. Date: Thu, 17 Nov 2005 23:55:32 -0800 Message-ID: <7vfypumlu3.fsf@assigned-by-dhcp.cox.net> @@ -26,63 +26,137 @@ section of the documentation: So if your policy is (1) always require fast-forward push (i.e. never allow "git-push repo +branch:branch"), (2) you have a list of users allowed to update each branch, and (3) you -do not let tags to be overwritten, then: - - #!/bin/sh - # This is a sample hooks/update script, written by JC - # in his e-mail buffer, so naturally it is not tested - # but hopefully would convey the idea. - - umask 002 - case "$1" in - refs/tags/*) - # No overwriting an existing tag - if test -f "$GIT_DIR/$1" - then - exit 1 - fi - ;; - refs/heads/*) - # No rebasing or rewinding - if expr "$2" : '0*$' >/dev/null - then - # creating a new branch - ; - else - # updating -- make sure it is a fast forward - mb=`git-merge-base "$2" "$3"` - case "$mb,$2" in - "$2,$mb") - ;; # fast forward -- happy - *) - exit 1 ;; # unhappy - esac - fi - ;; - *) - # No funny refs allowed - exit 1 - ;; - esac - - # Is the user allowed to update it? - me=`id -u -n` ;# e.g. "junio" - while read head_pattern users - do - if expr "$1" : "$head_pattern" >/dev/null - then - case " $users " in - *" $me "*) - exit 0 ;; # happy - ' * ') - exit 0 ;; # anybody - esac - fi - done - exit 1 - -For the sake of simplicity, I assumed that you keep something -like this in $GIT_DIR/info/allowed-pushers file: +do not let tags to be overwritten, then you can use something +like this as your hooks/update script. + +[jc: editorial note. This is a much improved version by Carl +since I posted the original outline] + +-- >8 -- beginning of script -- >8 -- + +#!/bin/bash + +umask 002 + +# If you are having trouble with this access control hook script +# you can try setting this to true. It will tell you exactly +# why a user is being allowed/denied access. + +verbose=false + +# Default shell globbing messes things up downstream +GLOBIGNORE=* + +function grant { + $verbose && echo >&2 "-Grant- $1" + echo grant + exit 0 +} + +function deny { + $verbose && echo >&2 "-Deny- $1" + echo deny + exit 1 +} + +function info { + $verbose && echo >&2 "-Info- $1" +} + +# Implement generic branch and tag policies. +# - Tags should not be updated once created. +# - Branches should only be fast-forwarded. +case "$1" in + refs/tags/*) + [ -f "$GIT_DIR/$1" ] && + deny >/dev/null "You can't overwrite an existing tag" + ;; + refs/heads/*) + # No rebasing or rewinding + if expr "$2" : '0*$' >/dev/null; then + info "The branch '$1' is new..." + else + # updating -- make sure it is a fast forward + mb=$(git-merge-base "$2" "$3") + case "$mb,$2" in + "$2,$mb") info "Update is fast-forward" ;; + *) deny >/dev/null "This is not a fast-forward update." ;; + esac + fi + ;; + *) + deny >/dev/null \ + "Branch is not under refs/heads or refs/tags. What are you trying to do?" + ;; +esac + +# Implement per-branch controls based on username +allowed_users_file=$GIT_DIR/info/allowed-users +username=$(id -u -n) +info "The user is: '$username'" + +if [ -f "$allowed_users_file" ]; then + rc=$(cat $allowed_users_file | grep -v '^#' | grep -v '^$' | + while read head_pattern user_patterns; do + matchlen=$(expr "$1" : "$head_pattern") + if [ "$matchlen" == "${#1}" ]; then + info "Found matching head pattern: '$head_pattern'" + for user_pattern in $user_patterns; do + info "Checking user: '$username' against pattern: '$user_pattern'" + matchlen=$(expr "$username" : "$user_pattern") + if [ "$matchlen" == "${#username}" ]; then + grant "Allowing user: '$username' with pattern: '$user_pattern'" + fi + done + deny "The user is not in the access list for this branch" + fi + done + ) + case "$rc" in + grant) grant >/dev/null "Granting access based on $allowed_users_file" ;; + deny) deny >/dev/null "Denying access based on $allowed_users_file" ;; + *) ;; + esac +fi + +allowed_groups_file=$GIT_DIR/info/allowed-groups +groups=$(id -G -n) +info "The user belongs to the following groups:" +info "'$groups'" + +if [ -f "$allowed_groups_file" ]; then + rc=$(cat $allowed_groups_file | grep -v '^#' | grep -v '^$' | + while read head_pattern group_patterns; do + matchlen=$(expr "$1" : "$head_pattern") + if [ "$matchlen" == "${#1}" ]; then + info "Found matching head pattern: '$head_pattern'" + for group_pattern in $group_patterns; do + for groupname in $groups; do + info "Checking group: '$groupname' against pattern: '$group_pattern'" + matchlen=$(expr "$groupname" : "$group_pattern") + if [ "$matchlen" == "${#groupname}" ]; then + grant "Allowing group: '$groupname' with pattern: '$group_pattern'" + fi + done + done + deny "None of the user's groups are in the access list for this branch" + fi + done + ) + case "$rc" in + grant) grant >/dev/null "Granting access based on $allowed_groups_file" ;; + deny) deny >/dev/null "Denying access based on $allowed_groups_file" ;; + *) ;; + esac +fi + +deny >/dev/null "There are no more rules to check. Denying access" + +-- >8 -- end of script -- >8 -- + +This uses two files, $GIT_DIR/info/allowed-users and +allowed-groups, to describe which heads can be pushed into by +whom. The format of each file would look like this: refs/heads/master junio refs/heads/cogito$ pasky @@ -91,15 +165,8 @@ like this in $GIT_DIR/info/allowed-pushers file: refs/tags/v[0-9]* junio With this, Linus can push or create "bw/penguin" or "bw/zebra" -or "bw/panda" branches, Pasky can do only "cogito", and I can do -master branch and make versioned tags. And anybody can do -tmp/blah branches. This assumes all the users are in a single -group that can write into $GIT_DIR/ and underneath. - - - - - - - +or "bw/panda" branches, Pasky can do only "cogito", and JC can +do master branch and make versioned tags. And anybody can do +tmp/blah branches. +------------ diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index eebaf3a..53cc355 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -11,6 +11,6 @@ Use the given merge strategy; can be supplied more than once to specify them in the order they should be tried. If there is no `-s` option, a built-in list of strategies - is used instead (`git-merge-resolve` when merging a single + is used instead (`git-merge-recursive` when merging a single head, `git-merge-octopus` otherwise). diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 3ec56d2..7df0266 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -6,27 +6,27 @@ resolve:: and another branch you pulled from) using 3-way merge algorithm. It tries to carefully detect criss-cross merge ambiguities and is considered generally safe and - fast. This is the default merge strategy when pulling - one branch. + fast. recursive:: This can only resolve two heads using 3-way merge algorithm. When there are more than one common ancestors that can be used for 3-way merge, it creates a - merged tree of the common ancestores and uses that as + merged tree of the common ancestors and uses that as the reference tree for the 3-way merge. This has been reported to result in fewer merge conflicts without causing mis-merges by tests done on actual merge commits taken from Linux 2.6 kernel development history. Additionally this can detect and handle merges involving - renames. + renames. This is the default merge strategy when + pulling or merging one branch. octopus:: This resolves more than two-head case, but refuses to do complex merge that needs manual resolution. It is primarily meant to be used for bundling topic branch heads together. This is the default merge strategy when - pulling more than one branch. + pulling or merging more than one branches. ours:: This resolves any number of heads, but the result of the diff --git a/Documentation/sort_glossary.pl b/Documentation/sort_glossary.pl index babbea0..e57dc78 100644 --- a/Documentation/sort_glossary.pl +++ b/Documentation/sort_glossary.pl @@ -42,7 +42,6 @@ sub no_spaces ($) { print 'GIT Glossary ============ -Aug 2005 This list is sorted alphabetically: diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index cf7ba76..0827056 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -1282,26 +1282,27 @@ fatal: merge program failed `git-merge-one-file` script is called with parameters to describe those three versions, and is responsible to leave the -merge results in the working tree and register it in the index -file. It is a fairly straightforward shell script, and -eventually calls `merge` program from RCS suite to perform the +merge results in the working tree. +It is a fairly straightforward shell script, and +eventually calls `merge` program from RCS suite to perform a file-level 3-way merge. In this case, `merge` detects conflicts, and the merge result with conflict marks is left in -the working tree, while the index file is updated with the -version from the current branch (this is to make `git diff` -useful after this step). This can be seen if you run `ls-files +the working tree.. This can be seen if you run `ls-files --stage` again at this point: ------------ $ git-ls-files --stage 100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example -100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 0 hello +100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello +100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello +100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello ------------ -As you can see, there is no unmerged paths in the index file. This is the state of the index file and the working file after `git merge` returns control back to you, leaving the conflicting -merge for you to resolve. +merge for you to resolve. Notice that the path `hello` is still +unmerged, and what you see with `git diff` at this point is +differences since stage 2 (i.e. your version). Publishing your work @@ -1636,14 +1637,49 @@ fast forward. You need to pull and merge those other changes back before you push your work when it happens. +Advanced Shared Repository Management +------------------------------------- + +Being able to push into a shared repository means being able to +write into it. If your developers are coming over the network, +this means you, as the repository administrator, need to give +each of them an SSH access to the shared repository machine. + +In some cases, though, you may not want to give a normal shell +account to them, but want to restrict them to be able to only +do `git push` into the repository and nothing else. + +You can achieve this by setting the login shell of your +developers on the shared repository host to `git-shell` program. + +[NOTE] +Most likely you would also need to list `git-shell` program in +`/etc/shells` file. + +This restricts the set of commands that can be run from incoming +SSH connection for these users to only `receive-pack` and +`upload-pack`, so the only thing they can do are `git fetch` and +`git push`. + +You still need to create UNIX user accounts for each developer, +and put them in the same group. Make sure that the repository +shared among these developers is writable by that group. + +You can implement finer grained branch policies using update +hooks. There is a document ("control access to branches") in +Documentation/howto by Carl Baldwin and JC outlining how to (1) +limit access to branch per user, (2) forbid overwriting existing +tags. + + Bundling your work together --------------------------- It is likely that you will be working on more than one thing at -a time. It is easy to use those more-or-less independent tasks +a time. It is easy to manage those more-or-less independent tasks using branches with git. -We have already seen how branches work in a previous example, +We have already seen how branches work previously, with "fun and work" example using two branches. The idea is the same if there are more than two branches. Let's say you started out from "master" head, and have some new code in the "master" |