diff options
Diffstat (limited to 'Documentation')
27 files changed, 445 insertions, 85 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index ba2006d892..fe1c1e5bc2 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -152,7 +152,7 @@ Writing Documentation: when writing or modifying command usage strings and synopsis sections in the manual pages: - Placeholders are enclosed in angle brackets: + Placeholders are spelled in lowercase and enclosed in angle brackets: <file> --sort=<key> --abbrev[=<n>] diff --git a/Documentation/RelNotes/1.7.4.1.txt b/Documentation/RelNotes/1.7.4.1.txt new file mode 100644 index 0000000000..79923a6d2f --- /dev/null +++ b/Documentation/RelNotes/1.7.4.1.txt @@ -0,0 +1,27 @@ +Git v1.7.4.1 Release Notes +========================== + +Fixes since v1.7.4 +------------------ + + * On Windows platform, the codepath to spawn a new child process forgot + to first flush the output buffer. + + * "git bundle" did not use OFS_DELTA encoding, making its output a few + per-cent larger than necessarily. + + * The option to tell "git clone" to recurse into the submodules was + misspelled with an underscore "--recurse_submodules". + + * "git diff --cached HEAD" before the first commit does what an end user + would expect (namely, show what would be committed without further "git + add"). + + * "git fast-import" didn't accept the command to ask for "notes" feature + to be present in its input stream, even though it was capable of the + feature. + + * "git fsck" gave up scanning loose object files in directories with + garbage files. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.5.txt b/Documentation/RelNotes/1.7.5.txt new file mode 100644 index 0000000000..56c3863f04 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.txt @@ -0,0 +1,56 @@ +Git v1.7.5 Release Notes (draft) +======================== + +Updates since v1.7.4 +-------------------- + + * Various MinGW portability fixes. + + * Various git-p4 enhancements (in contrib). + + * "git config" used to be also known as "git repo-config", but the old + name is now officially deprecated. + + * "git checkout --detach <commit>" is a more user friendly synonym for + "git checkout <commit>^0". + + * "git cherry-pick" and "git revert" can be told to use custom merge + strategy, similar to "git rebase". + + * "rev-list --objects $revs -- $pathspec" would limit the objects listed + in its output properly with the pathspec, in preparation for narrow + clones. + + * "git log" family of commands now understand globbing pathspecs. You + can say "git log -- '*.txt'" for example. + + * "git rerere" learned a new subcommand "remaining", that is similar to + "status" that lists the paths that had conflicts that are known to + rerere, but excludes the paths that have already been marked as + resolved in the index from its output. "git mergetool" has been + updated to use this facility. + + * A possible value to the "push.default" configuration variable, + 'tracking', gained a synonym that more naturally describes what it + does, 'upstream'. + +Also contains various documentation updates. + + +Fixes since v1.7.4 +------------------ + +All of the fixes in the v1.7.4.X maintenance series are included in this +release, unless otherwise noted. + + * "git merge" triggers prepare-commit-msg hook. Earlier, only "git + commit" to conclude an interrupted merge triggered the hook, leading to + an inconsistent overall user experience (js/maint-merge-use-prepare-commit-msg-hook). + + +--- +exec >/var/tmp/1 +O=v1.7.4 +O=v1.7.4.1-140-g8978166 +echo O=$(git describe 'master') +git shortlog --no-merges ^maint ^$O master diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 72741ebda1..c3b0816ed7 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,10 +10,18 @@ Checklist (and a short version for the impatient): description (50 characters is the soft limit, see DISCUSSION in git-commit(1)), and should skip the full stop - the body should provide a meaningful commit message, which: - - uses the imperative, present tense: "change", - not "changed" or "changes". - - includes motivation for the change, and contrasts - its implementation with previous behaviour + . explains the problem the change tries to solve, iow, what + is wrong with the current code without the change. + . justifies the way the change solves the problem, iow, why + the result with the change is better. + . alternate solutions considered but discarded, if any. + - describe changes in imperative mood, e.g. "make xyzzy do frotz" + instead of "[This patch] makes xyzzy do frotz" or "[I] changed + xyzzy to do frotz", as if you are giving orders to the codebase + to change its behaviour. + - try to make sure your explanation can be understood without + external resources. Instead of giving a URL to a mailing list + archive, summarize the relevant points of the discussion. - add a "Signed-off-by: Your Name <you@example.com>" line to the commit message (or just use the option "-s" when committing) to confirm that you agree to the Developer's Certificate of Origin @@ -90,7 +98,10 @@ your commit head. Instead, always make a commit with complete commit message and generate a series of patches from your repository. It is a good discipline. -Describe the technical detail of the change(s). +Give an explanation for the change(s) that is detailed enough so +that people can judge if it is good thing to do, without reading +the actual patch text to determine how well the code does what +the explanation promises to do. 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. @@ -99,9 +110,8 @@ help reviewers check the patch, and future maintainers understand the code, are the most beautiful patches. Descriptions that summarise the point in the subject well, and describe the motivation for the change, the approach taken by the change, and if relevant how this -differs substantially from the prior version, can be found on Usenet -archives back into the late 80's. Consider it like good Netiquette, -but for code. +differs substantially from the prior version, are all good things +to have. Oh, another thing. I am picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped diff --git a/Documentation/config.txt b/Documentation/config.txt index c5e183516a..c995a1a47b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1591,7 +1591,8 @@ push.default:: * `matching` - push all matching branches. All branches having the same name in both ends are considered to be matching. This is the default. -* `tracking` - push the current branch to its upstream branch. +* `upstream` - push the current branch to its upstream branch. +* `tracking` - deprecated synonym for `upstream`. * `current` - push the current branch to a branch of the same name. rebase.stat:: diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 3ac2beac62..c57460c03d 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -74,10 +74,13 @@ separate lines indicate the old and the new mode. combined diff format -------------------- -"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or -'--cc' option to produce 'combined diff'. For showing a merge commit -with "git log -p", this is the default format; you can force showing -full diff with the '-m' option. +Any diff-generating command can take the `-c` or `--cc` option to +produce a 'combined diff' when showing a merge. This is the default +format when showing merges with linkgit:git-diff[1] or +linkgit:git-show[1]. Note also that you can give the `-m' option to any +of these commands to force generation of diffs with individual parents +of a merge. + A 'combined diff' format looks like this: ------------ diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 695696da1b..f37276e5ad 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -64,13 +64,11 @@ ifndef::git-pull[] downloaded. The default behavior for a remote may be specified with the remote.<name>.tagopt setting. See linkgit:git-config[1]. -endif::git-pull[] --[no-]recurse-submodules:: This option controls if new commits of all populated submodules should be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]). -ifndef::git-pull[] --submodule-prefix=<path>:: Prepend <path> to paths printed in informative messages such as "Fetching submodule foo". This option is used diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 881652f490..2dcfc097d3 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -22,7 +22,7 @@ DESCRIPTION ----------- Reads the supplied diff output (i.e. "a patch") and applies it to files. With the `--index` option the patch is also applied to the index, and -with the `--cache` option the patch is only applied to the index. +with the `--cached` option the patch is only applied to the index. Without these options, the command applies the patch only to files, and does not require them to be in a git repository. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 880763d391..396f4cc15b 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -9,6 +9,7 @@ SYNOPSIS -------- [verse] 'git checkout' [-q] [-f] [-m] [<branch>] +'git checkout' [-q] [-f] [-m] [--detach] [<commit>] 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... 'git checkout' --patch [<tree-ish>] [--] [<paths>...] @@ -22,9 +23,10 @@ branch. 'git checkout' [<branch>]:: 'git checkout' -b|-B <new_branch> [<start point>]:: +'git checkout' [--detach] [<commit>]:: This form switches branches by updating the index, working - tree, and HEAD to reflect the specified branch. + tree, and HEAD to reflect the specified branch or commit. + If `-b` is given, a new branch is created as if linkgit:git-branch[1] were called and then checked out; in this case you can @@ -115,6 +117,13 @@ explicitly give a name with '-b' in such a case. Create the new branch's reflog; see linkgit:git-branch[1] for details. +--detach:: + Rather than checking out a branch to work on it, check out a + commit for inspection and discardable experiments. + This is the default behavior of "git checkout <commit>" when + <commit> is not a branch name. See the "DETACHED HEAD" section + below for details. + --orphan:: Create a new 'orphan' branch, named <new_branch>, started from <start_point> and switch to it. The first commit made on this @@ -204,42 +213,140 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. -Detached HEAD +DETACHED HEAD ------------- +HEAD normally refers to a named branch (e.g. 'master'). Meanwhile, each +branch refers to a specific commit. Let's look at a repo with three +commits, one of them tagged, and with branch 'master' checked out: + +------------ + HEAD (refers to branch 'master') + | + v +a---b---c branch 'master' (refers to commit 'c') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ -It is sometimes useful to be able to 'checkout' a commit that is -not at the tip of one of your branches. The most obvious -example is to check out the commit at a tagged official release -point, like this: +When a commit is created in this state, the branch is updated to refer to +the new commit. Specifically, 'git commit' creates a new commit 'd', whose +parent is commit 'c', and then updates branch 'master' to refer to new +commit 'd'. HEAD still refers to branch 'master' and so indirectly now refers +to commit 'd': ------------ -$ git checkout v2.6.18 +$ edit; git add; git commit + + HEAD (refers to branch 'master') + | + v +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') ------------ -Earlier versions of git did not allow this and asked you to -create a temporary branch using the `-b` option, but starting from -version 1.5.0, the above command 'detaches' your HEAD from the -current branch and directly points at the commit named by the tag -(`v2.6.18` in the example above). +It is sometimes useful to be able to checkout a commit that is not at +the tip of any named branch, or even to create a new commit that is not +referenced by a named branch. Let's look at what happens when we +checkout commit 'b' (here we show two ways this may be done): -You can use all git commands while in this state. You can use -`git reset --hard $othercommit` to further move around, for -example. You can make changes and create a new commit on top of -a detached HEAD. You can even create a merge by using `git -merge $othercommit`. +------------ +$ git checkout v2.0 # or +$ git checkout master^^ + + HEAD (refers to commit 'b') + | + v +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ -The state you are in while your HEAD is detached is not recorded -by any branch (which is natural --- you are not on any branch). -What this means is that you can discard your temporary commits -and merges by switching back to an existing branch (e.g. `git -checkout master`), and a later `git prune` or `git gc` would -garbage-collect them. If you did this by mistake, you can ask -the reflog for HEAD where you were, e.g. +Notice that regardless of which checkout command we use, HEAD now refers +directly to commit 'b'. This is known as being in detached HEAD state. +It means simply that HEAD refers to a specific commit, as opposed to +referring to a named branch. Let's see what happens when we create a commit: ------------ -$ git log -g -2 HEAD +$ edit; git add; git commit + + HEAD (refers to commit 'e') + | + v + e + / +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ + +There is now a new commit 'e', but it is referenced only by HEAD. We can +of course add yet another commit in this state: + +------------ +$ edit; git add; git commit + + HEAD (refers to commit 'f') + | + v + e---f + / +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ + +In fact, we can perform all the normal git operations. But, let's look +at what happens when we then checkout master: + +------------ +$ git checkout master + + HEAD (refers to branch 'master') + e---f | + / v +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') ------------ +It is important to realize that at this point nothing refers to commit +'f'. Eventually commit 'f' (and by extension commit 'e') will be deleted +by the routine git garbage collection process, unless we create a reference +before that happens. If we have not yet moved away from commit 'f', +any of these will create a reference to it: + +------------ +$ git checkout -b foo <1> +$ git branch foo <2> +$ git tag foo <3> +------------ + +<1> creates a new branch 'foo', which refers to commit 'f', and then +updates HEAD to refer to branch 'foo'. In other words, we'll no longer +be in detached HEAD state after this command. + +<2> similarly creates a new branch 'foo', which refers to commit 'f', +but leaves HEAD detached. + +<3> creates a new tag 'foo', which refers to commit 'f', +leaving HEAD detached. + +If we have moved away from commit 'f', then we must first recover its object +name (typically by using git reflog), and then we can create a reference to +it. For example, to see the last two commits to which HEAD referred, we +can use either of these commands: + +------------ +$ git reflog -2 HEAD # or +$ git log -g -2 HEAD +------------ EXAMPLES -------- diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index cd848664ce..5d85daa5fe 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -98,6 +98,16 @@ effect to your index in a row. cherry-pick'ed commit, then a fast forward to this commit will be performed. +--strategy=<strategy>:: + Use the given merge strategy. Should only be used once. + See the MERGE STRATEGIES section in linkgit:git-merge[1] + for details. + +-X<option>:: +--strategy-option=<option>:: + Pass the merge strategy-specific option through to the + merge strategy. See linkgit:git-merge[1] for details. + EXAMPLES -------- git cherry-pick master:: @@ -139,6 +149,28 @@ git rev-list --reverse master \-- README | git cherry-pick -n --stdin:: so the result can be inspected and made into a single new commit if suitable. +The following sequence attempts to backport a patch, bails out because +the code the patch applies to has changed too much, and then tries +again, this time exercising more care about matching up context lines. + +------------ +$ git cherry-pick topic^ <1> +$ git diff <2> +$ git reset --merge ORIG_HEAD <3> +$ git cherry-pick -Xpatience topic^ <4> +------------ +<1> apply the change that would be shown by `git show topic^`. +In this example, the patch does not apply cleanly, so +information about the conflict is written to the index and +working tree and no new commit results. +<2> summarize changes to be reconciled +<3> cancel the cherry-pick. In other words, return to the +pre-cherry-pick state, preserving any local modifications you had in +the working tree. +<4> try to apply the change introduced by `topic^` again, +spending extra time to avoid mistakes based on incorrectly matching +context lines. + Author ------ Written by Junio C Hamano <gitster@pobox.com> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index fd6a1f7e25..411fa68e9d 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -215,10 +215,11 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) -u[<mode>]:: --untracked-files[=<mode>]:: - Show untracked files (Default: 'all'). + Show untracked files. + -The mode parameter is optional, and is used to specify -the handling of untracked files. +The mode parameter is optional (defaults to 'all'), and is used to +specify the handling of untracked files; when -u is not used, the +default is 'normal', i.e. show untracked files and directories. + The possible options are: + @@ -226,9 +227,8 @@ The possible options are: - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. + -See linkgit:git-config[1] for configuration variable -used to change the default for when the option is not -specified. +The default can be changed using the status.showUntrackedFiles +configuration variable documented in linkgit:git-config[1]. -v:: --verbose:: diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index f6ac847507..49105102db 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -38,6 +38,8 @@ directories. This behavior can be forced by --no-index. commit relative to the named <commit>. Typically you would want comparison with the latest commit, so if you do not give <commit>, it defaults to HEAD. + If HEAD does not exist (e.g. unborned branches) and + <commit> is not given, it shows all staged changes. --staged is a synonym of --cached. 'git diff' [--options] <commit> [--] [<path>...]:: diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 4415e63635..e1b7a0f9ec 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -78,6 +78,10 @@ OPTIONS set of marks. If a mark is defined to different values, the last file wins. +--import-marks-if-exists=<file>:: + Like --import-marks but instead of erroring out, silently + skips the file if it does not exist. + --relative-marks:: After specifying --relative-marks= the paths specified with --import-marks= and --export-marks= are relative @@ -192,7 +196,8 @@ especially when a higher level language such as Perl, Python or Ruby is being used. fast-import is very strict about its input. Where we say SP below we mean -*exactly* one space. Likewise LF means one (and only one) linefeed. +*exactly* one space. Likewise LF means one (and only one) linefeed +and HT one (and only one) horizontal tab. Supplying additional whitespace characters will cause unexpected results, such as branch names or file names with leading or trailing spaces in their name, or early termination of fast-import when it encounters @@ -330,6 +335,11 @@ and control the current import process. More detailed discussion format to the file descriptor set with `--cat-blob-fd` or `stdout` if unspecified. +`ls`:: + Causes fast-import to print a line describing a directory + entry in 'ls-tree' format to the file descriptor set with + `--cat-blob-fd` or `stdout` if unspecified. + `feature`:: Require that fast-import supports the specified feature, or abort if it does not. @@ -915,6 +925,55 @@ This command can be used anywhere in the stream that comments are accepted. In particular, the `cat-blob` command can be used in the middle of a commit but not in the middle of a `data` command. +`ls` +~~~~ +Prints information about the object at a path to a file descriptor +previously arranged with the `--cat-blob-fd` argument. This allows +printing a blob from the active commit (with `cat-blob`) or copying a +blob or tree from a previous commit for use in the current one (with +`filemodify`). + +The `ls` command can be used anywhere in the stream that comments are +accepted, including the middle of a commit. + +Reading from the active commit:: + This form can only be used in the middle of a `commit`. + The path names a directory entry within fast-import's + active commit. The path must be quoted in this case. ++ +.... + 'ls' SP <path> LF +.... + +Reading from a named tree:: + The `<dataref>` can be a mark reference (`:<idnum>`) or the + full 40-byte SHA-1 of a Git tag, commit, or tree object, + preexisting or waiting to be written. + The path is relative to the top level of the tree + named by `<dataref>`. ++ +.... + 'ls' SP <dataref> SP <path> LF +.... + +See `filemodify` above for a detailed description of `<path>`. + +Output uses the same format as `git ls-tree <tree> {litdd} <path>`: + +==== + <mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF +==== + +The <dataref> represents the blob, tree, or commit object at <path> +and can be used in later 'cat-blob', 'filemodify', or 'ls' commands. + +If there is no file or subtree at that path, 'git fast-import' will +instead report + +==== + missing SP <path> LF +==== + `feature` ~~~~~~~~~ Require that fast-import supports the specified feature, or abort if @@ -942,12 +1001,21 @@ import-marks:: any "feature import-marks" command in the stream. cat-blob:: - Ignored. Versions of fast-import not supporting the - "cat-blob" command will exit with a message indicating so. +ls:: + Require that the backend support the 'cat-blob' or 'ls' command. + Versions of fast-import not supporting the specified command + will exit with a message indicating so. This lets the import error out early with a clear message, rather than wasting time on the early part of an import before the unsupported command is detected. +notes:: + Require that the backend support the 'notemodify' (N) + subcommand to the 'commit' command. + Versions of fast-import not supporting notes will exit + with a message indicating so. + + `option` ~~~~~~~~ Processes the specified option so that git fast-import behaves in a diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index fac1cf55e5..152e695c81 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -123,7 +123,7 @@ EXAMPLES -------- An example directly producing formatted text. Show the most recent -3 tagged commits:: +3 tagged commits: ------------ #!/bin/sh @@ -140,7 +140,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, -demonstrating the use of --shell. List the prefixes of all heads:: +demonstrating the use of --shell. List the prefixes of all heads: ------------ #!/bin/sh @@ -154,7 +154,7 @@ done A bit more elaborate report on tags, demonstrating that the format -may be an entire script:: +may be an entire script: ------------ #!/bin/sh @@ -204,3 +204,15 @@ eval=`git for-each-ref --shell --format="$fmt" \ refs/tags` eval "$eval" ------------ + +Author +------ +Written by Junio C Hamano <gitster@pobox.com>. + +Documentation +------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index abe7bf9ff9..3422765827 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git ls-remote' [--heads] [--tags] [-u <exec> | --upload-pack <exec>] - <repository> <refs>... + <repository> [<refs>...] DESCRIPTION ----------- diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 30466917da..b33e6be872 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -84,6 +84,15 @@ must be given before the options meant for 'git fetch'. --verbose:: Pass --verbose to git-fetch and git-merge. +--[no-]recurse-submodules:: + This option controls if new commits of all populated submodules should + be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]). + That might be necessary to get the data needed for merging submodule + commits, a feature git learned in 1.7.3. Notice that the result of a + merge will not be checked out in the submodule, "git submodule update" + has to be called afterwards to bring the work tree up to date with the + merge result. + Options related to merging ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 2d65cfefd5..68263a6a53 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -7,17 +7,17 @@ git-remote-ext - Bridge smart transport to external command. SYNOPSIS -------- -git remote add nick "ext::<command>[ <arguments>...]" +git remote add <nick> "ext::<command>[ <arguments>...]" DESCRIPTION ----------- -This remote helper uses the specified 'program' to connect +This remote helper uses the specified '<command>' to connect to a remote git server. -Data written to stdin of this specified 'program' is assumed +Data written to stdin of the specified '<command>' is assumed to be sent to a git:// server, git-upload-pack, git-receive-pack or git-upload-archive (depending on situation), and data read -from stdout of this program is assumed to be received from +from stdout of <command> is assumed to be received from the same service. Command and arguments are separated by an unescaped space. @@ -40,7 +40,7 @@ The following sequences have a special meaning: git wants to invoke. '%G' (must be the first characters in an argument):: - This argument will not be passed to 'program'. Instead, it + This argument will not be passed to '<command>'. Instead, it will cause the helper to start by sending git:// service requests to the remote side with the service field set to an appropriate value and the repository field set to rest of the argument. Default is not to send @@ -50,7 +50,7 @@ This is useful if remote side is git:// server accessed over some tunnel. '%V' (must be first characters in argument):: - This argument will not be passed to 'program'. Instead it sets + This argument will not be passed to '<command>'. Instead it sets the vhost field in the git:// service request (to rest of the argument). Default is not to send vhost in such request (if sent). @@ -76,7 +76,7 @@ EXAMPLES: --------- This remote helper is transparently used by git when you use commands such as "git fetch <URL>", "git clone <URL>", -, "git push <URL>" or "git remote add nick <URL>", where <URL> +, "git push <URL>" or "git remote add <nick> <URL>", where <URL> begins with `ext::`. Examples: "ext::ssh -i /home/foo/.ssh/somekey user@host.example %S 'foo/repo'":: diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 3a23477ce7..51de895822 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -201,12 +201,12 @@ REF LIST ATTRIBUTES OPTIONS ------- -'option verbosity' <N>:: +'option verbosity' <n>:: Changes the verbosity of messages displayed by the helper. - A value of 0 for N means that processes operate + A value of 0 for <n> means that processes operate quietly, and the helper produces only error output. 1 is the default level of verbosity, and higher values - of N correspond to the number of -v flags passed on the + of <n> correspond to the number of -v flags passed on the command line. 'option progress' \{'true'|'false'\}:: diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 752fc88e76..45be851750 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -80,6 +80,16 @@ effect to your index in a row. --signoff:: Add Signed-off-by line at the end of the commit message. +--strategy=<strategy>:: + Use the given merge strategy. Should only be used once. + See the MERGE STRATEGIES section in linkgit:git-merge[1] + for details. + +-X<option>:: +--strategy-option=<option>:: + Pass the merge strategy-specific option through to the + merge strategy. See linkgit:git-merge[1] for details. + EXAMPLES -------- git revert HEAD~3:: diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index dae190a5f2..5102a23f8e 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -38,20 +38,20 @@ OPTIONS -u[<mode>]:: --untracked-files[=<mode>]:: - Show untracked files (Default: 'all'). + Show untracked files. + -The mode parameter is optional, and is used to specify -the handling of untracked files. The possible options are: +The mode parameter is optional (defaults to 'all'), and is used to +specify the handling of untracked files; when -u is not used, the +default is 'normal', i.e. show untracked files and directories. ++ +The possible options are: + --- - 'no' - Show no untracked files - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. --- + -See linkgit:git-config[1] for configuration variable -used to change the default for when the option is not -specified. +The default can be changed using the status.showUntrackedFiles +configuration variable documented in linkgit:git-config[1]. --ignore-submodules[=<when>]:: Ignore changes to submodules when looking for changes. <when> can be diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 0ade2ce54e..e161a40a73 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -66,7 +66,7 @@ COMMANDS Set the 'rewriteRoot' option in the [svn-remote] config. --rewrite-uuid=<UUID>;; Set the 'rewriteUUID' option in the [svn-remote] config. ---username=<USER>;; +--username=<user>;; For transports that SVN handles authentication for (http, https, and plain svn), specify the username. For other transports (eg svn+ssh://), you must include the username in @@ -443,8 +443,8 @@ OPTIONS Only used with the 'init' command. These are passed directly to 'git init'. --r <ARG>:: ---revision <ARG>:: +-r <arg>:: +--revision <arg>:: Used with the 'fetch' command. + This allows revision ranges for partial/cauterized history diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 8b169e364a..65f76c5440 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -18,21 +18,22 @@ SYNOPSIS DESCRIPTION ----------- -Adds a tag reference in `.git/refs/tags/`. +Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given +to delete, list or verify tags. -Unless `-f` is given, the tag must not yet exist in +Unless `-f` is given, the tag to be created must not yet exist in the `.git/refs/tags/` directory. If one of `-a`, `-s`, or `-u <key-id>` is passed, the command -creates a 'tag' object, and requires the tag message. Unless +creates a 'tag' object, and requires a tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied. -Otherwise just the SHA1 object name of the commit object is -written (i.e. a lightweight tag). +Otherwise just a tag reference for the SHA1 object name of the commit object is +created (i.e. a lightweight tag). A GnuPG signed tag object will be created when `-s` or `-u <key-id>` is used. When `-u <key-id>` is not used, the diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 916a38aa99..0f848de8b2 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|--verbose] [--] <pack>.idx ... +'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ... DESCRIPTION diff --git a/Documentation/git.txt b/Documentation/git.txt index e968ed4aa0..0c32d45248 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,9 +44,10 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.7.4/git.html[documentation for release 1.7.4] +* link:v1.7.4.1/git.html[documentation for release 1.7.4.1] * release notes for + link:RelNotes/1.7.4.1.txt[1.7.4.1], link:RelNotes/1.7.4.txt[1.7.4]. * link:v1.7.3.5/git.html[documentation for release 1.7.3.5] diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index f04b48ef0d..33716a31d0 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -273,6 +273,29 @@ This commit is referred to as a "merge commit", or sometimes just a <<def_pack,pack>>, to assist in efficiently accessing the contents of a pack. +[[def_pathspec]]pathspec:: + Pattern used to specify paths. ++ +Pathspecs are used on the command line of "git ls-files", "git +ls-tree", "git grep", "git checkout", and many other commands to +limit the scope of operations to some subset of the tree or +worktree. See the documentation of each command for whether +paths are relative to the current directory or toplevel. The +pathspec syntax is as follows: + +* any path matches itself +* the pathspec up to the last slash represents a + directory prefix. The scope of that pathspec is + limited to that subtree. +* the rest of the pathspec is a pattern for the remainder + of the pathname. Paths relative to the directory + prefix will be matched against that pattern using fnmatch(3); + in particular, '*' and '?' _can_ match directory separators. ++ +For example, Documentation/*.jpg will match all .jpg files +in the Documentation subtree, +including Documentation/chapter_1/figure_1.jpg. + [[def_parent]]parent:: A <<def_commit_object,commit object>> contains a (possibly empty) list of the logical predecessor(s) in the line of development, i.e. its diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt index 0953a50b69..2933056120 100644 --- a/Documentation/howto/using-merge-subtree.txt +++ b/Documentation/howto/using-merge-subtree.txt @@ -71,5 +71,5 @@ Additional tips relevant parts of your tree. - Please note that if the other project merges from you, then it will - connects its history to yours, which can be something they don't want + connect its history to yours, which can be something they don't want to. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 44a2ef1de1..9c47ad885b 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -165,7 +165,7 @@ limiting may be applied. -n 'number':: --max-count=<number>:: - Limit the number of commits output. + Limit the number of commits to output. --skip=<number>:: |