{"thread":{"id":"28014","subject":"git-archive's wrong documentation: really write pax rather than tar","startedAt":"2011-08-03T22:17:59Z","lastAt":"2011-08-04T22:51:09Z","messageCount":9,"participants":["Hin-Tak Leung","Jeff King","Junio C Hamano","René Scharfe"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"172823","messageId":"1312409879.97173.YahooMailClassic@web29501.mail.ird.yahoo.com","threadId":"28014","inReplyTo":null,"subject":"git-archive's wrong documentation: really write pax rather than tar","fromName":"Hin-Tak Leung","fromEmail":"htl10@users.sourceforge.net","sentAt":"2011-08-03T22:17:59Z","receivedAt":"2011-08-03T22:17:59Z","isPatch":false,"sender":{"key":"htl10@users.sourceforge.net","avatar":null},"body":"Had a bit of discussion on R-devel a few months ago, and now that I am doing something similiar again I decided to write and report this issue:\n\nhttp://r.789695.n4.nabble.com/quot-R-CMD-check-quot-accepts-but-quot-R-CMD-INSTALL-quot-rejects-a-tar-ball-td3420479.html\n\nThe summary of the problem is that, git-archive's \"--format=tar\" option really write the pax format most of the time, and some cross-platform archive extraction library (rather than the all-powerful GNU tar) really does not think that's the tar format and bail out.\n\nIs it possible to (1) add a warning in the man-page, or (2) actually fix the problem in git-archive ( archive-tar.c ) to generate more conformant archive packages?\n\nThanks. BTW, git (and git archive) is a great tool!\n"},{"id":"172834","messageId":"20110804014143.GA32579@sigill.intra.peff.net","threadId":"28014","inReplyTo":"1312409879.97173.YahooMailClassic@web29501.mail.ird.yahoo.com","subject":"Re: git-archive's wrong documentation: really write pax rather than tar","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-08-04T01:41:43Z","receivedAt":"2011-08-04T01:41:43Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 03, 2011 at 11:17:59PM +0100, Hin-Tak Leung wrote:\n\n> The summary of the problem is that, git-archive's \"--format=tar\"\n> option really write the pax format most of the time, and some\n> cross-platform archive extraction library (rather than the\n> all-powerful GNU tar) really does not think that's the tar format and\n> bail out.\n\nOut of curiosity, what is the library? Putting pax headers into ustar\nformat has been standardized in POSIX since 2001.\n\n> Is it possible to (1) add a warning in the man-page, or (2) actually\n> fix the problem in git-archive ( archive-tar.c ) to generate more\n> conformant archive packages?\n\nThat header contains useful information (the commit id from which the\narchive was generated). And there is a way to turn it off: give a tree\nid instead of a commit id. There is an example in the git-archive\nmanpage that does exactly this already. Look for the example mentioning\n\"pax header\" here:\n\n http://www.kernel.org/pub/software/scm/git/docs/git-archive.html\n\nIt might be a bit more obvious to find if we actually had a\n--no-pax-header option, though.\n\n-Peff\n"},{"id":"172837","messageId":"7v62me6ism.fsf@alter.siamese.dyndns.org","threadId":"28014","inReplyTo":"20110804014143.GA32579@sigill.intra.peff.net","subject":"Re: git-archive's wrong documentation: really write pax rather than tar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-08-04T01:56:41Z","receivedAt":"2011-08-04T01:56:41Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> It might be a bit more obvious to find if we actually had a\n> --no-pax-header option, though.\n\nYeah, we would need to make sure that --no-pack-header causes a barf\nfor other backends, though. \"struct archiver_args\" right now seems to have\ncompression_level but I think it should just have \"const char **\" that is\ninterpreted by backends.\n"},{"id":"172838","messageId":"20110804020054.GA1947@sigill.intra.peff.net","threadId":"28014","inReplyTo":"7v62me6ism.fsf@alter.siamese.dyndns.org","subject":"Re: git-archive's wrong documentation: really write pax rather than tar","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-08-04T02:00:54Z","receivedAt":"2011-08-04T02:00:54Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 03, 2011 at 06:56:41PM -0700, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > It might be a bit more obvious to find if we actually had a\n> > --no-pax-header option, though.\n> \n> Yeah, we would need to make sure that --no-pack-header causes a barf\n> for other backends, though. \"struct archiver_args\" right now seems to have\n> compression_level but I think it should just have \"const char **\" that is\n> interpreted by backends.\n\nActually, it is relevant for zip, too. The option should really be\ncalled \"--no-commit-id\" or something similar. I don't think it's as big\na deal with zip (because there is no compatibility issue), but you may\nwant to omit the header for other reasons (e.g., because you know it\ndoesn't point to a commit that is public).\n\n-Peff\n"},{"id":"172841","messageId":"20110804021329.GB32579@sigill.intra.peff.net","threadId":"28014","inReplyTo":"20110804014143.GA32579@sigill.intra.peff.net","subject":"Re: git-archive's wrong documentation: really write pax rather than tar","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-08-04T02:13:29Z","receivedAt":"2011-08-04T02:13:29Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 03, 2011 at 07:41:43PM -0600, Jeff King wrote:\n\n> Look for the example mentioning \"pax header\" here:\n> \n> http://www.kernel.org/pub/software/scm/git/docs/git-archive.html\n\nBTW, I noticed while looking at this that the HTML versions of the\nexamples are quite hard to read, as they are formatted in a\nproportional-width font. I never noticed because I always just read the\nroff-formatted manpages in a monospaced-terminal. We should probably do\nthis:\n\n-- >8 --\nSubject: docs: put listed example commands in backticks\n\nMany examples of git command invocation are given in asciidoc listing\nblocks, which makes them monospaced and avoids further interpretation of\nspecial characters. Some manpages make a list of examples, like:\n\n git foo::\n Run git foo.\n\n git foo -q::\n Use the \"-q\" option.\n\nto quickly show many variants. However, they can sometimes be hard to\nread, because they are shown in a proportional-width font (so, for\nexample, seeing the difference between \"-- foo\" and \"--foo\" can be\ndifficult).\n\nThis patch puts all such examples into backticks, which gives the\nequivalent formatting to a listing block (i.e., monospaced and without\ncharacter interpretation).\n\nAs a bonus, this also fixes an example in the git-push manpage, in which\n\"git push origin :::\" was accidentally considered a newly-indented list,\nand not a list item with \"git push origin :\" in it.\n\nSigned-off-by: Jeff King \n---\nI found all of these with:\n\n git grep :: Documentation/*.txt | grep 'git '\n\nand then marked up only the examples by hand. Most of the other matches\nwere fine as-is (i.e., they weren't meant to be code examples). There\nwas one common type of hit that I didn't convert, but maybe could be,\nthough. Some of the commands with multiple modes of operation (e.g.,\ncheckout, diff) use lists like:\n\n 'git diff' [--options] -- []::\n ...\n 'git diff' [--options] --cached [] [--] [...]::\n\netc. Those could arguably be monospaced, as well.\n\nI suspect we could replace some invocations of {carat} and other\npunctuation inside the newly-backticked text, but it doesn't hurt to\nleave it as-is. And I'm paranoid that even if it works on my setup, some\nother version of asciidoc will mangle it.\n\n Documentation/git-archive.txt | 16 ++++++++--------\n Documentation/git-cherry-pick.txt | 14 +++++++-------\n Documentation/git-grep.txt | 6 +++---\n Documentation/git-gui.txt | 16 ++++++++--------\n Documentation/git-log.txt | 16 ++++++++--------\n Documentation/git-merge-file.txt | 4 ++--\n Documentation/git-push.txt | 20 ++++++++++----------\n Documentation/git-remote-fd.txt | 8 ++++----\n Documentation/git-revert.txt | 4 ++--\n Documentation/git-rm.txt | 4 ++--\n Documentation/git-show.txt | 10 +++++-----\n Documentation/git-tar-tree.txt | 10 +++++-----\n Documentation/git-whatchanged.txt | 4 ++--\n 13 files changed, 66 insertions(+), 66 deletions(-)\n\ndiff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\nindex 1320c87..ac7006e 100644\n--- a/Documentation/git-archive.txt\n+++ b/Documentation/git-archive.txt\n@@ -142,41 +142,41 @@ while archiving any tree in your `$GIT_DIR/info/attributes` file.\n \n EXAMPLES\n --------\n-git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)::\n+`git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)`::\n \n \tCreate a tar archive that contains the contents of the\n \tlatest commit on the current branch, and extract it in the\n \t`/var/tmp/junk` directory.\n \n-git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz::\n+`git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz`::\n \n \tCreate a compressed tarball for v1.4.0 release.\n \n-git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz::\n+`git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz`::\n \n \tSame as above, but using the builtin tar.gz handling.\n \n-git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0::\n+`git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0`::\n \n \tSame as above, but the format is inferred from the output file.\n \n-git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\\{tree\\} | gzip >git-1.4.0.tar.gz::\n+`git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\\{tree\\} | gzip >git-1.4.0.tar.gz`::\n \n \tCreate a compressed tarball for v1.4.0 release, but without a\n \tglobal extended pax header.\n \n-git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip::\n+`git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip`::\n \n \tPut everything in the current head's Documentation/ directory\n \tinto 'git-1.4.0-docs.zip', with the prefix 'git-docs/'.\n \n-git archive -o latest.zip HEAD::\n+`git archive -o latest.zip HEAD`::\n \n \tCreate a Zip archive that contains the contents of the latest\n \tcommit on the current branch. Note that the output format is\n \tinferred by the extension of the output file.\n \n-git config tar.tar.xz.command \"xz -c\"::\n+`git config tar.tar.xz.command \"xz -c\"`::\n \n \tConfigure a \"tar.xz\" format for making LZMA-compressed tarfiles.\n \tYou can use it specifying `--format=tar.xz`, or by creating an\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 6c9c2cb..7cfa3d9 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -112,31 +112,31 @@ effect to your index in a row.\n \n EXAMPLES\n --------\n-git cherry-pick master::\n+`git cherry-pick master`::\n \n \tApply the change introduced by the commit at the tip of the\n \tmaster branch and create a new commit with this change.\n \n-git cherry-pick ..master::\n-git cherry-pick ^HEAD master::\n+`git cherry-pick ..master`::\n+`git cherry-pick ^HEAD master`::\n \n \tApply the changes introduced by all commits that are ancestors\n \tof master but not of HEAD to produce new commits.\n \n-git cherry-pick master{tilde}4 master{tilde}2::\n+`git cherry-pick master{tilde}4 master{tilde}2`::\n \n \tApply the changes introduced by the fifth and third last\n \tcommits pointed to by master and create 2 new commits with\n \tthese changes.\n \n-git cherry-pick -n master~1 next::\n+`git cherry-pick -n master~1 next`::\n \n \tApply to the working tree and the index the changes introduced\n \tby the second last commit pointed to by master and by the last\n \tcommit pointed to by next, but do not create any commit with\n \tthese changes.\n \n-git cherry-pick --ff ..next::\n+`git cherry-pick --ff ..next`::\n \n \tIf history is linear and HEAD is an ancestor of next, update\n \tthe working tree and advance the HEAD pointer to match next.\n@@ -144,7 +144,7 @@ git cherry-pick --ff ..next::\n \tare in next but not HEAD to the current branch, creating a new\n \tcommit for each new change.\n \n-git rev-list --reverse master \\-- README | git cherry-pick -n --stdin::\n+`git rev-list --reverse master \\-- README | git cherry-pick -n --stdin`::\n \n \tApply the changes introduced by all commits on the master\n \tbranch that touched README to the working tree and index,\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 07b3c6a..0627111 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -215,15 +215,15 @@ OPTIONS\n Examples\n --------\n \n-git grep {apostrophe}time_t{apostrophe} \\-- {apostrophe}*.[ch]{apostrophe}::\n+`git grep {apostrophe}time_t{apostrophe} \\-- {apostrophe}*.[ch]{apostrophe}`::\n \tLooks for `time_t` in all tracked .c and .h files in the working\n \tdirectory and its subdirectories.\n \n-git grep -e {apostrophe}#define{apostrophe} --and \\( -e MAX_PATH -e PATH_MAX \\)::\n+`git grep -e {apostrophe}#define{apostrophe} --and \\( -e MAX_PATH -e PATH_MAX \\)`::\n \tLooks for a line that has `#define` and either `MAX_PATH` or\n \t`PATH_MAX`.\n \n-git grep --all-match -e NODE -e Unexpected::\n+`git grep --all-match -e NODE -e Unexpected`::\n \tLooks for a line that has `NODE` or `Unexpected` in\n \tfiles that have lines that match both.\n \ndiff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt\nindex 18f713b..0041994 100644\n--- a/Documentation/git-gui.txt\n+++ b/Documentation/git-gui.txt\n@@ -50,7 +50,7 @@ version::\n \n Examples\n --------\n-git gui blame Makefile::\n+`git gui blame Makefile`::\n \n \tShow the contents of the file 'Makefile' in the current\n \tworking directory, and provide annotations for both the\n@@ -59,41 +59,41 @@ git gui blame Makefile::\n \tuncommitted changes (if any) are explicitly attributed to\n \t'Not Yet Committed'.\n \n-git gui blame v0.99.8 Makefile::\n+`git gui blame v0.99.8 Makefile`::\n \n \tShow the contents of 'Makefile' in revision 'v0.99.8'\n \tand provide annotations for each line. Unlike the above\n \texample the file is read from the object database and not\n \tthe working directory.\n \n-git gui blame --line=100 Makefile::\n+`git gui blame --line=100 Makefile`::\n \n \tLoads annotations as described above and automatically\n \tscrolls the view to center on line '100'.\n \n-git gui citool::\n+`git gui citool`::\n \n \tMake one commit and return to the shell when it is complete.\n \tThis command returns a non-zero exit code if the window was\n \tclosed in any way other than by making a commit.\n \n-git gui citool --amend::\n+`git gui citool --amend`::\n \n \tAutomatically enter the 'Amend Last Commit' mode of\n \tthe interface.\n \n-git gui citool --nocommit::\n+`git gui citool --nocommit`::\n \n \tBehave as normal citool, but instead of making a commit\n \tsimply terminate with a zero exit code. It still checks\n \tthat the index does not contain any unmerged entries, so\n \tyou can use it as a GUI version of linkgit:git-mergetool[1]\n \n-git citool::\n+`git citool`::\n \n \tSame as `git gui citool` (above).\n \n-git gui browser maint::\n+`git gui browser maint`::\n \n \tShow a browser for the tree of the 'maint' branch. Files\n \tselected in the browser can be viewed with the internal\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 59f8be0..6c93466 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -88,45 +88,45 @@ include::diff-generate-patch.txt[]\n \n Examples\n --------\n-git log --no-merges::\n+`git log --no-merges`::\n \n \tShow the whole commit history, but skip any merges\n \n-git log v2.6.12.. include/scsi drivers/scsi::\n+`git log v2.6.12.. include/scsi drivers/scsi`::\n \n \tShow all commits since version 'v2.6.12' that changed any file\n \tin the include/scsi or drivers/scsi subdirectories\n \n-git log --since=\"2 weeks ago\" \\-- gitk::\n+`git log --since=\"2 weeks ago\" \\-- gitk`::\n \n \tShow the changes during the last two weeks to the file 'gitk'.\n \tThe \"--\" is necessary to avoid confusion with the *branch* named\n \t'gitk'\n \n-git log --name-status release..test::\n+`git log --name-status release..test`::\n \n \tShow the commits that are in the \"test\" branch but not yet\n \tin the \"release\" branch, along with the list of paths\n \teach commit modifies.\n \n-git log --follow builtin-rev-list.c::\n+`git log --follow builtin-rev-list.c`::\n \n \tShows the commits that changed builtin-rev-list.c, including\n \tthose commits that occurred before the file was given its\n \tpresent name.\n \n-git log --branches --not --remotes=origin::\n+`git log --branches --not --remotes=origin`::\n \n \tShows all commits that are in any of local branches but not in\n \tany of remote-tracking branches for 'origin' (what you have that\n \torigin doesn't).\n \n-git log master --not --remotes=*/master::\n+`git log master --not --remotes=*/master`::\n \n \tShows all commits that are in local master but not in any remote\n \trepository master branches.\n \n-git log -p -m --first-parent::\n+`git log -p -m --first-parent`::\n \n \tShows the history including change diffs, but only from the\n \t\"main branch\" perspective, skipping commits that come from merged\ndiff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt\nindex 635c669..d7db2a3 100644\n--- a/Documentation/git-merge-file.txt\n+++ b/Documentation/git-merge-file.txt\n@@ -76,12 +76,12 @@ OPTIONS\n EXAMPLES\n --------\n \n-git merge-file README.my README README.upstream::\n+`git merge-file README.my README README.upstream`::\n \n \tcombines the changes of README.my and README.upstream since README,\n \ttries to merge them and writes the result into README.my.\n \n-git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345::\n+`git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345`::\n \n \tmerges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels\n \t`a` and `c` instead of `tmp/a123` and `tmp/c345`.\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 88acfcd..49c6e9f 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -327,12 +327,12 @@ a case where you do mean to lose history.\n Examples\n --------\n \n-git push::\n+`git push`::\n \tWorks like `git push `, where is the\n \tcurrent branch's remote (or `origin`, if no remote is\n \tconfigured for the current branch).\n \n-git push origin::\n+`git push origin`::\n \tWithout additional configuration, works like\n \t`git push origin :`.\n +\n@@ -344,45 +344,45 @@ use `git config remote.origin.push HEAD`. Any valid (like\n the ones in the examples below) can be configured as the default for\n `git push origin`.\n \n-git push origin :::\n+`git push origin :`::\n \tPush \"matching\" branches to `origin`. See\n \t in the <> section above for a\n \tdescription of \"matching\" branches.\n \n-git push origin master::\n+`git push origin master`::\n \tFind a ref that matches `master` in the source repository\n \t(most likely, it would find `refs/heads/master`), and update\n \tthe same ref (e.g. `refs/heads/master`) in `origin` repository\n \twith it. If `master` did not exist remotely, it would be\n \tcreated.\n \n-git push origin HEAD::\n+`git push origin HEAD`::\n \tA handy way to push the current branch to the same name on the\n \tremote.\n \n-git push origin master:satellite/master dev:satellite/dev::\n+`git push origin master:satellite/master dev:satellite/dev`::\n \tUse the source ref that matches `master` (e.g. `refs/heads/master`)\n \tto update the ref that matches `satellite/master` (most probably\n \t`refs/remotes/satellite/master`) in the `origin` repository, then\n \tdo the same for `dev` and `satellite/dev`.\n \n-git push origin HEAD:master::\n+`git push origin HEAD:master`::\n \tPush the current branch to the remote ref matching `master` in the\n \t`origin` repository. This form is convenient to push the current\n \tbranch without thinking about its local name.\n \n-git push origin master:refs/heads/experimental::\n+`git push origin master:refs/heads/experimental`::\n \tCreate the branch `experimental` in the `origin` repository\n \tby copying the current `master` branch. This form is only\n \tneeded to create a new branch or tag in the remote repository when\n \tthe local name and the remote name are different; otherwise,\n \tthe ref name on its own will work.\n \n-git push origin :experimental::\n+`git push origin :experimental`::\n \tFind a ref that matches `experimental` in the `origin` repository\n \t(e.g. `refs/heads/experimental`), and delete it.\n \n-git push origin {plus}dev:master::\n+`git push origin {plus}dev:master`::\n \tUpdate the origin repository's master branch with the dev branch,\n \tallowing non-fast-forward updates. *This can leave unreferenced\n \tcommits dangling in the origin repository.* Consider the\ndiff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt\nindex 4aecd4d..f095d57 100644\n--- a/Documentation/git-remote-fd.txt\n+++ b/Documentation/git-remote-fd.txt\n@@ -35,19 +35,19 @@ GIT_TRANSLOOP_DEBUG::\n \n EXAMPLES\n --------\n-git fetch fd::17 master::\n+`git fetch fd::17 master`::\n \tFetch master, using file descriptor #17 to communicate with\n \tgit-upload-pack.\n \n-git fetch fd::17/foo master::\n+`git fetch fd::17/foo master`::\n \tSame as above.\n \n-git push fd::7,8 master (as URL)::\n+`git push fd::7,8 master (as URL)`::\n \tPush master, using file descriptor #7 to read data from\n \tgit-receive-pack and file descriptor #8 to write data to\n \tsame service.\n \n-git push fd::7,8/bar master::\n+`git push fd::7,8/bar master`::\n \tSame as above.\n \n Documentation\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex 3d0a7d1..b311d59 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -93,12 +93,12 @@ effect to your index in a row.\n \n EXAMPLES\n --------\n-git revert HEAD~3::\n+`git revert HEAD~3`::\n \n \tRevert the changes specified by the fourth last commit in HEAD\n \tand create a new commit with the reverted changes.\n \n-git revert -n master{tilde}5..master{tilde}2::\n+`git revert -n master{tilde}5..master{tilde}2`::\n \n \tRevert the changes done by commits from the fifth last commit\n \tin master (included) to the third last commit in master\ndiff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt\nindex da0215d..665ad4d 100644\n--- a/Documentation/git-rm.txt\n+++ b/Documentation/git-rm.txt\n@@ -137,7 +137,7 @@ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached\n \n EXAMPLES\n --------\n-git rm Documentation/\\*.txt::\n+`git rm Documentation/\\*.txt`::\n \tRemoves all `*.txt` files from the index that are under the\n \t`Documentation` directory and any of its subdirectories.\n +\n@@ -145,7 +145,7 @@ Note that the asterisk `*` is quoted from the shell in this\n example; this lets git, and not the shell, expand the pathnames\n of files and subdirectories under the `Documentation/` directory.\n \n-git rm -f git-*.sh::\n+`git rm -f git-*.sh`::\n \tBecause this example lets the shell expand the asterisk\n \t(i.e. you are listing the files explicitly), it\n \tdoes not remove `subdir/git-foo.sh`.\ndiff --git a/Documentation/git-show.txt b/Documentation/git-show.txt\nindex 1f0e30b..1e38819 100644\n--- a/Documentation/git-show.txt\n+++ b/Documentation/git-show.txt\n@@ -48,23 +48,23 @@ include::pretty-formats.txt[]\n EXAMPLES\n --------\n \n-git show v1.0.0::\n+`git show v1.0.0`::\n \tShows the tag `v1.0.0`, along with the object the tags\n \tpoints at.\n \n-git show v1.0.0^\\{tree\\}::\n+`git show v1.0.0^\\{tree\\}`::\n \tShows the tree pointed to by the tag `v1.0.0`.\n \n-git show -s --format=%s v1.0.0^\\{commit\\}::\n+`git show -s --format=%s v1.0.0^\\{commit\\}`::\n \tShows the subject of the commit pointed to by the\n \ttag `v1.0.0`.\n \n-git show next~10:Documentation/README::\n+`git show next~10:Documentation/README`::\n \tShows the contents of the file `Documentation/README` as\n \tthey were current in the 10th last commit of the branch\n \t`next`.\n \n-git show master:Makefile master:t/Makefile::\n+`git show master:Makefile master:t/Makefile`::\n \tConcatenates the contents of said Makefiles in the head\n \tof the branch `master`.\n \ndiff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt\nindex 95b135d..346e7a2 100644\n--- a/Documentation/git-tar-tree.txt\n+++ b/Documentation/git-tar-tree.txt\n@@ -53,26 +53,26 @@ tar.umask::\n \n EXAMPLES\n --------\n-git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -)::\n+`git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -)`::\n \n \tCreate a tar archive that contains the contents of the\n \tlatest commit on the current branch, and extracts it in\n \t`/var/tmp/junk` directory.\n \n-git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz::\n+`git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz`::\n \n \tCreate a tarball for v1.4.0 release.\n \n-git tar-tree v1.4.0{caret}\\{tree\\} git-1.4.0 | gzip >git-1.4.0.tar.gz::\n+`git tar-tree v1.4.0{caret}\\{tree\\} git-1.4.0 | gzip >git-1.4.0.tar.gz`::\n \n \tCreate a tarball for v1.4.0 release, but without a\n \tglobal extended pax header.\n \n-git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar::\n+`git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar`::\n \n \tGet a tarball v1.4.0 from example.com.\n \n-git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar::\n+`git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar`::\n \n \tPut everything in the current head's Documentation/ directory\n \tinto 'git-1.4.0-docs.tar', with the prefix 'git-docs/'.\ndiff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt\nindex 99388bd..76c7f7e 100644\n--- a/Documentation/git-whatchanged.txt\n+++ b/Documentation/git-whatchanged.txt\n@@ -53,12 +53,12 @@ include::pretty-formats.txt[]\n \n Examples\n --------\n-git whatchanged -p v2.6.12.. include/scsi drivers/scsi::\n+`git whatchanged -p v2.6.12.. include/scsi drivers/scsi`::\n \n \tShow as patches the commits since version 'v2.6.12' that changed\n \tany file in the include/scsi or drivers/scsi subdirectories\n \n-git whatchanged --since=\"2 weeks ago\" \\-- gitk::\n+`git whatchanged --since=\"2 weeks ago\" \\-- gitk`::\n \n \tShow the changes during the last two weeks to the file 'gitk'.\n \tThe \"--\" is necessary to avoid confusion with the *branch* named\n"},{"id":"172842","messageId":"7vwret6hgj.fsf@alter.siamese.dyndns.org","threadId":"28014","inReplyTo":"20110804020054.GA1947@sigill.intra.peff.net","subject":"Re: git-archive's wrong documentation: really write pax rather than tar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-08-04T02:25:32Z","receivedAt":"2011-08-04T02:25:32Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Wed, Aug 03, 2011 at 06:56:41PM -0700, Junio C Hamano wrote:\n>\n>> Jeff King writes:\n>> \n>> > It might be a bit more obvious to find if we actually had a\n>> > --no-pax-header option, though.\n>> \n>> Yeah, we would need to make sure that --no-pack-header causes a barf\n>> for other backends, though. \"struct archiver_args\" right now seems to have\n>> compression_level but I think it should just have \"const char **\" that is\n>> interpreted by backends.\n>\n> Actually, it is relevant for zip, too. The option should really be\n> called \"--no-commit-id\" or something similar. I don't think it's as big\n> a deal with zip (because there is no compatibility issue), but you may\n> want to omit the header for other reasons (e.g., because you know it\n> doesn't point to a commit that is public).\n\nHmm, perhaps. It indeed is an implementation detail of the tar backend\nthat the commit object name is stored in pax header, so --no-commit-id\nmight make sense from \"git\" point of view, but from the point of view of\nOP that started this thread, he wouldn't care what that extra information\nis --- it can be a commit object name or it can be phase of the moon when\nthe archive was made --- he just wants the extra header dropped.\n\nSo I dunno.\n"},{"id":"172843","messageId":"20110804022903.GA3388@sigill.intra.peff.net","threadId":"28014","inReplyTo":"7vwret6hgj.fsf@alter.siamese.dyndns.org","subject":"Re: git-archive's wrong documentation: really write pax rather than tar","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-08-04T02:29:03Z","receivedAt":"2011-08-04T02:29:03Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 03, 2011 at 07:25:32PM -0700, Junio C Hamano wrote:\n\n> > Actually, it is relevant for zip, too. The option should really be\n> > called \"--no-commit-id\" or something similar. I don't think it's as big\n> > a deal with zip (because there is no compatibility issue), but you may\n> > want to omit the header for other reasons (e.g., because you know it\n> > doesn't point to a commit that is public).\n> \n> Hmm, perhaps. It indeed is an implementation detail of the tar backend\n> that the commit object name is stored in pax header, so --no-commit-id\n> might make sense from \"git\" point of view, but from the point of view of\n> OP that started this thread, he wouldn't care what that extra information\n> is --- it can be a commit object name or it can be phase of the moon when\n> the archive was made --- he just wants the extra header dropped.\n> \n> So I dunno.\n\nIf the intent of the option is \"write plain-vanilla ustar\" (I really\nhope it doesn't need to be \"plain-vanilla 4.3BSD tar\"), then I think we\nwould do better to have a new --format type. Because from the OP's\nperspective, it's not \"drop this header that I don't like\" but \"make\nsomething compatible with older versions of tar\".\n\n-Peff\n"},{"id":"172938","messageId":"4E3AD953.6010808@lsrfire.ath.cx","threadId":"28014","inReplyTo":"20110804022903.GA3388@sigill.intra.peff.net","subject":"Re: git-archive's wrong documentation: really write pax rather than tar","fromName":"René Scharfe","fromEmail":"rene.scharfe@lsrfire.ath.cx","sentAt":"2011-08-04T17:39:31Z","receivedAt":"2011-08-04T17:39:31Z","isPatch":false,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Am 04.08.2011 04:29, schrieb Jeff King:\n> On Wed, Aug 03, 2011 at 07:25:32PM -0700, Junio C Hamano wrote:\n> \n>>> Actually, it is relevant for zip, too. The option should really be\n>>> called \"--no-commit-id\" or something similar. I don't think it's as big\n>>> a deal with zip (because there is no compatibility issue), but you may\n>>> want to omit the header for other reasons (e.g., because you know it\n>>> doesn't point to a commit that is public).\n>>\n>> Hmm, perhaps. It indeed is an implementation detail of the tar backend\n>> that the commit object name is stored in pax header, so --no-commit-id\n>> might make sense from \"git\" point of view, but from the point of view of\n>> OP that started this thread, he wouldn't care what that extra information\n>> is --- it can be a commit object name or it can be phase of the moon when\n>> the archive was made --- he just wants the extra header dropped.\n>>\n>> So I dunno.\n> \n> If the intent of the option is \"write plain-vanilla ustar\" (I really\n> hope it doesn't need to be \"plain-vanilla 4.3BSD tar\"), then I think we\n> would do better to have a new --format type. Because from the OP's\n> perspective, it's not \"drop this header that I don't like\" but \"make\n> something compatible with older versions of tar\".\n\nYes, the commit ID header is just one part of this. Extended pax\nheaders are also used to store file names or symlink targets that are\ntoo long. If none of this applies, the output should be pure ustar, though.\n\nPOSIX says that programs should treat unknown entry types just like\nplain files and print an error message. You'd get an extra file named\npax_global_header, containing only the commit ID, and for long file\nnames extra files that contain them (and your original files would get\nshort names based on their object ID).\n\nLooking at the web page linked to in the original post, the problem\nseems to be that R (probably http://www.r-project.org/) uses \"tar\" as a\npackage format, seems to accept the ustar format but refuses pax\nextended headers and thus is incompatible with \"POSIX tar\" and also\ndoesn't follow the suggestion to treat unknown entries as plain files.\n\nWe could add a \"ustar\" format that doesn't write commit ID comments and\nerrors out on file names that are too long.\n\nRené\n"},{"id":"172957","messageId":"7vei104wpu.fsf@alter.siamese.dyndns.org","threadId":"28014","inReplyTo":"20110804021329.GB32579@sigill.intra.peff.net","subject":"Re: git-archive's wrong documentation: really write pax rather than tar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-08-04T22:51:09Z","receivedAt":"2011-08-04T22:51:09Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> As a bonus, this also fixes an example in the git-push manpage, in which\n> \"git push origin :::\" was accidentally considered a newly-indented list,\n> and not a list item with \"git push origin :\" in it.\n\nThanks. That \"happens to have colon at the end\" one is nasty.\n"}]}