{"thread":{"id":"43200","subject":"Re: A documentation to-do list","startedAt":"2006-11-22T01:13:12Z","lastAt":"2006-11-22T20:31:24Z","messageCount":6,"participants":["Michael K. Edwards","Junio C Hamano","Alan Chandler","lamikr","Chris Riddoch","Johannes Schindelin"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"297290","messageId":"6efbd9b70611211713y4a1574adje48622f7bab6d702@mail.gmail.com","threadId":"43200","inReplyTo":null,"subject":"A documentation to-do list","fromName":"Chris Riddoch","fromEmail":"riddochc@gmail.com","sentAt":"2006-11-22T01:13:12Z","receivedAt":"2006-11-22T01:13:12Z","isPatch":false,"sender":{"key":"riddochc@gmail.com","avatar":null},"body":"Hi, everyone.\n\nHaving decided to take it on myself to improve Git's documentation, I\nasked on #git if people had particular things they felt I should focus\non. I also was prompted to put up a page on the wiki to make my to-do\nlist public.\n\nSo, I present: http://git.or.cz/gitwiki/Documentation_To-Do_List\n\nAdd your favorite, specific, lack-of-documentation or badly-described\nannoyance here!\n\n-- \nepistemological humility\n"},{"id":"294166","messageId":"7vslgcw9ii.fsf@assigned-by-dhcp.cox.net","threadId":"43200","inReplyTo":"6efbd9b70611211713y4a1574adje48622f7bab6d702@mail.gmail.com","subject":"Re: A documentation to-do list","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-11-22T01:33:09Z","receivedAt":"2006-11-22T01:33:09Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Chris Riddoch\" writes:\n\n> Hi, everyone.\n>\n> Having decided to take it on myself to improve Git's documentation, I\n> asked on #git if people had particular things they felt I should focus\n> on. I also was prompted to put up a page on the wiki to make my to-do\n> list public.\n>\n> So, I present: http://git.or.cz/gitwiki/Documentation_To-Do_List\n>\n> Add your favorite, specific, lack-of-documentation or badly-described\n> annoyance here!\n\nThanks.\n\nI would not likely to be writing the updates because I am not a\ngood writer myself, but if there are things that need to be\nexplained, both behaviour-wise and intent/design-wise, I am\nwilling to help this effort.\n\nAside from lacking minor details here and there I think the\nlargest problem in the current documentation set is the\norganization, though.\n\n"},{"id":"294424","messageId":"200611220529.18568.alan@chandlerfamily.org.uk","threadId":"43200","inReplyTo":"6efbd9b70611211713y4a1574adje48622f7bab6d702@mail.gmail.com","subject":"Re: A documentation to-do list","fromName":"Alan Chandler","fromEmail":"alan@chandlerfamily.org.uk","sentAt":"2006-11-22T05:29:18Z","receivedAt":"2006-11-22T05:29:18Z","isPatch":false,"sender":{"key":"alan@chandlerfamily.org.uk","avatar":"https://gravatar.com/avatar/1862247e5ea8eac114c842f9dc3a5db6253754e24ef7171757cf97eedce48b8c?d=mp&s=160"},"body":"On Wednesday 22 November 2006 01:13, Chris Riddoch wrote:\n> Hi, everyone.\n>\n> Having decided to take it on myself to improve Git's documentation, I\n> asked on #git if people had particular things they felt I should focus\n> on. I also was prompted to put up a page on the wiki to make my to-do\n> list public.\n>\n> So, I present: http://git.or.cz/gitwiki/Documentation_To-Do_List\n>\n> Add your favorite, specific, lack-of-documentation or badly-described\n> annoyance here!\n\nTimely, although I will ask the question here rather than there.\n\nI have started to use git-rebase a lot to try and sort out a project that has \ngot lots of long chains of commits on parallel branches doing roughly the \nsame thing. But I do not understand what the --merge flag is about.\n\ngit-rebase is clearly doing some form of merge for every commit it moves \nwithout the --merge flag, so what does it add?\n\nI thought I understood merging, but clearly I don't.\n\n-- \nAlan Chandler\n"},{"id":"298328","messageId":"Pine.LNX.4.63.0611221044180.30004@wbgn013.biozentrum.uni-wuerzburg.de","threadId":"43200","inReplyTo":"6efbd9b70611211713y4a1574adje48622f7bab6d702@mail.gmail.com","subject":"Re: A documentation to-do list","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2006-11-22T09:57:03Z","receivedAt":"2006-11-22T09:57:03Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 21 Nov 2006, Chris Riddoch wrote:\n\n> Having decided to take it on myself to improve Git's documentation, I\n> asked on #git if people had particular things they felt I should focus\n> on.\n\nI have a request, which is not about _what_ to document, but _how_. People \noften complained about the bad introduction into git, pointing to \nhttp://www.selenic.com/mercurial/wiki/index.cgi/QuickStart for a \"way \nbetter\" tutorial.\n\nIt would be really, really easy to just copy that, and describe git \ninstead of hg. (There is no mention of a license there, so that may not be \nallowed, but then, it is too short and obvious to be copyrightable, isn't \nit?) You will find that git commands are way shorter!\n\nSo, finally my request: we should _organize_ the documentation such that \nyour average Joe Programmer is able to get started with git in 1 minute.\n\nIf she is interested in more subtle operations, then she should have a \ntechnical overview such as \"Branching and merging with git\", maybe a \nlittle stripped down to leave complicated (but for normal work \nuninteresting) issues out. With a pot of steaming coffee.\n\nFinally, for complicated issues, there is Documentation/technical, the man \npages, the source, and the git list (in that order).\n\nHmmm?\n\nCiao,\nDscho\n"},{"id":"294021","messageId":"f2b55d220611220918ud5071dcj2d5d23489d9d099f@mail.gmail.com","threadId":"43200","inReplyTo":"Pine.LNX.4.63.0611221044180.30004@wbgn013.biozentrum.uni-wuerzburg.de","subject":"Re: A documentation to-do list","fromName":"Michael K. Edwards","fromEmail":"medwards.linux@gmail.com","sentAt":"2006-11-22T17:18:57Z","receivedAt":"2006-11-22T17:18:57Z","isPatch":false,"sender":{"key":"medwards.linux@gmail.com","avatar":null},"body":"On 11/22/06, Johannes Schindelin wrote:\n> So, finally my request: we should _organize_ the documentation such that\n> your average Joe Programmer is able to get started with git in 1 minute.\n\nI would modify that to a sort of \"choose your own adventure\" alternative:\n How to use git mindlessly (branchlessly) in 1 minute, by\npretending it's CVS with funny syntax;\nvs.\n How git can make you a better programmer in 1 day, by encouraging\nyou to think about, experiment with, and comment on interactions\nbetween how you and others are evolving a shared code base.\n\nCheers,\n"},{"id":"294972","messageId":"4564B39C.2020903@cc.jyu.fi","threadId":"43200","inReplyTo":"Pine.LNX.4.63.0611221044180.30004@wbgn013.biozentrum.uni-wuerzburg.de","subject":"Re: A documentation to-do list","fromName":"lamikr","fromEmail":"lamikr@cc.jyu.fi","sentAt":"2006-11-22T20:31:24Z","receivedAt":"2006-11-22T20:31:24Z","isPatch":false,"sender":{"key":"lamikr@cc.jyu.fi","avatar":null},"body":"Johannes Schindelin wrote:\n> Hi,\n>\n> On Tue, 21 Nov 2006, Chris Riddoch wrote:\n>\n> \n>> Having decided to take it on myself to improve Git's documentation, I\n>> asked on #git if people had particular things they felt I should focus\n>> on.\n>> \n>\n> I have a request, which is not about _what_ to document, but _how_. People \n> often complained about the bad introduction into git, pointing to \n> http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart for a \"way \n> better\" tutorial.\n> \nI agree with this. In addition at least I have always missed official\n\"home page\" as even currently the kernel.org points for example just to\n\n http://www.kernel.org/pub/software/scm/git/\n \nOk, by clicking the \"docs\" subfolder one gets to man pages. But man\npages does not specify the basic things like, where is the official git\nrepository\nand how to pull the latest official or development versions from there.\nIn addition man pages are not the fastest way to get started.\nInstead small tutorial for example with a following kind of usage\nscenario might be quite useful for many. (I do not know even myself to\nstep 10 :-)\n\n1) One clones architehture specific git repository\n (for example git-clone\ngit://git.kernel.org/pub/scm/linux/kernel/git/tmlind/linux-omap-2.6.git)\n2) This repository has omap specific things in master branch which is\noften synced with main kernel\n3) Once omap specific things are working agains the release kernel\n(let's say 2.6.16), master is tagged with keys like\n \"linux-omap-2.6.16-omap1\"\n4) User creates \"MY_DEV\" branch and adds own changes to there\n5) User tags the branch with \"MY_OMAP1_2_6_16\" and releases own\n2.6.16-omap1 based kernel\n6) Master branch in OMAP is synced with the main kernel which is now\nsomewhere like 2.6.18-rc5\n7) User changes to master branch, pulls the master branch to 2.6.18-rc5\nlevel\n8) User switches to MY_DEV branch has pulls it it 2.6.18-rc5 level from\nmaster branch. Fix merge errors and commits them there.\n9) Stable team releases bug fix version 2.6.16.25 to own git\n10) User wants to release MY_OMAP1_2_6_16_25 version and would like to\nuse git-pull instead of using patch files\n - How to jump back to tagged version in repository?\n - How to pull the stable team changes here?\n\nOther common issues that comes to my mind are but which are not easy to\nfind out from the current official\nman based documentation:\n\n1) where is the repository and gitweb for git itself. (only man pages\nare easy to find out currently from net).\n2) how to checkout the latest from there (even announcement emails does\nnot mention this currently!)\n3) how to pull the git repository to newer version when Junio announces\nnew tar-balls\n4) how to change to older tagged version (or to some older non tagged\ncommit version) and build from there\n5) how to create own work branch, commit changes to there and\n a) use git-format-patches to create patch files\n b) automatize the patch sending via emails\n c) use push for sending changes back to master repository\n6) what is the difference between origin and master. Can user push\nchanges to origin or should they always be pushed to master or own branch\n7) how to create own repository\n8) how to set-up gitweb to show your own git repository\n9) how to allow others to pull over http connection from your repository\n(this was for example easy, but it is hard to find any documentation\nfrom this)\n10) how to allow others to pull over git connection from your repository\n(requires git-daemon + touch command with magic keyword)\n\n"}]}