{"thread":{"id":"7503","subject":"[PATCH] Documentation: A few minor fixes to Git User's Manual","startedAt":"2007-04-03T16:27:28Z","lastAt":"2007-04-04T18:31:41Z","messageCount":7,"participants":["Jakub Narebski","J. Bruce Fields","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"38506","messageId":"11756176481314-git-send-email-jnareb@gmail.com","threadId":"7503","inReplyTo":null,"subject":"[PATCH] Documentation: A few minor fixes to Git User's Manual","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-04-03T16:27:28Z","receivedAt":"2007-04-03T16:27:28Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Mainly consistent usage of \"git command\" and not \"git-command\" syntax\n\nSigned-off-by: Jakub Narebski \n---\nA few [shorthand] comments about Git User's Manual:\n\n* no \"detached head\" feature (since 1.5.0.5 at least)\n* git branch --track as shorthand (for 1.5.1)\n* uses ssh://host/path syntax instead of scp-like host:path\n (which one is preferred? documentation has URL-like first)\n* no mention of receive.denyNonFastForwards (in about push)\n* inconsistent use of header levels\n Level 0 (top level): ====================== \n Level 1: ---------------------- \n Level 2: ~~~~~~~~~~~~~~~~~~~~~~ \n Level 3: ^^^^^^^^^^^^^^^^^^^^^^ \n Level 4 (bottom level): ++++++++++++++++++++++\n* no git rebase --skip (e.g. if patch was applied, but\n duplication was not detected, or patch is no longer needed)\n* no git rebase --merge (e.g. renames)\n* git cherry-pick --no-commit + git commit, instead of\n git cherry-pick + git commit --amend\n* legitimate use of multiple root commits: joining projects\n (e.g. git = git-core + git-tools (mail) + gitk + gitweb + git-gui)\n* note that description of git internals would use plumbing\n commands (e.g. git-update-index instead of git-add / git-rm)\n* blob object: git-add and git-show instead of git-update-index\n and git-cat-file? (plumbing vs porcelain)\n* tree object: user usually do not use git-write-tree (plumbing) (?)\n* commit object: \"read SCM's\", \"idiotic file manager\" -- git has\n now enough porcelain to be considered full fledged SCM (in \"Note\n on commits\"). needs rewording?\n* tag object: porcelain to create tag is git-tag, and you can use\n git tag -v to verify a tag (plumbing vs porcelain)\n* interchanging old name \"directory cache\" with new name \"index\"\n* git update-index --force-remove to make file untracked\n* very useful git-cat-file -p\n* git-rev-parse ^{tree} instead of \n git-cat-file commit | head -1\n* git-cat-file blob :1:hello.c >hello.c~1, git-merge-file\n (and git-mergetool if discussion was not so plumbing-ish)\n\n Documentation/user-manual.txt | 20 ++++++++++----------\n 1 files changed, 10 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 1c49e69..574e9c0 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -84,7 +84,7 @@ $ git branch -r\t\t# list\n origin/master\n origin/next\n ...\n-$ git branch checkout -b masterwork origin/master\n+$ git checkout -b masterwork origin/master\n -----------------------------------------------\n \n Fetch a branch from a different repository, and give it a new\n@@ -155,8 +155,8 @@ Make sure git knows who to blame:\n ------------------------------------------------\n $ cat >~/.gitconfig <<\\EOF\n [user]\n-name = Your Name Comes Here\n-email = you@yourdomain.example.com\n+\tname = Your Name Comes Here\n+\temail = you@yourdomain.example.com\n EOF\n ------------------------------------------------\n \n@@ -195,7 +195,7 @@ Importing or exporting patches:\n -----------------------------------------------\n $ git format-patch origin..HEAD # format a patch for each commit\n \t\t\t\t# in HEAD but not in origin\n-$ git-am mbox # import patches from the mailbox \"mbox\"\n+$ git am mbox # import patches from the mailbox \"mbox\"\n -----------------------------------------------\n \n Fetch a branch in a different git repository, then merge into the\n@@ -579,7 +579,7 @@ cloned from, using gitlink:git-remote[1]:\n \n -------------------------------------------------\n $ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git\n-$ git fetch\n+$ git fetch linux-nfs\n * refs/remotes/linux-nfs/master: storing branch 'master' ...\n commit: bf81b46\n -------------------------------------------------\n@@ -680,7 +680,7 @@ occasionally you may land on a commit that broke something unrelated;\n run\n \n -------------------------------------------------\n-$ git bisect-visualize\n+$ git bisect visualize\n -------------------------------------------------\n \n which will run gitk and label the commit it chose with a marker that\n@@ -765,7 +765,7 @@ We can also create a tag to refer to a particular commit; after\n running\n \n -------------------------------------------------\n-$ git-tag stable-1 1b2e1d63ff\n+$ git tag stable-1 1b2e1d63ff\n -------------------------------------------------\n \n You can use stable-1 to refer to the commit 1b2e1d63ff.\n@@ -909,7 +909,7 @@ name based on any tag it finds pointing to one of the commit's\n descendants:\n \n -------------------------------------------------\n-$ git name-rev e05db0fd\n+$ git name-rev --tags e05db0fd\n e05db0fd tags/v1.5.0-rc1^0~23\n -------------------------------------------------\n \n@@ -918,7 +918,7 @@ revision using a tag on which the given commit is based:\n \n -------------------------------------------------\n $ git describe e05db0fd\n-v1.5.0-rc0-ge05db0f\n+v1.5.0-rc0-260-ge05db0f\n -------------------------------------------------\n \n but that may sometimes help you guess which tags might come after the\n@@ -1861,7 +1861,7 @@ Allow web browsing of a repository\n \n The gitweb cgi script provides users an easy way to browse your\n project's files and history without having to install git; see the file\n-gitweb/README in the git source tree for instructions on setting it up.\n+gitweb/INSTALL in the git source tree for instructions on setting it up.\n \n Examples\n --------\n-- \n1.5.0.5\n"},{"id":"38512","messageId":"20070403172113.GB26201@fieldses.org","threadId":"7503","inReplyTo":"11756176481314-git-send-email-jnareb@gmail.com","subject":"Re: [PATCH] Documentation: A few minor fixes to Git User's Manual","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-04-03T17:21:13Z","receivedAt":"2007-04-03T17:21:13Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Tue, Apr 03, 2007 at 06:27:28PM +0200, Jakub Narebski wrote:\n> Mainly consistent usage of \"git command\" and not \"git-command\" syntax\n\nLooks good, thanks!\n\n> A few [shorthand] comments about Git User's Manual:\n\nAnd thanks very much for the comments.\n\n> * inconsistent use of header levels\n> Level 0 (top level): ======================\n> Level 1: ----------------------\n> Level 2: ~~~~~~~~~~~~~~~~~~~~~~\n> Level 3: ^^^^^^^^^^^^^^^^^^^^^^\n> Level 4 (bottom level): ++++++++++++++++++++++\n\nHave you found internal inconsistencies, or are you just referring to\nthe fact that it's using different syntax from the default?\n\nMy original intention was to suck in other articles under Documentation/\nas chapters. Shifting all the headers by one allows us to do that, at\nleast initially, by just including the articles without modification.\nThe glossary is the only thing we're currently using that way, though.\n\nThe \"Git interals\" chapter is obviously most taken from the README,\nwhich has gotten out of date in a few places.\n\nMy vague medium-term plan is to revise that chapter and then merge\ntutorial-2.txt into it, and maybe core-tutorial too, but I haven't had\ntime to work on it recently. (Any help appreciated.)\n\nI'd kinda like to remove all the tutorials some day and absorb them into\nthe manual instead, but maybe that would be unpopular.\n\n--b.\n"},{"id":"38516","messageId":"7vd52lz4i3.fsf@assigned-by-dhcp.cox.net","threadId":"7503","inReplyTo":"11756176481314-git-send-email-jnareb@gmail.com","subject":"Re: [PATCH] Documentation: A few minor fixes to Git User's Manual","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-04-03T18:39:48Z","receivedAt":"2007-04-03T18:39:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narebski writes:\n\n> Mainly consistent usage of \"git command\" and not \"git-command\" syntax\n>\n> Signed-off-by: Jakub Narebski \n\nThe patch part looks good so I'll be applying it before 1.5.1, Ok?\n"},{"id":"38517","messageId":"20070403185744.GE26201@fieldses.org","threadId":"7503","inReplyTo":"7vd52lz4i3.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation: A few minor fixes to Git User's Manual","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-04-03T18:57:44Z","receivedAt":"2007-04-03T18:57:44Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Tue, Apr 03, 2007 at 11:39:48AM -0700, Junio C Hamano wrote:\n> Jakub Narebski writes:\n> \n> > Mainly consistent usage of \"git command\" and not \"git-command\" syntax\n> >\n> > Signed-off-by: Jakub Narebski \n> \n> The patch part looks good so I'll be applying it before 1.5.1, Ok?\n\nDefinitely. If you'd like:\n\nAcked-by: J. Bruce Fields \n\n--b.\n"},{"id":"38518","messageId":"7vlkh9xotn.fsf@assigned-by-dhcp.cox.net","threadId":"7503","inReplyTo":"11756176481314-git-send-email-jnareb@gmail.com","subject":"Re: [PATCH] Documentation: A few minor fixes to Git User's Manual","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-04-03T19:03:48Z","receivedAt":"2007-04-03T19:03:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narebski writes:\n\n> * no \"detached head\" feature (since 1.5.0.5 at least)\n\nThat is a 1.5.0 feature.\n\nCare to volunteer to write that section? I think illustrating\nwhat you would want to achieve by detaching your HEAD would be\nuseful, and I offhand know of two different uses:\n\n - Sightseeing. You do not intend to build on, but seek around\n to see what was there in the past. Checking out a tag or a\n remote branch falls into this.\n\n - Rebuilding history. When you want to futz with a commit 5\n revs ago, you would detach your HEAD to that commit, fix it\n up, and rebase the original branch on top of that detached\n HEAD.\n\nI am sure people may have invented more creative ways to use it.\nThe topic probably belongs to \"advanced user's manual\", though.\n\n> * uses ssh://host/path syntax instead of scp-like host:path\n> (which one is preferred? documentation has URL-like first)\n\nMy impression is that site:path is preferred.\n\n> * no mention of receive.denyNonFastForwards (in about push)\n\nI think the \"Setting up a shared repository\" section refers most\nof the material to cvs-migration.txt, so you probably want to\nadd a sentence to \"Advanced Shared Repository Management\"\nsection in the latter.\n\n> * inconsistent use of header levels\n\nI am not sure what you are getting at. \n\n> * no git rebase --merge (e.g. renames)\n> * git cherry-pick --no-commit + git commit, instead of\n> git cherry-pick + git commit --amend\n\nIt usually is not a good idea for a manual to show two ways to\ndo the same thing without explaining pros and cons.\n\nI typically use rebase *without* --merge because it tends to be\nfaster (recently 'mailinfo' was broken for i18n contents, and I\nhad to use \"rebase --merge\" until it was fixed; now I can go\nback to my old ways of running it without --merge ;-)). I think\nthe only reason to use --merge is when you want the rename thing\nin merge-recursive.\n\nI do not think \"cherry-pick -n + commit\" vs \"cherry-pick +\ncommit --amend\" is an interesting contrast for a single commit.\nSquashing more than one commit is why you would want to pick\nwithout committing, which you cannot do with the latter. So\nthey are not \"instead of\" -- they serve different purposes.\n\n> * legitimate use of multiple root commits: joining projects\n> (e.g. git = git-core + git-tools (mail) + gitk + gitweb + git-gui)\n\nI am not sure if you would even need to talk about it. As long\nas the document does not say \"you shouldn't have more than one\nroot\", I think we are Ok.\n"},{"id":"38666","messageId":"200704041722.58780.jnareb@gmail.com","threadId":"7503","inReplyTo":"20070403172113.GB26201@fieldses.org","subject":"Re: [PATCH] Documentation: A few minor fixes to Git User's Manual","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-04-04T15:22:58Z","receivedAt":"2007-04-04T15:22:58Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Tue, Apr 03, 2007, J. Bruce Fields wrote:\n> On Tue, Apr 03, 2007 at 06:27:28PM +0200, Jakub Narebski wrote:\n>>\n>> A few [shorthand] comments about Git User's Manual:\n[...]\n>> * inconsistent use of header levels\n>> Level 0 (top level): ======================\n>> Level 1: ----------------------\n>> Level 2: ~~~~~~~~~~~~~~~~~~~~~~\n>> Level 3: ^^^^^^^^^^^^^^^^^^^^^^\n>> Level 4 (bottom level): ++++++++++++++++++++++\n> \n> Have you found internal inconsistencies, or are you just referring to\n> the fact that it's using different syntax from the default?\n\nBoth, but more the fact that I haven't noticed that user-manual uses\ndifferent syntax (____ and not ==== is Level 0), and that I mistook\n____ for ---- (perhaps #### would be better, if it is possible), but\nalso the fact that parts Git User's Manual is composed of use different\nsectioning.\n\n> I'd kinda like to remove all the tutorials some day and absorb them into\n> the manual instead, but maybe that would be unpopular.\n\nI'd rather keep the tutorials, perhaps making them more tutorial-ish,\nand adding proposed but not as a patch and not included \"Branching and\nMerging\" tutorial, and making Git User's Manual more a reference material.\n\n-- \nJakub Narebski\nPoland\n"},{"id":"38665","messageId":"200704042031.41475.jnareb@gmail.com","threadId":"7503","inReplyTo":"7vlkh9xotn.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation: A few minor fixes to Git User's Manual","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-04-04T18:31:41Z","receivedAt":"2007-04-04T18:31:41Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Thu, Apr 03, 2007, Junio C Hamano wrote:\n> Jakub Narebski writes:\n> \n>> * no \"detached head\" feature (since 1.5.0.5 at least)\n> \n> That is a 1.5.0 feature.\n> \n> Care to volunteer to write that section?\n\nI'd rather not write about somthing I don't personally use.\nBut I can add one sentence mentioning detached head as an\nalternative to \"checkout -b tmp\", \"reset --hard\" for sightseeing.\nSee also below.\n \n> I think illustrating \n> what you would want to achieve by detaching your HEAD would be\n> useful, and I offhand know of two different uses:\n> \n> - Sightseeing. You do not intend to build on, but seek around\n> to see what was there in the past. Checking out a tag or a\n> remote branch falls into this.\n> \n> - Rebuilding history. When you want to futz with a commit 5\n> revs ago, you would detach your HEAD to that commit, fix it\n> up, and rebase the original branch on top of that detached\n> HEAD.\n> \n> I am sure people may have invented more creative ways to use it.\n> The topic probably belongs to \"advanced user's manual\", though.\n\nIf I remember correctly I have added this note because of using\n\"git checkout -b new remotes/branch\" (or tag) together with\n\"git reset --hard tag\" for sight-seeing.\n \n>> * uses ssh://host/path syntax instead of scp-like host:path\n>> (which one is preferred? documentation has URL-like first)\n> \n> My impression is that site:path is preferred.\n\nSo perhaps we should use this syntax in Git User's Manual?\n \n>> * no mention of receive.denyNonFastForwards (in about push)\n> \n> I think the \"Setting up a shared repository\" section refers most\n> of the material to cvs-migration.txt, so you probably want to\n> add a sentence to \"Advanced Shared Repository Management\"\n> section in the latter.\n\nI was referring to the following fragment:\n\n As with git-fetch, git-push will complain if this does not result in\n a <>. Normally this is a sign of\n something wrong. However, if you are sure you know what you're\n doing, you may force git-push to perform the update anyway by\n proceeding the branch name by a plus sign:\n\n -------------------------------------------------\n $ git push ssh://yourserver.com/~you/proj.git +master\n -------------------------------------------------\n\nI'd like to have note here that if receive.denyNonFastForwards is set\non remote repository side (and it is set by default when initializing\nshared repository), then you would not be able to force non fast-forward\npush. Just to avoid potential confusion (why it is not accepting push?).\n \n>> * no git rebase --merge (e.g. renames)\n>> * git cherry-pick --no-commit + git commit, instead of\n>> git cherry-pick + git commit --amend\n> \n> It usually is not a good idea for a manual to show two ways to\n> do the same thing without explaining pros and cons.\n> \n> I typically use rebase *without* --merge because it tends to be\n> faster (recently 'mailinfo' was broken for i18n contents, and I\n> had to use \"rebase --merge\" until it was fixed; now I can go\n> back to my old ways of running it without --merge ;-)). I think\n> the only reason to use --merge is when you want the rename thing\n> in merge-recursive.\n\nIt would be enough to have one sentence mentioning it, like e.g.\n\"Use 'git rebase --merge' if rebased commits include renames\",\nor something like that.\n \n> I do not think \"cherry-pick -n + commit\" vs \"cherry-pick +\n> commit --amend\" is an interesting contrast for a single commit.\n> Squashing more than one commit is why you would want to pick\n> without committing, which you cannot do with the latter. So\n> they are not \"instead of\" -- they serve different purposes.\n\nWell, perhaps in \"Advanced...\" section it should be mentioned\nthat you can use 'git cherry-pick --no-commit' to concatenate\ntogether some commits (and 'git merge --squash' to concatenate\nwhole branch to single commit).\n\nChosing \"cherry-pick -n + commit\" vs \"cherry-pick + commit --amend\"\nis IMVHO a matter of taste; I think commit --amend is encouraged.\n\n>> * legitimate use of multiple root commits: joining projects\n>> (e.g. git = git-core + git-tools (mail) + gitk + gitweb + git-gui)\n> \n> I am not sure if you would even need to talk about it. As long\n> as the document does not say \"you shouldn't have more than one\n> root\", I think we are Ok.\n\nI was thinking about adding a sentence that you can have multiple\nroot commits in repository, and usually they are result of joining\ntwo projects (git can join projects, which is a plus), or rather\nincluding one project in the other.\n\nGit User's Manual says:\n\n As a special case, a commit object with no parents is called the\n \"root\" object, and is the point of an initial project commit. Each\n project must have at least one root, and while you can tie several\n different root objects together into one project by creating a commit\n object which has two or more separate roots as its ultimate parents,\n that's probably just going to confuse people. So aim for the notion\n of \"one root object per project\", even if git itself does not enforce\n that.\n\nI'd rather have this softened: try do not use it for the sake of using \nit, but joining projects (swallowing other project) results in multiple \nroots.\n\n-- \nJakub Narebski\nShadeHawk on #git\nPoland\n"}]}