diff options
Diffstat (limited to 'Documentation/tutorial.txt')
| -rw-r--r-- | Documentation/tutorial.txt | 404 |
1 files changed, 0 insertions, 404 deletions
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt deleted file mode 100644 index fa79b016c7..0000000000 --- a/Documentation/tutorial.txt +++ /dev/null @@ -1,404 +0,0 @@ -A tutorial introduction to git -============================== - -This tutorial explains how to import a new project into git, make -changes to it, and share changes with other developers. - -First, note that you can get documentation for a command such as "git -diff" with: - ------------------------------------------------- -$ man git-diff ------------------------------------------------- - -Importing a new project ------------------------ - -Assume you have a tarball project.tar.gz with your initial work. You -can place it under git revision control as follows. - ------------------------------------------------- -$ tar xzf project.tar.gz -$ cd project -$ git init-db ------------------------------------------------- - -Git will reply - ------------------------------------------------- -defaulting to local storage area ------------------------------------------------- - -You've now initialized the working directory--you may notice a new -directory created, named ".git". Tell git that you want it to track -every file under the current directory with - ------------------------------------------------- -$ git add . ------------------------------------------------- - -Finally, - ------------------------------------------------- -$ git commit -a ------------------------------------------------- - -will prompt you for a commit message, then record the current state -of all the files to the repository. - -Try modifying some files, then run - ------------------------------------------------- -$ git diff ------------------------------------------------- - -to review your changes. When you're done, - ------------------------------------------------- -$ git commit -a ------------------------------------------------- - -will again prompt your for a message describing the change, and then -record the new versions of the modified files. - -A note on commit messages: Though not required, it's a good idea to -begin the commit message with a single short (less than 50 character) -line summarizing the change, followed by a blank line and then a more -thorough description. Tools that turn commits into email, for -example, use the first line on the Subject line and the rest of the -commit in the body. - -To add a new file, first create the file, then - ------------------------------------------------- -$ git add path/to/new/file ------------------------------------------------- - -then commit as usual. No special command is required when removing a -file; just remove it, then commit. - -At any point you can view the history of your changes using - ------------------------------------------------- -$ git whatchanged ------------------------------------------------- - -If you also want to see complete diffs at each step, use - ------------------------------------------------- -$ git whatchanged -p ------------------------------------------------- - -Managing branches ------------------ - -A single git repository can maintain multiple branches of -development. To create a new branch named "experimental", use - ------------------------------------------------- -$ git branch experimental ------------------------------------------------- - -If you now run - ------------------------------------------------- -$ git branch ------------------------------------------------- - -you'll get a list of all existing branches: - ------------------------------------------------- - experimental -* master ------------------------------------------------- - -The "experimental" branch is the one you just created, and the -"master" branch is a default branch that was created for you -automatically. The asterisk marks the branch you are currently on; -type - ------------------------------------------------- -$ git checkout experimental ------------------------------------------------- - -to switch to the experimental branch. Now edit a file, commit the -change, and switch back to the master branch: - ------------------------------------------------- -(edit file) -$ git commit -a -$ git checkout master ------------------------------------------------- - -Check that the change you made is no longer visible, since it was -made on the experimental branch and you're back on the master branch. - -You can make a different change on the master branch: - ------------------------------------------------- -(edit file) -$ git commit -a ------------------------------------------------- - -at this point the two branches have diverged, with different changes -made in each. To merge the changes made in the two branches, run - ------------------------------------------------- -$ git pull . experimental ------------------------------------------------- - -If the changes don't conflict, you're done. If there are conflicts, -markers will be left in the problematic files showing the conflict; - ------------------------------------------------- -$ git diff ------------------------------------------------- - -will show this. Once you've edited the files to resolve the -conflicts, - ------------------------------------------------- -$ git commit -a ------------------------------------------------- - -will commit the result of the merge. Finally, - ------------------------------------------------- -$ gitk ------------------------------------------------- - -will show a nice graphical representation of the resulting history. - -If you develop on a branch crazy-idea, then regret it, you can always -delete the branch with - -------------------------------------- -$ git branch -D crazy-idea -------------------------------------- - -Branches are cheap and easy, so this is a good way to try something -out. - -Using git for collaboration ---------------------------- - -Suppose that Alice has started a new project with a git repository in -/home/alice/project, and that Bob, who has a home directory on the -same machine, wants to contribute. - -Bob begins with: - ------------------------------------------------- -$ git clone /home/alice/project myrepo ------------------------------------------------- - -This creates a new directory "myrepo" containing a clone of Alice's -repository. The clone is on an equal footing with the original -project, posessing its own copy of the original project's history. - -Bob then makes some changes and commits them: - ------------------------------------------------- -(edit files) -$ git commit -a -(repeat as necessary) ------------------------------------------------- - -When he's ready, he tells Alice to pull changes from the repository -at /home/bob/myrepo. She does this with: - ------------------------------------------------- -$ cd /home/alice/project -$ git pull /home/bob/myrepo ------------------------------------------------- - -This actually pulls changes from the branch in Bob's repository named -"master". Alice could request a different branch by adding the name -of the branch to the end of the git pull command line. - -This merges Bob's changes into her repository; "git whatchanged" will -now show the new commits. If Alice has made her own changes in the -meantime, then Bob's changes will be merged in, and she will need to -manually fix any conflicts. - -A more cautious Alice might wish to examine Bob's changes before -pulling them. She can do this by creating a temporary branch just -for the purpose of studying Bob's changes: - -------------------------------------- -$ git fetch /home/bob/myrepo master:bob-incoming -------------------------------------- - -which fetches the changes from Bob's master branch into a new branch -named bob-incoming. (Unlike git pull, git fetch just fetches a copy -of Bob's line of development without doing any merging). Then - -------------------------------------- -$ git whatchanged -p master..bob-incoming -------------------------------------- - -shows a list of all the changes that Bob made since he branched from -Alice's master branch. - -After examing those changes, and possibly fixing things, Alice can -pull the changes into her master branch: - -------------------------------------- -$ git checkout master -$ git pull . bob-incoming -------------------------------------- - -The last command is a pull from the "bob-incoming" branch in Alice's -own repository. - -Later, Bob can update his repo with Alice's latest changes using - -------------------------------------- -$ git pull -------------------------------------- - -Note that he doesn't need to give the path to Alice's repository; -when Bob cloned Alice's repository, git stored the location of her -repository in the file .git/remotes/origin, and that location is used -as the default for pulls. - -Bob may also notice a branch in his repository that he didn't create: - -------------------------------------- -$ git branch -* master - origin -------------------------------------- - -The "origin" branch, which was created automatically by "git clone", -is a pristine copy of Alice's master branch; Bob should never commit -to it. - -If Bob later decides to work from a different host, he can still -perform clones and pulls using the ssh protocol: - -------------------------------------- -$ git clone alice.org:/home/alice/project myrepo -------------------------------------- - -Alternatively, git has a native protocol, or can use rsync or http; -see gitlink:git-pull[1] for details. - -Git can also be used in a CVS-like mode, with a central repository -that various users push changes to; see gitlink:git-push[1] and -link:cvs-migration.html[git for CVS users]. - -Keeping track of history ------------------------- - -Git history is represented as a series of interrelated commits. The -most recent commit in the currently checked-out branch can always be -referred to as HEAD, and the "parent" of any commit can always be -referred to by appending a caret, "^", to the end of the name of the -commit. So, for example, - -------------------------------------- -git diff HEAD^ HEAD -------------------------------------- - -shows the difference between the most-recently checked-in state of -the tree and the previous state, and - -------------------------------------- -git diff HEAD^^ HEAD^ -------------------------------------- - -shows the difference between that previous state and the state two -commits ago. Also, HEAD~5 can be used as a shorthand for HEAD{caret}{caret}{caret}{caret}{caret}, -and more generally HEAD~n can refer to the nth previous commit. -Commits representing merges have more than one parent, and you can -specify which parent to follow in that case; see -gitlink:git-rev-parse[1]. - -The name of a branch can also be used to refer to the most recent -commit on that branch; so you can also say things like - -------------------------------------- -git diff HEAD experimental -------------------------------------- - -to see the difference between the most-recently committed tree in -the current branch and the most-recently committed tree in the -experimental branch. - -But you may find it more useful to see the list of commits made in -the experimental branch but not in the current branch, and - -------------------------------------- -git whatchanged HEAD..experimental -------------------------------------- - -will do that, just as - -------------------------------------- -git whatchanged experimental..HEAD -------------------------------------- - -will show the list of commits made on the HEAD but not included in -experimental. - -You can also give commits convenient names of your own: after running - -------------------------------------- -$ git-tag v2.5 HEAD^^ -------------------------------------- - -you can refer to HEAD^^ by the name "v2.5". If you intend to share -this name with other people (for example, to identify a release -version), you should create a "tag" object, and perhaps sign it; see -gitlink:git-tag[1] for details. - -You can revisit the old state of a tree, and make further -modifications if you wish, using git branch: the command - -------------------------------------- -$ git branch stable-release v2.5 -------------------------------------- - -will create a new branch named "stable-release" starting from the -commit which you tagged with the name v2.5. - -You can reset the state of any branch to an earlier commit at any -time with - -------------------------------------- -$ git reset --hard v2.5 -------------------------------------- - -This will remove all later commits from this branch and reset the -working tree to the state it had when the given commit was made. If -this branch is the only branch containing the later commits, those -later changes will be lost. 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. - -Next Steps ----------- - -Some good commands to explore next: - - * gitlink:git-diff[1]: This flexible command does much more than - we've seen in the few examples above. - - * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert - series of git commits into emailed patches, and vice versa, - useful for projects such as the linux kernel which rely heavily - on emailed patches. - - * gitlink:git-bisect[1]: When there is a regression in your - project, one way to track down the bug is by searching through - the history to find the exact commit that's to blame. Git bisect - can help you perform a binary search for that commit. It is - smart enough to perform a close-to-optimal search even in the - case of complex non-linear history with lots of merged branches. - -Other good starting points include link:everyday.html[Everday GIT -with 20 Commands Or So] and link:cvs-migration.html[git for CVS -users]. Also, link:core-tutorial.html[A short git tutorial] gives an -introduction to lower-level git commands for advanced users and -developers. |