From: Junio C Hamano Date: Wed, 2 May 2012 20:51:45 +0000 (-0700) Subject: Merge branch 'jk/doc-asciidoc-inline-literal' X-Git-Tag: v1.7.11-rc0~73 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/d274fc093cbdcddbf9aff5f79de4e9445f3363d7?hp=-c Merge branch 'jk/doc-asciidoc-inline-literal' Our documentation was written for an ancient version of AsciiDoc, making the source not very readable. By Jeff King * jk/doc-asciidoc-inline-literal: docs: stop using asciidoc no-inline-literal --- d274fc093cbdcddbf9aff5f79de4e9445f3363d7 diff --combined Documentation/Makefile index 9fee0b9261,9ad6a6a300..14286cb657 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@@ -82,7 -82,7 +82,7 @@@ endi # ifndef ASCIIDOC7 - ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal + ASCIIDOC_EXTRA += -a asciidoc7compatible endif ifdef DOCBOOK_XSL_172 ASCIIDOC_EXTRA += -a git-asciidoc-no-roff @@@ -124,16 -124,6 +124,16 @@@ SHELL_PATH ?= $(SHELL # Shell quote; SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) +ifdef DEFAULT_PAGER +DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER)) +ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)' +endif + +ifdef DEFAULT_EDITOR +DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) +ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' +endif + # # Please note that there is a minor bug in asciidoc. # The version after 6.0.3 _will_ include the patch found here: diff --combined Documentation/config.txt index 40a6e8fb89,b7d2757d0b..cb9882d0a8 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@@ -95,9 -95,7 +95,9 @@@ included file is expanded immediately, found at the location of the include directive. If the value of the `include.path` variable is a relative path, the path is considered to be relative to the configuration file in which the include directive was -found. See below for examples. +found. The value of `include.path` is subject to tilde expansion: `{tilde}/` +is expanded to the value of `$HOME`, and `{tilde}user/` to the specified +user's home directory. See below for examples. Example ~~~~~~~ @@@ -124,7 -122,6 +124,7 @@@ [include] path = /path/to/foo.inc ; include by absolute path path = foo ; expand "foo" relative to the current file + path = ~/foo ; expand "foo" in your $HOME directory Variables ~~~~~~~~~ @@@ -141,23 -138,8 +141,23 @@@ advice.*: + -- pushNonFastForward:: - Advice shown when linkgit:git-push[1] refuses - non-fast-forward refs. + Set this variable to 'false' if you want to disable + 'pushNonFFCurrent', 'pushNonFFDefault', and + 'pushNonFFMatching' simultaneously. + pushNonFFCurrent:: + Advice shown when linkgit:git-push[1] fails due to a + non-fast-forward update to the current branch. + pushNonFFDefault:: + Advice to set 'push.default' to 'upstream' or 'current' + when you ran linkgit:git-push[1] and pushed 'matching + refs' by default (i.e. you did not provide an explicit + refspec, and no 'push.default' configuration was set) + and it resulted in a non-fast-forward error. + pushNonFFMatching:: + Advice shown when you ran linkgit:git-push[1] and pushed + 'matching refs' explicitly (i.e. you used ':', or + specified a refspec that isn't your current branch) and + it resulted in a non-fast-forward error. statusHints:: Directions on how to stage/unstage/add shown in the output of linkgit:git-status[1] and the template shown @@@ -481,8 -463,8 +481,8 @@@ Common unit suffixes of 'k', 'm', or 'g core.excludesfile:: In addition to '.gitignore' (per-directory) and '.git/info/exclude', git looks into this file for patterns - of files which are not meant to be tracked. "{tilde}/" is expanded - to the value of `$HOME` and "{tilde}user/" to the specified user's + of files which are not meant to be tracked. "`~/`" is expanded + to the value of `$HOME` and "`~user/`" to the specified user's home directory. See linkgit:gitignore[5]. core.askpass:: @@@ -863,7 -845,7 +863,7 @@@ commit.status: commit.template:: Specify a file to use as the template for new commit messages. - "{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the + "`~/`" is expanded to the value of `$HOME` and "`~user/`" to the specified user's home directory. credential.helper:: @@@ -988,7 -970,7 +988,7 @@@ format.thread: a boolean value, or `shallow` or `deep`. `shallow` threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the - `\--in-reply-to`, and the first patch mail, in this order. + `--in-reply-to`, and the first patch mail, in this order. `deep` threading makes every mail a reply to the previous one. A true boolean value is the same as `shallow`, and a false value disables threading. @@@ -1419,7 -1401,7 +1419,7 @@@ instaweb.port: interactive.singlekey:: In interactive commands, allow the user to provide one-letter input with a single key (i.e., without hitting enter). - Currently this is used by the `\--patch` mode of + Currently this is used by the `--patch` mode of linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1], linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this setting is silently ignored if portable keystroke input @@@ -1427,13 -1409,13 +1427,13 @@@ log.abbrevCommit:: If true, makes linkgit:git-log[1], linkgit:git-show[1], and - linkgit:git-whatchanged[1] assume `\--abbrev-commit`. You may - override this option with `\--no-abbrev-commit`. + linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may + override this option with `--no-abbrev-commit`. log.date:: Set the default date-time mode for the 'log' command. Setting a value for log.date is similar to using 'git log''s - `\--date` option. Possible values are `relative`, `local`, + `--date` option. Possible values are `relative`, `local`, `default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1] for details. @@@ -1623,18 -1605,18 +1623,18 @@@ pack.indexVersion: and this config option ignored whenever the corresponding pack is larger than 2 GB. + - If you have an old git that does not understand the version 2 `{asterisk}.idx` file, + If you have an old git that does not understand the version 2 `*.idx` file, cloning or fetching over a non native protocol (e.g. "http" and "rsync") - that will copy both `{asterisk}.pack` file and corresponding `{asterisk}.idx` file from the + that will copy both `*.pack` file and corresponding `*.idx` file from the other side may give you a repository that cannot be accessed with your - older version of git. If the `{asterisk}.pack` file is smaller than 2 GB, however, + older version of git. If the `*.pack` file is smaller than 2 GB, however, you can use linkgit:git-index-pack[1] on the *.pack file to regenerate - the `{asterisk}.idx` file. + the `*.idx` file. pack.packSizeLimit:: The maximum size of a pack. This setting only affects packing to a file when repacking, i.e. the git:// protocol - is unaffected. It can be overridden by the `\--max-pack-size` + is unaffected. It can be overridden by the `--max-pack-size` option of linkgit:git-repack[1]. The minimum size allowed is limited to 1 MiB. The default is unlimited. Common unit suffixes of 'k', 'm', or 'g' are @@@ -1644,8 -1626,8 +1644,8 @@@ pager.: If the value is boolean, turns on or off pagination of the output of a particular git subcommand when writing to a tty. Otherwise, turns on pagination for the subcommand using the - pager specified by the value of `pager.`. If `\--paginate` - or `\--no-pager` is specified on the command line, it takes + pager specified by the value of `pager.`. If `--paginate` + or `--no-pager` is specified on the command line, it takes precedence over this option. To disable pagination for all commands, set `core.pager` or `GIT_PAGER` to `cat`. @@@ -1653,9 -1635,9 +1653,9 @@@ pretty.: Alias for a --pretty= format string, as specified in linkgit:git-log[1]. Any aliases defined here can be used just as the built-in pretty formats could. For example, - running `git config pretty.changelog "format:{asterisk} %H %s"` + running `git config pretty.changelog "format:* %H %s"` would cause the invocation `git log --pretty=changelog` - to be equivalent to running `git log "--pretty=format:{asterisk} %H %s"`. + to be equivalent to running `git log "--pretty=format:* %H %s"`. Note that an alias with the same name as a built-in format will be silently ignored. @@@ -1683,30 -1665,12 +1683,30 @@@ push.default: line. Possible values are: + * `nothing` - do not push anything. -* `matching` - push all matching branches. - All branches having the same name in both ends are considered to be - matching. This is the default. +* `matching` - push all branches having the same name in both ends. + This is for those who prepare all the branches into a publishable + shape and then push them out with a single command. It is not + appropriate for pushing into a repository shared by multiple users, + since locally stalled branches will attempt a non-fast forward push + if other users updated the branch. + + + This is currently the default, but Git 2.0 will change the default + to `simple`. * `upstream` - push the current branch to its upstream branch. -* `tracking` - deprecated synonym for `upstream`. + With this, `git push` will update the same remote ref as the one which + is merged by `git pull`, making `push` and `pull` symmetrical. + See "branch..merge" for how to configure the upstream branch. +* `simple` - like `upstream`, but refuses to push if the upstream + branch's name is different from the local one. This is the safest + option and is well-suited for beginners. It will become the default + in Git 2.0. * `current` - push the current branch to a branch of the same name. + + + The `simple`, `current` and `upstream` modes are for those who want to + push out a single branch after finishing work, even when the other + branches are not yet ready to be pushed out. If you are working with + other people to push into the same shared repository, you would want + to use one of these. rebase.stat:: Whether to show a diffstat of what changed upstream since the last @@@ -1786,7 -1750,7 +1786,7 @@@ remote..push: remote..mirror:: If true, pushing to this remote will automatically behave - as if the `\--mirror` option was given on the command line. + as if the `--mirror` option was given on the command line. remote..skipDefaultUpdate:: If true, this remote will be skipped by default when updating diff --combined Documentation/git-cherry-pick.txt index 3d25a20b67,06a0bfde8d..9f3dae631e --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@@ -103,25 -103,6 +103,25 @@@ effect to your index in a row cherry-pick'ed commit, then a fast forward to this commit will be performed. +--allow-empty:: + By default, cherry-picking an empty commit will fail, + indicating that an explicit invocation of `git commit + --allow-empty` is required. This option overrides that + behavior, allowing empty commits to be preserved automatically + in a cherry-pick. Note that when "--ff" is in effect, empty + commits that meet the "fast-forward" requirement will be kept + even without this option. Note also, that use of this option only + keeps commits that were initially empty (i.e. the commit recorded the + same tree as its parent). Commits which are made empty due to a + previous commit are dropped. To force the inclusion of those commits + use `--keep-redundant-commits`. + +--keep-redundant-commits:: + If a commit being cherry picked duplicates a commit already in the + current history, it will become empty. By default these + redundant commits are ignored. This option overrides that behavior and + creates an empty commit object. Implies `--allow-empty`. + --strategy=:: Use the given merge strategy. Should only be used once. See the MERGE STRATEGIES section in linkgit:git-merge[1] @@@ -149,7 -130,7 +149,7 @@@ EXAMPLE Apply the changes introduced by all commits that are ancestors of master but not of HEAD to produce new commits. - `git cherry-pick master{tilde}4 master{tilde}2`:: + `git cherry-pick master~4 master~2`:: Apply the changes introduced by the fifth and third last commits pointed to by master and create 2 new commits with @@@ -170,7 -151,7 +170,7 @@@ are in next but not HEAD to the current branch, creating a new commit for each new change. - `git rev-list --reverse master \-- README | git cherry-pick -n --stdin`:: + `git rev-list --reverse master -- README | git cherry-pick -n --stdin`:: Apply the changes introduced by all commits on the master branch that touched README to the working tree and index, diff --combined Documentation/git-fast-import.txt index b52dca5133,45101ca957..2620d28b4b --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@@ -98,10 -98,9 +98,10 @@@ OPTION options. --cat-blob-fd=:: - Specify the file descriptor that will be written to - when the `cat-blob` command is encountered in the stream. - The default behaviour is to write to `stdout`. + Write responses to `cat-blob` and `ls` queries to the + file descriptor instead of `stdout`. Allows `progress` + output intended for the end-user to be separated from other + output. --done:: Require a `done` command at the end of the stream. @@@ -479,9 -478,9 +479,9 @@@ current branch value should be written ---- from refs/heads/branch^0 ---- - The `{caret}0` suffix is necessary as fast-import does not permit a branch to + The `^0` suffix is necessary as fast-import does not permit a branch to start from itself, and the branch is created in memory before the - `from` command is even read from the input. Adding `{caret}0` will force + `from` command is even read from the input. Adding `^0` will force fast-import to resolve the commit through Git's revision parsing library, rather than its internal branch table, thereby loading in the existing value of the branch. @@@ -943,9 -942,6 +943,9 @@@ This command can be used anywhere in th 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. +See ``Responses To Commands'' below for details about how to read +this output safely. + `ls` ~~~~ Prints information about the object at a path to a file descriptor @@@ -979,7 -975,7 +979,7 @@@ Reading from a named tree: See `filemodify` above for a detailed description of ``. - Output uses the same format as `git ls-tree {litdd} `: + Output uses the same format as `git ls-tree -- `: ==== SP ('blob' | 'tree' | 'commit') SP HT LF @@@ -995,9 -991,6 +995,9 @@@ instead repor missing SP LF ==== +See ``Responses To Commands'' below for details about how to read +this output safely. + `feature` ~~~~~~~~~ Require that fast-import supports the specified feature, or abort if @@@ -1086,35 -1079,6 +1086,35 @@@ If the `--done` command line option or in use, the `done` command is mandatory and marks the end of the stream. +Responses To Commands +--------------------- +New objects written by fast-import are not available immediately. +Most fast-import commands have no visible effect until the next +checkpoint (or completion). The frontend can send commands to +fill fast-import's input pipe without worrying about how quickly +they will take effect, which improves performance by simplifying +scheduling. + +For some frontends, though, it is useful to be able to read back +data from the current repository as it is being updated (for +example when the source material describes objects in terms of +patches to be applied to previously imported objects). This can +be accomplished by connecting the frontend and fast-import via +bidirectional pipes: + +==== + mkfifo fast-import-output + frontend fast-import-output +==== + +A frontend set up this way can use `progress`, `ls`, and `cat-blob` +commands to read information from the import in progress. + +To avoid deadlock, such frontends must completely consume any +pending output from `progress`, `ls`, and `cat-blob` before +performing writes to fast-import that might block. + Crash Reports ------------- If fast-import is supplied invalid input it will terminate with a diff --combined Documentation/git-push.txt index a52b7b1a19,620f8b421f..cb97cc1c3b --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@@ -34,7 -34,7 +34,7 @@@ OPTIONS[[OPTIONS] ...:: The format of a parameter is an optional plus - `{plus}`, followed by the source ref , followed + `+`, followed by the source ref , followed by a colon `:`, followed by the destination ref . It is used to specify with what object the ref in the remote repository is to be updated. @@@ -50,7 -50,7 +50,7 @@@ updated + The object referenced by is used to update the reference on the remote side, but by default this is only allowed if the - update can fast-forward . By having the optional leading `{plus}`, + update can fast-forward . By having the optional leading `+`, you can tell git to update the ref even when the update is not a fast-forward. This does *not* attempt to merge into . See EXAMPLES below for details. @@@ -60,7 -60,7 +60,7 @@@ Pushing an empty allows you to delete the ref from the remote repository. + - The special refspec `:` (or `{plus}:` to allow non-fast-forward updates) + The special refspec `:` (or `+:` to allow non-fast-forward updates) directs git to push "matching" branches: for every branch that exists on the local side, the remote side is updated if a branch of the same name already exists on the remote side. This is the default operation mode @@@ -75,7 -75,7 +75,7 @@@ nor in any Push line of the correspondi Remove remote branches that don't have a local counterpart. For example a remote branch `tmp` will be removed if a local branch with the same name doesn't exist any more. This also respects refspecs, e.g. - `git push --prune remote refs/heads/{asterisk}:refs/tmp/{asterisk}` would + `git push --prune remote refs/heads/*:refs/tmp/*` would make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo` doesn't exist. @@@ -170,16 -170,10 +170,16 @@@ useful if you write an alias or script is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. ---recurse-submodules=check:: - Check whether all submodule commits used by the revisions to be - pushed are available on a remote tracking branch. Otherwise the - push will be aborted and the command will exit with non-zero status. +--recurse-submodules=check|on-demand:: + Make sure all submodule commits used by the revisions to be + pushed are available on a remote tracking branch. If 'check' is + used git will verify that all submodule commits that changed in + the revisions to be pushed are available on at least one remote + of the submodule. If any commits are missing the push will be + aborted and exit with non-zero status. If 'on-demand' is used + all submodules that changed in the revisions to be pushed will + be pushed. If on-demand was not able to push all necessary + revisions it will also be aborted and exit with non-zero status. include::urls-remotes.txt[] @@@ -210,7 -204,7 +210,7 @@@ option is used flag:: A single character indicating the status of the ref: (space);; for a successfully pushed fast-forward; - `{plus}`;; for a successful forced update; + `+`;; for a successful forced update; `-`;; for a successfully deleted ref; `*`;; for a successfully pushed new ref; `!`;; for a ref that was rejected or failed to push; and @@@ -220,7 -214,7 +220,7 @@@ summary: For a successfully pushed ref, the summary shows the old and new values of the ref in a form suitable for using as an argument to `git log` (this is `..` in most cases, and - `\...` for forced non-fast-forward updates). + `...` for forced non-fast-forward updates). + For a failed update, more details are given: + @@@ -402,7 -396,7 +402,7 @@@ the ones in the examples below) can be Find a ref that matches `experimental` in the `origin` repository (e.g. `refs/heads/experimental`), and delete it. - `git push origin {plus}dev:master`:: + `git push origin +dev:master`:: Update the origin repository's master branch with the dev branch, allowing non-fast-forward updates. *This can leave unreferenced commits dangling in the origin repository.* Consider the diff --combined Documentation/git-rebase.txt index 841ebd6a9f,b0e13e5bf4..147fa1a8e0 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@@ -238,10 -238,6 +238,10 @@@ leave out at most one of A and B, in wh will be reset to where it was when the rebase operation was started. +--keep-empty:: + Keep the commits that do not change anything from its + parents in the result. + --skip:: Restart the rebasing process by skipping the current patch. @@@ -271,7 -267,7 +271,7 @@@ which makes little sense -X :: --strategy-option=:: Pass the through to the merge strategy. - This implies `\--merge` and, if no strategy has been + This implies `--merge` and, if no strategy has been specified, `-s recursive`. Note the reversal of 'ours' and 'theirs' as noted in above for the `-m` option. @@@ -615,8 -611,8 +615,8 @@@ Easy case: The changes are literally th Hard case: The changes are not the same.:: This happens if the 'subsystem' rebase had conflicts, or used - `\--interactive` to omit, edit, squash, or fixup commits; or - if the upstream used one of `commit \--amend`, `reset`, or + `--interactive` to omit, edit, squash, or fixup commits; or + if the upstream used one of `commit --amend`, `reset`, or `filter-branch`. @@@ -652,7 -648,7 +652,7 @@@ correspond to the ones before the rebas NOTE: While an "easy case recovery" sometimes appears to be successful even in the hard case, it may have unintended consequences. For example, a commit that was removed via `git rebase - \--interactive` will be **resurrected**! + --interactive` will be **resurrected**! The idea is to manually tell 'git rebase' "where the old 'subsystem' ended and your 'topic' began", that is, what the old merge-base @@@ -660,7 -656,7 +660,7 @@@ between them was. You will have to fin of the old 'subsystem', for example: * With the 'subsystem' reflog: after 'git fetch', the old tip of - 'subsystem' is at `subsystem@\{1}`. Subsequent fetches will + 'subsystem' is at `subsystem@{1}`. Subsequent fetches will increase the number. (See linkgit:git-reflog[1].) * Relative to the tip of 'topic': knowing that your 'topic' has three diff --combined Documentation/gitweb.conf.txt index 4b8d1b1d4c,1cea8cb65e..b9dd56753a --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@@ -499,13 -499,6 +499,13 @@@ $maxload: Set `$maxload` to undefined value (`undef`) to turn this feature off. The default value is 300. +$omit_age_column:: + If true, omit the column with date of the most current commit on the + projects list page. It can save a bit of I/O and a fork per repository. + +$omit_owner:: + If true prevents displaying information about repository owner. + $per_request_config:: If this is set to code reference, it will be run once for each request. You can set parts of configuration that change per session this way. @@@ -756,14 -749,14 +756,14 @@@ Project specific override is not suppor forks:: If this feature is enabled, gitweb considers projects in subdirectories of project root (basename) to be forks of existing - projects. For each project `$projname.git`, projects in the - `$projname/` directory and its subdirectories will not be - shown in the main projects list. Instead, a \'+' mark is shown - next to `$projname`, which links to a "forks" view that lists all - the forks (all projects in `$projname/` subdirectory). Additionally + projects. For each project +$projname.git+, projects in the + +$projname/+ directory and its subdirectories will not be + shown in the main projects list. Instead, a \'\+' mark is shown + next to +$projname+, which links to a "forks" view that lists all + the forks (all projects in +$projname/+ subdirectory). Additionally a "forks" view for a project is linked from project summary page. + - If the project list is taken from a file (`$projects_list` points to a + If the project list is taken from a file (+$projects_list+ points to a file), forks are only recognized if they are listed after the main project in that file. +