diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/SubmittingPatches | 30 | ||||
| -rw-r--r-- | Documentation/diff-options.txt | 11 | ||||
| -rw-r--r-- | Documentation/git-commit.txt | 17 | ||||
| -rw-r--r-- | Documentation/git-ls-files.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-rebase.txt | 44 | ||||
| -rw-r--r-- | Documentation/git-repo-config.txt | 18 | ||||
| -rw-r--r-- | Documentation/git-rev-parse.txt | 8 | ||||
| -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/howto/separating-topic-branches.txt | 91 |
11 files changed, 223 insertions, 27 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/diff-options.txt b/Documentation/diff-options.txt index 5c85167ff2..2a0275eeda 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -35,6 +35,17 @@ -C:: Detect copies as well as renames. +--diff-filter=[ACDMRTUXB*]:: + Select only files that are Added (`A`), Copied (`C`), + Deleted (`D`), Modified (`M`), Renamed (`R`), have their + type (mode) changed (`T`), are Unmerged (`U`), are + Unknown (`X`), or have had their pairing Broken (`B`). + Any combination of the filter characters may be used. + When `*` (All-or-none) is added to the combination, all + paths are selected if there is any file that matches + other criteria in the comparison; if there is no file + that matches other criteria, nothing is selected. + --find-copies-harder:: For performance reasons, by default, -C option finds copies only if the original file of the copy was modified in the same diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 53b64fa595..214ed235c5 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,8 +8,8 @@ git-commit - Record your changes SYNOPSIS -------- [verse] -'git-commit' [-a] [-i] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>] - [-e] [--author <author>] [--] <file>... +'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>] + [-e] [--author <author>] [--] [[-i | -o ]<file>...] DESCRIPTION ----------- @@ -73,15 +73,20 @@ OPTIONS commit the whole index. This is the traditional behaviour. ---:: - Do not interpret any more arguments as options. - -<file>...:: +-o|--only:: Commit only the files specified on the command line. This format cannot be used during a merge, nor when the index and the latest commit does not match on the specified paths to avoid confusion. +--:: + Do not interpret any more arguments as options. + +<file>...:: + Files to be committed. The meaning of these is + different between `--include` and `--only`. Without + 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]. diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index e5a92f47dd..e813f84202 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -15,6 +15,7 @@ SYNOPSIS [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] + [--error-unmatch] [--full-name] [--] [<file>]\* DESCRIPTION @@ -73,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: @@ -81,7 +86,7 @@ OPTIONS R:: removed/deleted C:: modified/changed K:: to be killed - ? other + ?:: other -v:: Similar to `-t`, but use lowercase letters for files 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-repo-config.txt b/Documentation/git-repo-config.txt index 306946412f..33fcde452a 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -8,12 +8,12 @@ git-repo-config - Get and set options in .git/config. SYNOPSIS -------- -'git-repo-config' name [value [value_regex]] -'git-repo-config' --replace-all name [value [value_regex]] -'git-repo-config' --get name [value_regex] -'git-repo-config' --get-all name [value_regex] -'git-repo-config' --unset name [value_regex] -'git-repo-config' --unset-all name [value_regex] +'git-repo-config' [type] name [value [value_regex]] +'git-repo-config' [type] --replace-all name [value [value_regex]] +'git-repo-config' [type] --get name [value_regex] +'git-repo-config' [type] --get-all name [value_regex] +'git-repo-config' [type] --unset name [value_regex] +'git-repo-config' [type] --unset-all name [value_regex] DESCRIPTION ----------- @@ -26,6 +26,12 @@ should provide a POSIX regex for the value. If you want to handle the lines *not* matching the regex, just prepend a single exclamation mark in front (see EXAMPLES). +The type specifier can be either '--int' or '--bool', which will make +'git-repo-config' ensure that the variable(s) are of the given type and +convert the value to the canonical form (simple decimal number for int, +a "true" or "false" string for bool). If no type specifier is passed, +no checks or transformations are performed on the value. + This command will fail if . .git/config is invalid, 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-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/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt new file mode 100644 index 0000000000..090e2c9b01 --- /dev/null +++ b/Documentation/howto/separating-topic-branches.txt @@ -0,0 +1,91 @@ +From: Junio C Hamano <junkio@cox.net> +Subject: Separating topic branches +Abstract: In this article, JC describes how to separate topic branches. + +This text was originally a footnote to a discussion about the +behaviour of the git diff commands. + +Often I find myself doing that [running diff against something other +than HEAD] while rewriting messy development history. For example, I +start doing some work without knowing exactly where it leads, and end +up with a history like this: + + "master" + o---o + \ "topic" + o---o---o---o---o---o + +At this point, "topic" contains something I know I want, but it +contains two concepts that turned out to be completely independent. +And often, one topic component is larger than the other. It may +contain more than two topics. + +In order to rewrite this mess to be more manageable, I would first do +"diff master..topic", to extract the changes into a single patch, start +picking pieces from it to get logically self-contained units, and +start building on top of "master": + + $ git diff master..topic >P.diff + $ git checkout -b topicA master + ... pick and apply pieces from P.diff to build + ... commits on topicA branch. + + o---o---o + / "topicA" + o---o"master" + \ "topic" + o---o---o---o---o---o + +Before doing each commit on "topicA" HEAD, I run "diff HEAD" +before update-index the affected paths, or "diff --cached HEAD" +after. Also I would run "diff --cached master" to make sure +that the changes are only the ones related to "topicA". Usually +I do this for smaller topics first. + +After that, I'd do the remainder of the original "topic", but +for that, I do not start from the patchfile I extracted by +comparing "master" and "topic" I used initially. Still on +"topicA", I extract "diff topic", and use it to rebuild the +other topic: + + $ git diff -R topic >P.diff ;# --cached also would work fine + $ git checkout -b topicB master + ... pick and apply pieces from P.diff to build + ... commits on topicB branch. + + "topicB" + o---o---o---o---o + / + /o---o---o + |/ "topicA" + o---o"master" + \ "topic" + o---o---o---o---o---o + +After I am done, I'd try a pretend-merge between "topicA" and +"topicB" in order to make sure I have not missed anything: + + $ git pull . topicA ;# merge it into current "topicB" + $ git diff topic + "topicB" + o---o---o---o---o---* (pretend merge) + / / + /o---o---o----------' + |/ "topicA" + o---o"master" + \ "topic" + o---o---o---o---o---o + +The last diff better not to show anything other than cleanups +for crufts. Then I can finally clean things up: + + $ git branch -D topic + $ git reset --hard HEAD^ ;# nuke pretend merge + + "topicB" + o---o---o---o---o + / + /o---o---o + |/ "topicA" + o---o"master" + |