$ man git-diff
------------------------------------------------
+It is a good idea to introduce yourself to git before doing any
+operation. The easiest way to do so is:
+
+------------------------------------------------
+$ cat >~/.gitconfig <<\EOF
+[user]
+ name = Your Name Comes Here
+ email = you@yourdomain.example.com
+EOF
+------------------------------------------------
+
+
Importing a new project
-----------------------
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
+every file under the current directory with (notice the dot '.'
+that means the current directory):
------------------------------------------------
$ git add .
Finally,
------------------------------------------------
-$ git commit -a
+$ git commit
------------------------------------------------
will prompt you for a commit message, then record the current state
to review your changes. When you're done,
------------------------------------------------
-$ git commit -a
+$ git commit file1 file2...
------------------------------------------------
will again prompt your for a message describing the change, and then
-record the new versions of the modified files.
+record the new versions of the files you listed. It is cumbersome
+to list all files and you can say `-a` (which stands for 'all')
+instead.
+
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
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)
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
-------------------------------------------------
+Git tracks content not files
+----------------------------
+
+With git you have to explicitly "add" all the changed _content_ you
+want to commit together. This can be done in a few different ways:
-then commit as usual. No special command is required when removing a
-file; just remove it, then commit.
+1) By using 'git add <file_spec>...'
+
+ This can be performed multiple times before a commit. Note that this
+ is not only for adding new files. Even modified files must be
+ added to the set of changes about to be committed. The "git status"
+ command gives you a summary of what is included so far for the
+ next commit. When done you should use the 'git commit' command to
+ make it real.
+
+ Note: don't forget to 'add' a file again if you modified it after the
+ first 'add' and before 'commit'. Otherwise only the previous added
+ state of that file will be committed. This is because git tracks
+ content, so what you're really 'add'ing to the commit is the *content*
+ of the file in the state it is in when you 'add' it.
+
+2) By using 'git commit -a' directly
+
+ This is a quick way to automatically 'add' the content from all files
+ that were modified since the previous commit, and perform the actual
+ commit without having to separately 'add' them beforehand. This will
+ not add content from new files i.e. files that were never added before.
+ Those files still have to be added explicitly before performing a
+ commit.
+
+But here's a twist. If you do 'git commit <file1> <file2> ...' then only
+the changes belonging to those explicitly specified files will be
+committed, entirely bypassing the current "added" changes. Those "added"
+changes will still remain available for a subsequent commit though.
+
+However, for normal usage you only have to remember 'git add' + 'git commit'
+and/or 'git commit -a'.
+
+
+Viewing the changelog
+---------------------
At any point you can view the history of your changes using
------------------------------------------------
at this point the two branches have diverged, with different changes
-made in each. To merge the changes made in the two branches, run
+made in each. To merge the changes made in experimental into master, run
------------------------------------------------
$ git pull . experimental
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.
+project, possessing its own copy of the original project's history.
Bob then makes some changes and commits them:
------------------------------------------------
$ cd /home/alice/project
-$ git pull /home/bob/myrepo
+$ git pull /home/bob/myrepo master
------------------------------------------------
-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 the changes from Bob's "master" branch into Alice's
+current branch. If Alice has made her own changes in the meantime,
+then she may need to manually fix any conflicts. (Note that the
+"master" argument in the above command is actually unnecessary, as it
+is the default.)
-This merges Bob's changes into her repository; "git log" 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.
+The "pull" command thus performs two operations: it fetches changes
+from a remote branch, then merges them into the current branch.
-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:
+You can perform the first operation alone using the "git fetch"
+command. For example, Alice could create a temporary branch just to
+track Bob's changes, without merging them with her own, using:
-------------------------------------
$ 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
+named bob-incoming. Then
-------------------------------------
$ git log -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:
+After examining those changes, and possibly fixing things, Alice
+could pull the changes into her master branch:
-------------------------------------
$ git checkout master
The last command is a pull from the "bob-incoming" branch in Alice's
own repository.
+Alice could also perform both steps at once with:
+
+-------------------------------------
+$ git pull /home/bob/myrepo master:bob-incoming
+-------------------------------------
+
+This is just like the "git pull /home/bob/myrepo master" that we saw
+before, except that it also stores the unmerged changes from bob's
+master branch in bob-incoming before merging them into Alice's
+current branch. Note that git pull always merges into the current
+branch, regardless of what else is given on the commandline.
+
Later, Bob can update his repo with Alice's latest changes using
-------------------------------------
$ git branch stable v2.5 # start a new branch named "stable" based
# at v2.5
$ git reset --hard HEAD^ # reset your current branch and working
- # directory its state at HEAD^
+ # directory to its state at HEAD^
-------------------------------------
Be careful with that last command: in addition to losing any changes
$ git grep "hello" v2.5
-------------------------------------
-searches for all occurences of "hello" in v2.5.
+searches for all occurrences of "hello" in v2.5.
If you leave out the commit name, git grep will search any of the
files it manages in your current directory. So
smart enough to perform a close-to-optimal search even in the
case of complex non-linear history with lots of merged branches.
- * link:everyday.html[Everday GIT with 20 Commands Or So]
+ * link:everyday.html[Everyday GIT with 20 Commands Or So]
* link:cvs-migration.html[git for CVS users].