diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/SubmittingPatches | 30 | ||||
| -rw-r--r-- | Documentation/git-add.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-cvsserver.txt | 89 | ||||
| -rw-r--r-- | Documentation/git-ls-files.txt | 12 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-rebase.txt | 44 | ||||
| -rw-r--r-- | Documentation/git-rev-parse.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-rm.txt | 89 | ||||
| -rw-r--r-- | Documentation/git-tag.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-update-index.txt | 78 |
10 files changed, 357 insertions, 16 deletions
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/git-add.txt b/Documentation/git-add.txt index 89e461402e..7e293834d1 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -7,7 +7,7 @@ git-add - Add files to the index file. SYNOPSIS -------- -'git-add' [-n] [-v] <file>... +'git-add' [-n] [-v] [--] <file>... DESCRIPTION ----------- @@ -26,6 +26,11 @@ OPTIONS -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 ---------- diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt new file mode 100644 index 0000000000..88f07ff15d --- /dev/null +++ b/Documentation/git-cvsserver.txt @@ -0,0 +1,89 @@ +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 gitcvs only works over ssh connections. + + +INSTALLATION +------------ +1. Put server.pl somewhere useful on the same machine that is hosting your git repos + +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 + logfile=/path/to/logfile + + n.b. you need to ensure each user that is going to invoke server.pl has + write access to the log file. + +5. On each 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. + CVS_SERVER should be set to the server.pl script that has been put on the + remote machine. + +6. Clients should now be able to check out modules (where modules are the names + of branches in git). + $ cvs co -d mylocaldir master + +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-ls-files.txt b/Documentation/git-ls-files.txt index fe5341295c..e813f84202 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -8,12 +8,14 @@ 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>] + [--error-unmatch] [--full-name] [--] [<file>]\* DESCRIPTION @@ -72,6 +74,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,6 +88,10 @@ 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 diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 5b891105b2..6f4a48a109 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -43,6 +43,12 @@ to fast forward the remote ref that matches <dst>. If the optional plus `+` is used, the remote ref is updated even if it does not result in a fast forward update. + +Note: If no explicit refspec is found, (that is neither +on the command line nor in any Push line of the +corresponding remotes file---see below), then all the +refs that exist both on the local side and on the remote +side are updated. ++ Some short-cut notations are also supported. + * `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 16c158f439..f037d1280e 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -7,14 +7,54 @@ 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 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 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 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. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index d638bfc202..29b578978a 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -77,6 +77,14 @@ OPTIONS path of the top-level directory relative to the current directory (typically a sequence of "../", or an empty string). +--git-dir:: + Show `$GIT_DIR` if defined else show the path to the .git directory. + +--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. + --since=datestring, --after=datestring:: Parses the date string, and outputs corresponding --max-age= parameter for git-rev-list command. diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt new file mode 100644 index 0000000000..401bfb2d9c --- /dev/null +++ b/Documentation/git-rm.txt @@ -0,0 +1,89 @@ +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`. + + +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-tag.txt b/Documentation/git-tag.txt index e8892bb0b0..e1c76c600d 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -8,11 +8,13 @@ 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-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 -------- |