{"thread":{"id":"13407","subject":"[PATCH 1/2] Documentation: improve \"add\", \"pull\" and \"format-patch\" examples","startedAt":"2008-05-07T04:29:28Z","lastAt":"2008-05-07T05:02:19Z","messageCount":2,"participants":["Christian Couder","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"76246","messageId":"20080507062928.45452d1b.chriscool@tuxfamily.org","threadId":"13407","inReplyTo":null,"subject":"[PATCH 1/2] Documentation: improve \"add\", \"pull\" and \"format-patch\" examples","fromName":"Christian Couder","fromEmail":"chriscool@tuxfamily.org","sentAt":"2008-05-07T04:29:28Z","receivedAt":"2008-05-07T04:29:28Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"Before this patch in \"git-add.txt\" and \"git-format-patch.txt\", the\ncommands used in the examples were \"git-CMD\" instead of \"git CMD\".\nThis patch fixes that.\n\nIn \"git-pull.txt\" only the last example had the code sample in an\nasciidoc \"Listing Block\", and in the other two files, none.\nThis patch fixes that by putting all code samples in listing\nblocks.\n\nSigned-off-by: Christian Couder <chriscool@tuxfamily.org>\n---\n Documentation/git-add.txt          |   24 ++++++----\n Documentation/git-format-patch.txt |   67 +++++++++++++++++-----------\n Documentation/git-pull.txt         |   86 ++++++++++++++++++++++--------------\n 3 files changed, 108 insertions(+), 69 deletions(-)\n\n\tThis is a small patch series to improve examples in man pages.\n\tThe 2 patches are both independent from each other and from my\n\tother documentation patch series.\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex 35e67a0..2eabbc8 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -98,21 +98,27 @@ those in info/exclude.  See link:repository-layout.html[repository layout].\n \n EXAMPLES\n --------\n-git-add Documentation/\\\\*.txt::\n \n-\tAdds content from all `\\*.txt` files under `Documentation`\n-\tdirectory and its subdirectories.\n+* Adds content from all `\\*.txt` files under `Documentation` directory\n+and its subdirectories:\n++\n+------------\n+$ git add Documentation/\\\\*.txt\n+------------\n +\n Note that the asterisk `\\*` is quoted from the shell in this\n example; this lets the command to include the files from\n subdirectories of `Documentation/` directory.\n \n-git-add git-*.sh::\n-\n-\tConsiders adding content from all git-*.sh scripts.\n-\tBecause this example lets shell expand the asterisk\n-\t(i.e. you are listing the files explicitly), it does not\n-\tconsider `subdir/git-foo.sh`.\n+* Considers adding content from all git-*.sh scripts:\n++\n+------------\n+$ git add git-*.sh\n+------------\n++\n+Because this example lets shell expand the asterisk (i.e. you are\n+listing the files explicitly), it does not consider\n+`subdir/git-foo.sh`.\n \n Interactive mode\n ----------------\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 2336b3e..ca528f9 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -175,32 +175,47 @@ and file suffix, and number patches when outputting more than one.\n EXAMPLES\n --------\n \n-git-format-patch -k --stdout R1..R2 | git-am -3 -k::\n-\tExtract commits between revisions R1 and R2, and apply\n-\tthem on top of the current branch using `git-am` to\n-\tcherry-pick them.\n-\n-git-format-patch origin::\n-\tExtract all commits which are in the current branch but\n-\tnot in the origin branch.  For each commit a separate file\n-\tis created in the current directory.\n-\n-git-format-patch \\--root origin::\n-\tExtract all commits that lead to 'origin' since the\n-\tinception of the project.\n-\n-git-format-patch -M -B origin::\n-\tThe same as the previous one.  Additionally, it detects\n-\tand handles renames and complete rewrites intelligently to\n-\tproduce a renaming patch.  A renaming patch reduces the\n-\tamount of text output, and generally makes it easier to\n-\treview it.  Note that the \"patch\" program does not\n-\tunderstand renaming patches, so use it only when you know\n-\tthe recipient uses git to apply your patch.\n-\n-git-format-patch -3::\n-\tExtract three topmost commits from the current branch\n-\tand format them as e-mailable patches.\n+* Extract commits between revisions R1 and R2, and apply them on top of\n+the current branch using `git-am` to cherry-pick them:\n++\n+------------\n+$ git format-patch -k --stdout R1..R2 | git-am -3 -k\n+------------\n+\n+* Extract all commits which are in the current branch but not in the\n+origin branch:\n++\n+------------\n+$ git format-patch origin\n+------------\n++\n+For each commit a separate file is created in the current directory.\n+\n+* Extract all commits that lead to 'origin' since the inception of the\n+project:\n++\n+------------\n+$ git format-patch \\--root origin\n+------------\n+\n+* The same as the previous one:\n++\n+------------\n+$ git format-patch -M -B origin\n+------------\n++\n+Additionally, it detects and handles renames and complete rewrites\n+intelligently to produce a renaming patch.  A renaming patch reduces\n+the amount of text output, and generally makes it easier to review it.\n+Note that the \"patch\" program does not understand renaming patches, so\n+use it only when you know the recipient uses git to apply your patch.\n+\n+* Extract three topmost commits from the current branch and format them\n+as e-mailable patches:\n++\n+------------\n+$ git format-patch -3\n+------------\n \n See Also\n --------\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex 3405ca0..66304f0 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -111,40 +111,58 @@ rules apply:\n EXAMPLES\n --------\n \n-git pull, git pull origin::\n-\tUpdate the remote-tracking branches for the repository\n-\tyou cloned from, then merge one of them into your\n-\tcurrent branch.  Normally the branch merged in is\n-\tthe HEAD of the remote repository, but the choice is\n-\tdetermined by the branch.<name>.remote and\n-\tbranch.<name>.merge options; see linkgit:git-config[1]\n-\tfor details.\n-\n-git pull origin next::\n-\tMerge into the current branch the remote branch `next`;\n-\tleaves a copy of `next` temporarily in FETCH_HEAD, but\n-\tdoes not update any remote-tracking branches.\n-\n-git pull . fixes enhancements::\n-\tBundle local branch `fixes` and `enhancements` on top of\n-\tthe current branch, making an Octopus merge.  This `git pull .`\n-\tsyntax is equivalent to `git merge`.\n-\n-git pull -s ours . obsolete::\n-\tMerge local branch `obsolete` into the current branch,\n-\tusing `ours` merge strategy.\n-\n-git pull --no-commit . maint::\n-\tMerge local branch `maint` into the current branch, but\n-\tdo not make a commit automatically.  This can be used\n-\twhen you want to include further changes to the merge,\n-\tor want to write your own merge commit message.\n+* Update the remote-tracking branches for the repository\n+  you cloned from, then merge one of them into your\n+  current branch:\n++\n+------------------------------------------------\n+$ git pull, git pull origin\n+------------------------------------------------\n++\n+Normally the branch merged in is the HEAD of the remote repository,\n+but the choice is determined by the branch.<name>.remote and\n+branch.<name>.merge options; see linkgit:git-config[1] for details.\n+\n+* Merge into the current branch the remote branch `next`:\n++\n+------------------------------------------------\n+$ git pull origin next\n+------------------------------------------------\n++\n+This leaves a copy of `next` temporarily in FETCH_HEAD, but\n+does not update any remote-tracking branches.\n+\n+* Bundle local branch `fixes` and `enhancements` on top of\n+  the current branch, making an Octopus merge:\n++\n+------------------------------------------------\n+$ git pull . fixes enhancements\n+------------------------------------------------\n++\n+This `git pull .` syntax is equivalent to `git merge`.\n+\n+* Merge local branch `obsolete` into the current branch, using `ours`\n+  merge strategy:\n++\n+------------------------------------------------\n+$ git pull -s ours . obsolete\n+------------------------------------------------\n+\n+* Merge local branch `maint` into the current branch, but do not make\n+  a commit automatically:\n++\n+------------------------------------------------\n+$ git pull --no-commit . maint\n+------------------------------------------------\n++\n+This can be used when you want to include further changes to the\n+merge, or want to write your own merge commit message.\n +\n You should refrain from abusing this option to sneak substantial\n changes into a merge commit.  Small fixups like bumping\n release/version name would be acceptable.\n \n-Command line pull of multiple branches from one repository::\n+* Command line pull of multiple branches from one repository:\n +\n ------------------------------------------------\n $ git checkout master\n@@ -152,12 +170,12 @@ $ git fetch origin +pu:pu maint:tmp\n $ git pull . tmp\n ------------------------------------------------\n +\n-This updates (or creates, as necessary) branches `pu` and `tmp`\n-in the local repository by fetching from the branches\n-(respectively) `pu` and `maint` from the remote repository.\n+This updates (or creates, as necessary) branches `pu` and `tmp` in\n+the local repository by fetching from the branches (respectively)\n+`pu` and `maint` from the remote repository.\n +\n-The `pu` branch will be updated even if it is does not\n-fast-forward; the others will not be.\n+The `pu` branch will be updated even if it is does not fast-forward;\n+the others will not be.\n +\n The final command then merges the newly fetched `tmp` into master.\n \n-- \n1.5.5.1.126.g9ca01\n"},{"id":"76248","messageId":"7vskwug10k.fsf@gitster.siamese.dyndns.org","threadId":"13407","inReplyTo":"20080507062928.45452d1b.chriscool@tuxfamily.org","subject":"Re: [PATCH 1/2] Documentation: improve \"add\", \"pull\" and \"format-patch\" examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-05-07T05:02:19Z","receivedAt":"2008-05-07T05:02:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Although I would agree that the listing block enhances readability by\nmaking the example stand out, I am not so fond of making the examples into\na bulletted list.  Will apply, though.\n"}]}