diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/SubmittingPatches | 30 | ||||
| -rw-r--r-- | Documentation/git-commit.txt | 19 | ||||
| -rw-r--r-- | Documentation/git-ls-files.txt | 12 | ||||
| -rw-r--r-- | Documentation/git-pack-objects.txt | 21 | ||||
| -rw-r--r-- | Documentation/git-rebase.txt | 44 | ||||
| -rw-r--r-- | Documentation/git-repack.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-rev-parse.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-send-email.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-svnimport.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-tag.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-update-index.txt | 78 |
11 files changed, 205 insertions, 35 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-commit.txt b/Documentation/git-commit.txt index 5b1b4d3780..214ed235c5 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -85,27 +85,12 @@ OPTIONS <file>...:: Files to be committed. The meaning of these is different between `--include` and `--only`. Without - either, it defaults `--include` semantics. + either, it defaults `--only` semantics. If you make a commit and then found a mistake immediately after that, you can recover from it with gitlink:git-reset[1]. -WARNING -------- - -The 1.2.0 and its maintenance series 1.2.X will keep the -traditional `--include` semantics as the default when neither -`--only` nor `--include` is specified and `paths...` are given. -This *will* change during the development towards 1.3.0 in the -'master' branch of `git.git` repository. If you are using this -command in your scripts, and you depend on the traditional -`--include` semantics, please update them to explicitly ask for -`--include` semantics. Also if you are used to making partial -commit using `--include` semantics, please train your fingers to -say `git commit --include paths...` (or `git commit -i paths...`). - - Discussion ---------- @@ -121,7 +106,7 @@ even the command is invoked from a subdirectory. That is, update the specified paths to the index and then commit the whole tree. -`git commit --only paths...` largely bypasses the index file and +`git commit paths...` largely bypasses the index file and commits only the changes made to the specified paths. It has however several safety valves to prevent confusion. diff --git a/Documentation/git-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-pack-objects.txt b/Documentation/git-pack-objects.txt index 2d67d3911e..4cb2e83faa 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -8,7 +8,10 @@ git-pack-objects - Create a packed archive of objects. SYNOPSIS -------- -'git-pack-objects' [--non-empty] [--local] [--incremental] [--window=N] [--depth=N] {--stdout | base-name} < object-list +[verse] +'git-pack-objects' [-q] [--no-reuse-delta] [--non-empty] + [--local] [--incremental] [--window=N] [--depth=N] + {--stdout | base-name} < object-list DESCRIPTION @@ -32,6 +35,10 @@ Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) enables git to read from such an archive. +In a packed archive, an object is either stored as a compressed +whole, or as a difference from some other object. The latter is +often called a delta. + OPTIONS ------- @@ -74,6 +81,18 @@ base-name:: Only create a packed archive if it would contain at least one object. +-q:: + This flag makes the command not to report its progress + on the standard error stream. + +--no-reuse-delta:: + When creating a packed archive in a repository that + has existing packs, the command reuses existing deltas. + This sometimes results in a slightly suboptimal pack. + This flag tells the command not to reuse existing deltas + but compute them from scratch. + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> 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-repack.txt b/Documentation/git-repack.txt index 9060fe8897..6c0f792dad 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -9,7 +9,7 @@ objects into pack files. SYNOPSIS -------- -'git-repack' [-a] [-d] [-l] [-n] +'git-repack' [-a] [-d] [-f] [-l] [-n] [-q] DESCRIPTION ----------- @@ -43,6 +43,14 @@ OPTIONS Pass the `--local` option to `git pack-objects`, see gitlink:git-pack-objects[1]. +-f:: + Pass the `--no-reuse-delta` option to `git pack-objects`, see + gitlink:git-pack-objects[1]. + +-q:: + Pass the `-q` option to `git pack-objects`, see + gitlink:git-pack-objects[1]. + -n:: Do not update the server information with `git update-server-info`. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 1662e06561..29b578978a 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -80,7 +80,7 @@ OPTIONS --git-dir:: Show `$GIT_DIR` if defined else show the path to the .git directory. ---short, short=number:: +--short, --short=number:: Instead of outputting the full SHA1 values of object names try to abbriviate them to a shorter unique name. When no length is specified 7 is used. The minimum length is 4. diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 00537d8907..8c58685e28 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -24,6 +24,9 @@ OPTIONS ------- The options available are: +--cc:: + Specify a starting "Cc:" value for each email. + --chain-reply-to, --no-chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with "--no-chain-reply-to", all emails after @@ -48,6 +51,9 @@ The options available are: Only necessary if --compose is also set. If --compose is not set, this will be prompted for. +--no-signed-off-by-cc:: + Do not add emails foudn in Signed-off-by: lines to the cc list. + --quiet:: Make git-send-email less verbose. One line per email should be all that is output. @@ -61,6 +67,10 @@ The options available are: Only necessary if --compose is also set. If --compose is not set, this will be prompted for. +--suppress-from:: + Do not add the From: address to the cc: list, if it shows up in a From: + line. + --to:: Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt index 63e28b89d5..5c543d5d1b 100644 --- a/Documentation/git-svnimport.txt +++ b/Documentation/git-svnimport.txt @@ -61,6 +61,10 @@ When importing incrementally, you might need to edit the .git/svn2git file. the git repository. Use this option if you want to import into a different branch. +-r:: + Prepend 'rX: ' to commit messages, where X is the imported + subversion revision. + -m:: Attempt to detect merges based on the commit message. This option will enable default regexes that try to capture the name source diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index e8892bb0b0..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 -------- |