{"thread":{"id":"3254","subject":"[PATCH 1/3] Docs: split up pull-fetch-param.txt","startedAt":"2006-02-07T03:22:44Z","lastAt":"2006-02-07T03:22:44Z","messageCount":1,"participants":["J. Bruce Fields"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"15658","messageId":"1139282428.ec02f402.0@fieldses.org","threadId":"3254","inReplyTo":null,"subject":"[PATCH 1/3] Docs: split up pull-fetch-param.txt","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-02-07T03:22:44Z","receivedAt":"2006-02-07T03:22:44Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"The push and pull man pages include a bunch of shared text from\npull-fetch-param.txt.  This simplifies maintenance somewhat, but\nthere's actually quite a bit of text that applies only to one or the\nother.\n\nSo, separate out the push- and pull/fetch-specific text into\npull-fetch-param.txt and git-push.txt, then include the largest chunk\nof common stuff (the description of protocols and url's) from\nurls.txt.  That cuts some irrelevant stuff from the man pages without\nmaking us duplicate too much.\n\nSigned-off-by: J. Bruce Fields <bfields@citi.umich.edu>\n\n---\n\n Documentation/git-push.txt         |   27 +++++++++++\n Documentation/pull-fetch-param.txt |   86 +++---------------------------------\n Documentation/urls.txt             |   62 ++++++++++++++++++++++++++\n 3 files changed, 94 insertions(+), 81 deletions(-)\n create mode 100644 Documentation/urls.txt\n\nbe7ed0ba1dc97ad215f0785095930902597ca886\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex a0ef61d..7e9452e 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -23,7 +23,32 @@ documentation for gitlink:git-receive-pa\n \n OPTIONS\n -------\n-include::pull-fetch-param.txt[]\n+<repository>::\n+\tThe \"remote\" repository that is destination of a push operation.\n+include::urls.txt[]\n+\n+<refspec>::\n+\tThe canonical format of a <refspec> parameter is\n+\t`+?<src>:<dst>`; that is, an optional plus `+`, followed\n+\tby the source ref, followed by a colon `:`, followed by\n+\tthe destination ref.\n++\n+The <src> side can be an\n+arbitrary \"SHA1 expression\" that can be used as an\n+argument to `git-cat-file -t`.  E.g. `master~4` (push\n+four parents before the current master head).\n++\n+The local ref that matches <src> is used\n+to fast forward the remote ref that matches <dst>.  If\n+the optional plus `+` is used, the remote ref is updated\n+even if it does not result in a fast forward update.\n++\n+Some short-cut notations are also supported.\n++\n+* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.\n+* A parameter <ref> without a colon is equivalent to\n+  <ref>`:`<ref>, hence updates <ref> in the destination from <ref>\n+  in the source.\n \n \\--all::\n \tInstead of naming each ref to push, specifies all refs\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex 4524fee..9011ffb 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -1,68 +1,7 @@\n <repository>::\n \tThe \"remote\" repository that is the source of a fetch\n-\tor pull operation, or the destination of a push operation.\n-\tOne of the following notations can be used\n-\tto name the remote repository:\n-+\n-===============================================================\n-- rsync://host.xz/path/to/repo.git/\n-- http://host.xz/path/to/repo.git/\n-- https://host.xz/path/to/repo.git/\n-- git://host.xz/path/to/repo.git/\n-- git://host.xz/~user/path/to/repo.git/\n-- ssh://host.xz/path/to/repo.git/\n-- ssh://host.xz/~user/path/to/repo.git/\n-- ssh://host.xz/~/path/to/repo.git\n-===============================================================\n-+\n-SSH Is the default transport protocol and also supports an\n-scp-like syntax.  Both syntaxes support username expansion,\n-as does the native git protocol. The following three are\n-identical to the last three above, respectively:\n-+\n-===============================================================\n-- host.xz:/path/to/repo.git/\n-- host.xz:~user/path/to/repo.git/\n-- host.xz:path/to/repo.git\n-===============================================================\n-+\n-To sync with a local directory, use:\n-+\n-===============================================================\n-- /path/to/repo.git/\n-===============================================================\n-+\n-In addition to the above, as a short-hand, the name of a\n-file in `$GIT_DIR/remotes` directory can be given; the\n-named file should be in the following format:\n-+\n-\tURL: one of the above URL format\n-\tPush: <refspec>\n-\tPull: <refspec>\n-+\n-When such a short-hand is specified in place of\n-<repository> without <refspec> parameters on the command\n-line, <refspec> specified on `Push:` lines or `Pull:`\n-lines are used for `git-push` and `git-fetch`/`git-pull`,\n-respectively.  Multiple `Push:` and and `Pull:` lines may\n-be specified for additional branch mappings.\n-+\n-The name of a file in `$GIT_DIR/branches` directory can be\n-specified as an older notation short-hand; the named\n-file should contain a single line, a URL in one of the\n-above formats, optionally followed by a hash `#` and the\n-name of remote head (URL fragment notation).\n-`$GIT_DIR/branches/<remote>` file that stores a <url>\n-without the fragment is equivalent to have this in the\n-corresponding file in the `$GIT_DIR/remotes/` directory.\n-+\n-\tURL: <url>\n-\tPull: refs/heads/master:<remote>\n-+\n-while having `<url>#<head>` is equivalent to\n-+\n-\tURL: <url>\n-\tPull: refs/heads/<head>:<remote>\n+\tor pull operation.\n+include::urls.txt[]\n \n <refspec>::\n \tThe canonical format of a <refspec> parameter is\n@@ -70,17 +9,7 @@ while having `<url>#<head>` is equivalen\n \tby the source ref, followed by a colon `:`, followed by\n \tthe destination ref.\n +\n-When used in `git-push`, the <src> side can be an\n-arbitrary \"SHA1 expression\" that can be used as an\n-argument to `git-cat-file -t`.  E.g. `master~4` (push\n-four parents before the current master head).\n-+\n-For `git-push`, the local ref that matches <src> is used\n-to fast forward the remote ref that matches <dst>.  If\n-the optional plus `+` is used, the remote ref is updated\n-even if it does not result in a fast forward update.\n-+\n-For `git-fetch` and `git-pull`, the remote ref that matches <src>\n+The remote ref that matches <src>\n is fetched, and if <dst> is not empty string, the local\n ref that matches it is fast forwarded using <src>.\n Again, if the optional plus `+` is used, the local ref\n@@ -135,10 +64,7 @@ is often useful.\n Some short-cut notations are also supported.\n +\n * `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`; \n-  used with pull or fetch, it requests fetching everything up to\n-  the given tag.\n+  it requests fetching everything up to the given tag.\n * A parameter <ref> without a colon is equivalent to\n-  <ref>: when pulling/fetching, and <ref>`:`<ref> when\n-  pushing.  That is, do not store it locally if\n-  fetching, and update the same name if pushing.\n-\n+  <ref>: when pulling/fetching, so it merges <ref> into the current\n+  branch without storing the remote branch anywhere locally\ndiff --git a/Documentation/urls.txt b/Documentation/urls.txt\nnew file mode 100644\nindex 0000000..e027c71\n--- /dev/null\n+++ b/Documentation/urls.txt\n@@ -0,0 +1,62 @@\n+One of the following notations can be used\n+to name the remote repository:\n++\n+===============================================================\n+- rsync://host.xz/path/to/repo.git/\n+- http://host.xz/path/to/repo.git/\n+- https://host.xz/path/to/repo.git/\n+- git://host.xz/path/to/repo.git/\n+- git://host.xz/~user/path/to/repo.git/\n+- ssh://host.xz/path/to/repo.git/\n+- ssh://host.xz/~user/path/to/repo.git/\n+- ssh://host.xz/~/path/to/repo.git\n+===============================================================\n++\n+SSH Is the default transport protocol and also supports an\n+scp-like syntax.  Both syntaxes support username expansion,\n+as does the native git protocol. The following three are\n+identical to the last three above, respectively:\n++\n+===============================================================\n+- host.xz:/path/to/repo.git/\n+- host.xz:~user/path/to/repo.git/\n+- host.xz:path/to/repo.git\n+===============================================================\n++\n+To sync with a local directory, use:\n++\n+===============================================================\n+- /path/to/repo.git/\n+===============================================================\n++\n+In addition to the above, as a short-hand, the name of a\n+file in `$GIT_DIR/remotes` directory can be given; the\n+named file should be in the following format:\n++\n+\tURL: one of the above URL format\n+\tPush: <refspec>\n+\tPull: <refspec>\n++\n+When such a short-hand is specified in place of\n+<repository> without <refspec> parameters on the command\n+line, <refspec> specified on `Push:` lines or `Pull:`\n+lines are used for `git-push` and `git-fetch`/`git-pull`,\n+respectively.  Multiple `Push:` and and `Pull:` lines may\n+be specified for additional branch mappings.\n++\n+The name of a file in `$GIT_DIR/branches` directory can be\n+specified as an older notation short-hand; the named\n+file should contain a single line, a URL in one of the\n+above formats, optionally followed by a hash `#` and the\n+name of remote head (URL fragment notation).\n+`$GIT_DIR/branches/<remote>` file that stores a <url>\n+without the fragment is equivalent to have this in the\n+corresponding file in the `$GIT_DIR/remotes/` directory.\n++\n+\tURL: <url>\n+\tPull: refs/heads/master:<remote>\n++\n+while having `<url>#<head>` is equivalent to\n++\n+\tURL: <url>\n+\tPull: refs/heads/<head>:<remote>\n-- \n0.99.8b.g3480-dirty\n"}]}