summaryrefslogtreecommitdiff
path: root/Documentation/tutorial.txt
AgeCommit message (Collapse)AuthorFilesLines
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-12/+12
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-08-24Documentation: Correct various misspellings and typos.Libravatar Brian Hetro1-1/+1
Fix minor typos throughout the documentation. Signed-off-by: Brian Hetro <whee@smaertness.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-07-08Merge branch 'maint'Libravatar Junio C Hamano1-1/+1
* maint: user-manual: fix directory name in git-archive example user-manual: more explanation of push and pull usage tutorial: Fix typo user-manual: grammar and style fixes
2007-07-08tutorial: Fix typoLibravatar J. Bruce Fields1-1/+1
"You" should be "Alice" here. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-07-05fix remote.origin.url in tutorial.txtLibravatar Alecs King1-1/+1
Bob cloned from Alice. The origin url is actually Alice's repo. Signed-off-by: Alecs King <alecsk@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-06-10tutorial: use "project history" instead of "changelog" in headerLibravatar J. Bruce Fields1-2/+2
The word "changelog" seems a little too much like jargon to me, and beginners must understand section headers so they know where to look for help. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-19tutorial: revise index introductionLibravatar J. Bruce Fields1-49/+45
The embarassing history of this tutorial is that I started it without really understanding the index well, so I avoided mentioning it. And we all got the idea that "index" was a word to avoid using around newbies, but it was reluctantly mentioned that *something* had to be said. The result is a little awkward: the discussion of the index never actually uses that word, and isn't well-integrated into the surrounding material. Let's just go ahead and use the word "index" from the very start, and try to demonstrate its use with a minimum of lecturing. Also, remove discussion of using git-commit with explicit filenames. We're already a bit slow here to get people to their first commit, and I'm not convinced this is really so important. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-19tutorials: add user-manual linksLibravatar J. Bruce Fields1-1/+5
Mention the user manual, especially as an alternative introduction for user's mainly interested in read-only operations. And fix a typo while we're there. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
2007-05-04Mention version 1.5.1 in tutorial and user-manualLibravatar Carl Worth1-2/+2
Most other documentation will frequently be read from an installation of git so will naturally be associated with the installed version. But these two documents in particular are often read from web pages while users are still exploring git. It's important to mention version 1.5.1 since these documents provide example commands that won't work with previous versions of git. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-18Fix unmatched emphasis tag in git-tutorialLibravatar Andrew Ruder1-1/+1
In asciidoc 7.1.2 and prior there is no obvious way to get: 'add'ing to emphasize only the "add", instead it treats the first apostrophe as the beginning of an emphasis, and the second apostrophe as a regular apostrophe and makes the rest of the line an emphasis since there is no closing apostrophe. In the newer asciidoc you can do it pretty easily with __add__ing but I'm not sure it would be best to make that a prereq for something as silly as this. Signed-off-by: Andrew Ruder <andy@aeruder.net> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-04Why is it bad to rewind a branch that has already been pushed out?Libravatar Robin Rosenberg1-0/+2
Mention git-revert as an alternative to git-reset to revert changes. Signed-off-by: Robin Rosenberg <robin.rosenberg@dewire.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-03Why is it bad to rewind a branch that has already been pushed out?Libravatar Junio C Hamano1-3/+3
I was reading the tutorial and noticed that we say this: Also, don't use "git reset" on a publicly-visible branch that other developers pull from, as git will be confused by history that disappears in this way. I do not think this is a good explanation. For example, if we do this: (1) I build a series and push it out. ---o---o---o---j (2) Alice clones from me, and builds two commits on top of it. ---o---o---o---j---a---a (3) I rewind one and build a few, and push them out. ---o---o---o...j \ h---h---h---h (4) Alice pulls from me again: ---o---o---o---j---a---a---* \ / h---h---h---h Contrary to the description, git will happily have Alice merge between the two branches, and never gets confused. Maybe I did not want to have 'j' because it was an incomplete solution to some problem, and Alice may have fixed it up with her changes, while I abandoned that approach I started with 'j', and worked on something completely unrelated in the four 'h' commits. In such a case, the merge Alice would make would be very sensible, and after she makes the merge if I pull from her, the world will be perfect. I started something with 'j' and dropped the ball, Alice picked it up and perfected it while I went on to work on something else with 'h'. This would be a perfect example of distributed parallel collaboration. There is nothing confused about it. The case the rewinding becomes problematic is if the work done in 'h' tries to solve the same problem as 'j' tried to solve in a different way. Then the merge forced on Alice would make her pick between my previous attempt with her fixups (j+a) and my second attempt (h). If 'a' commits were to fix up what 'j' started, presumably Alice already studied and knows enough about the problem so she should be able to make an informed decision to pick between what 'j+a' and 'h' do. A lot worse case is if Alice's work is not at all related to what 'j' wanted to do (she did not mean to pick up from where I left off -- she just wanted to work on something different). Then she would not be familiar enough with what 'j' and 'h' tried to achieve, and I'd be forcing her to pick between the two. Of course if she can make the right decision, then again that is a perfect example of distributed collaboration, but that does not change the fact that I'd be forcing her to clean up my mess. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-02Tutorial: fix asciidoc formatting of "git add" section.Libravatar Junio C Hamano1-18/+18
Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-28[PATCH] Rename git-repo-config to git-config.Libravatar Tom Prince1-4/+4
Signed-off-by: Tom Prince <tom.prince@ualberta.net> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-16tutorial: shorthand for remotes but show distributed nature of gitLibravatar Junio C Hamano1-19/+24
* Promiscous pull shows the distributed nature of git better. * Add a new step after that to teach "remote add". * Highlight that with the shorthand defined you will get remote tracking branches for free. * Fix Alice's workflow. Signed-off-by: Santi Béjar <sbejar@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-16tutorial: Use only separate layoutLibravatar Santi Béjar1-13/+13
Then the newbies only have to understand one layout. Signed-off-by: Santi Béjar <sbejar@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-14some doc updatesLibravatar Nicolas Pitre1-11/+9
1) talk about "git merge" instead of "git pull ." 2) suggest "git repo-config" instead of directly editing config files 3) echo "URL: blah" > .git/remotes/foo is obsolete and should be "git repo-config remote.foo.url blah" 4) support for partial URL prefix has been removed (see commit ea560e6d64374ec1f6c163c276319a3da21a1345) so drop mention of it. Signed-off-by: Nicolas Pitre <nico@cam.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-07"init-db" can really be just "init"Libravatar Nicolas Pitre1-1/+1
Make "init" the equivalent of "init-db". This should make first GIT impression a little more friendly. Signed-off-by: Nicolas Pitre <nico@cam.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-06Documentation: tutorial editingLibravatar J. Bruce Fields1-6/+10
Edit for conciseness. Add a "Making changes" section header. When possible, make sure that stuff in text boxes could be entered literally. (Don't use "..." unless we want a user to type that.) Move 'commit -a' example into a literal code section, clarify that it finds modified files automatically. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-03Documentation/tutorial: misc updatesLibravatar Santi Béjar1-4/+13
- Teach how to delete a branch with "git branch -d name". - Usually a commit has one parent; merge has more. - Teach "git show" instead of "git cat-file -p". Signed-off-by: Santi Béjar <sbejar@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-03tutorial: misc updates.Libravatar Junio C Hamano1-7/+17
Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-12-31Documentation: update tutorial's discussion of originLibravatar J. Bruce Fields1-10/+15
Update tutorial's discussion of origin branch to reflect new defaults, and include a brief mention of git-repo-config. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-12-15Provide more meaningful output from 'git init-db'.Libravatar Shawn O. Pearce1-1/+1
Back in the old days of Git when people messed around with their GIT_DIR environment variable more often it was nice to know whether or not git-init-db created a .git directory or used GIT_DIR. As most users at that time were rather technical UNIXy folk the message "defaulting to local storage area" made sense to some and seemed reasonable. But it doesn't really convey any meaning to the new Git user, as they don't know what a 'local storage area is' nor do they know enough about Git to care. It also really doesn't tell the experienced Git user a whole lot about the command they just ran, especially if they might be reinitializing an existing repository (e.g. to update hooks). So now we print out what we did ("Initialized empty" or "Reinitialized existing"), what type of repository ("" or "shared"), and what location the repository will be in ("$GIT_DIR"). Suggested in part by Andy Parkins in his Git 'niggles' list (<200612132237.10051.andyparkins@gmail.com>). Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-12-04make 'git add' a first class user friendly interface to the indexLibravatar Nicolas Pitre1-6/+40
This brings the power of the index up front using a proper mental model without talking about the index at all. See for example how all the technical discussion has been evacuated from the git-add man page. Any content to be committed must be added together. Whether that content comes from new files or modified files doesn't matter. You just need to "add" it, either with git-add, or by providing git-commit with -a (for already known files only of course). No need for a separate command to distinguish new vs modified files please. That would only screw the mental model everybody should have when using GIT. Signed-off-by: Nicolas Pitre <nico@cam.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-11-29Merge branch 'maint'Libravatar Junio C Hamano1-5/+24
* branch 'maint': Document git-repo-config --bool/--int options. tutorial: talk about user.name early and don't start with commit -a git-blame: fix rev parameter handling.
2006-11-29tutorial: talk about user.name early and don't start with commit -aLibravatar Junio C Hamano1-5/+24
Introducing yourself to git early would be a good idea; otherwise the user may not find the mistake until much later when "git log" is learned. Teaching "commit -a" without saying that it is a shortcut for listing the paths to commit leaves the user puzzled. Teach the form with explicit paths first. Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-11-25Documentation: clarify tutorial pull/merge discussionLibravatar J. Bruce Fields1-15/+26
Attempt to clarify somewhat the difference between pull and merge, and give a little more details on the pull syntax. I'm still not happy with this section: the explanation of the origin branch isn't great, but maybe that should be left alone pending the use-separate-remotes change; and we need to explain how to set up a public repository and push to it. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-11-21Doc: Make comment about merging in tutorial.txt more clearLibravatar Paolo Ciarrocchi1-1/+1
Rephrased a sentence in order to make more clear the concept of pull . branch Signed-off-by: Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-06-07Some doc typo fixesLibravatar Francis Daly1-1/+1
All should be clear enough, except perhaps committish / commitish. I just kept the more-used one within the current docs. [jc: with rephrasing of check-ref-format description later discussed on the list] Signed-off-by: Francis Daly <francis@daoine.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-06-03Documentation: Spelling fixesLibravatar Horst H. von Brand1-4/+4
Signed-off-by: Horst H. von Brand <vonbrand@inf.utfsm.cl> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-29documentation: add brief mention of cat-file to tutorial part ILibravatar J. Bruce Fields1-1/+7
I'd rather avoid git cat-file so early on, but the git-cat-file -p old-commit:/path/to/file trick is too useful.... Also fix a nearby typo while we're at it. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-29documentation: mention gitk font adjustment in tutorialLibravatar J. Bruce Fields1-1/+3
Kind of silly, but the font I get by default in gitk makes it mostly unusable for me, so this is the first thing I'd want to know about. (But maybe there's a better suggestion than just Ctrl-='ing until satisfied.) Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-21tutorial: add discussion of index file, object databaseLibravatar J. Bruce Fields1-6/+22
Add a sequel to tutorial.txt which discusses the index file and the object database. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-21tutorial: expanded discussion of commit historyLibravatar J. Bruce Fields1-53/+112
Expand the history-browsing section of the tutorial a bit, in part to address Junio's suggestion that we mention "git grep" and Linus's complaint that people are missing the flexibility of the commandline interfaces for selecting commits. This reads a little more like a collection of examples than a "tutorial", but maybe that's what people need at this point. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-21tutorial: replace "whatchanged" by "log"Libravatar J. Bruce Fields1-6/+6
Junio suggested changing references to git-whatchanged to git-log. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-03-04AsciiDoc fix for tutorialLibravatar Francis Daly1-1/+1
RE \^.+\^ becomes <sup>. Not wanted here Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-01-22Documentation: finishing touches to the new tutorial.Libravatar Junio C Hamano1-1/+1
We forgot to update the primary link from git.html leading to the tutorial, and also forgot to build and install the renamed core-tutorial document. Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-01-22New tutorialLibravatar J. Bruce Fields1-1703/+286
The current Documentation/tutorial.txt concentrates on the lower-level git interfaces. So it's useful to people developing alternative porcelains, to advanced users, etc., but not so much to beginning users. I think it makes sense for the main tutorial to address those beginnning users, so with this patch I'm proposing that we move Documentation/tutorial.txt to Documentation/core-tutorial.txt and replace it by a new tutorial. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-01-15show-branch: make the current branch and merge commits stand out.Libravatar Junio C Hamano1-24/+25
This changes the character used to mark the commits that is on the branch from '+' to '*' for the current branch, to make it stand out. Also we show '-' for merge commits. When you have a handful branches with relatively long diversion, it is easier to see which one is the current branch this way. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-12-24Tutorial: mention shared repository management.Libravatar Junio C Hamano1-0/+18
Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-12-20A shared repository should be writable by members.Libravatar Junio C Hamano1-1/+3
Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-12-17Documentation: HTTP needs update-server-info.Libravatar Junio C Hamano1-7/+11
Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-12-14Documentation: tutorialLibravatar Junio C Hamano1-0/+6
At the beginning of tutorial, refer the reader to everyday if she has not done so yet. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-12-13Documentation: not learning core git commands.Libravatar Junio C Hamano1-1/+19
The initial section of tutorial was too heavy on internal workings for the first-time readers, so rewrite the introductory section of git(7) to start with "not learning core git commands" section and refer them to README to grasp the basic concepts, then Everyday to give overview with task/role oriented examples for minimum set of commands, and finally the tutorial. Also add to existing note in the tutorial that many too technical descriptions can be skipped by a casual reader. I initially started to review the tutorial, with the objective of ripping out the detailed technical information altogether, but I found that the level of details in the initial couple of sections that talk about refs and the object database in a hands-on fashion was about rigth, and left all of them there. I feel that reading about fsck-index and repack is too abstract without being aware of these directories and files. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-12-07Documentation(tutorial): adjust merge example to the new merge world order.Libravatar Junio C Hamano1-11/+12
Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-12-05Documentation: shared repository management in tutorial.Libravatar Junio C Hamano1-0/+35
The branch policy script I outlined was improved and polished by Carl and posted on the list twice since then. It is a shame not to pick it up, so replace the original outline in howto/update-hook-example.txt with the latest from Carl. Also talk about setting up git-shell to allow git-push/git-fetch only SSH access to a shared repository host in the tutorial. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-30Tutorial: adjust merge example to recursive strategy.Libravatar Junio C Hamano1-8/+7
Current default, merge-recursive, gives slightly different message while working from merge-resolve which was used to prepare the illustration in the tutorial. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-21tutorial: setting up a tree for subsystem maintainersLibravatar Junio C Hamano1-1/+4
The "copying over packs" step is to prevent the objects available in upstream repository to get expanted in the subsystem maintainer tree, and is still valid if the upstream repository do not live on the same machine. But if they are on the same machine using objects/info/alternates is cleaner. Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-11Change 'cache' to 'index' in the docsLibravatar Lukas_Sandström1-3/+3
This patch makes the documentation refer to the index as index instead of cache, but some references still remain. (e.g. git-update-index.txt) Signed-off-by: Lukas Sandström <lukass@etek.chalmers.se> Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-11-08Use consistent shell prompts and example style.Libravatar Jon Loeliger1-88/+138
Signed-off-by: Jon Loeliger <jdl@freescale.com> Signed-off-by: Junio C Hamano <junkio@cox.net>