From 93f9cc675d6ca9d9170f72def005ecffd9590e9c Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Fri, 18 May 2007 00:51:42 -0400 Subject: [PATCH] tutorial: revise index introduction 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" --- Documentation/tutorial.txt | 94 ++++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 49 deletions(-) diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 8094172316..f55d4083ed 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -44,42 +44,67 @@ Initialized empty Git repository in .git/ ------------------------------------------------ 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 (note the '.') with: +directory created, named ".git". + +Next, tell git to take a snapshot of the contents of all files under the +current directory (note the '.'), with gitlink:git-add[1]: ------------------------------------------------ $ git add . ------------------------------------------------ -Finally, +This snapshot is now stored in a temporary staging area which git calls +the "index". You can permanently store the contents of the index in the +repository with gitlink:git-commit[1]: ------------------------------------------------ $ git commit ------------------------------------------------ -will prompt you for a commit message, then record the current state -of all the files to the repository. +This will prompt you for a commit message. You've now stored the first +version of your project in git. Making changes -------------- -Try modifying some files, then run +Modify some files, then add their updated contents to the index: ------------------------------------------------ -$ git diff +$ git add file1 file2 file3 ------------------------------------------------ -to review your changes. When you're done, tell git that you -want the updated contents of these files in the commit and then -make a commit, like this: +You are now ready to commit. You can see what is about to be committed +using gitlink:git-diff[1] with the --cached option: + +------------------------------------------------ +$ git diff --cached +------------------------------------------------ + +(Without --cached, gitlink:git-diff[1] will show you any changes that +you've made but not yet added to the index.) You can also get a brief +summary of the situation with gitlink:git-status[1]: + +------------------------------------------------ +$ git status +# On branch master +# Changes to be committed: +# (use "git reset HEAD ..." to unstage) +# +# modified: file1 +# modified: file2 +# modified: file3 +# +------------------------------------------------ + +If you need to make any further adjustments, do so now, and then add any +newly modified content to the index. Finally, commit your changes with: ------------------------------------------------ -$ git add file1 file2 file3 $ git commit ------------------------------------------------ This will again prompt your for a message describing the change, and then -record the new versions of the files you listed. +record a new version of the project. Alternatively, instead of running `git add` beforehand, you can use @@ -87,7 +112,8 @@ Alternatively, instead of running `git add` beforehand, you can use $ git commit -a ------------------------------------------------ -which will automatically notice modified (but not new) files. +which will automatically notice any modified (but not new) files, add +them to the index, and commit, all in one step. 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) @@ -96,45 +122,15 @@ 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. - 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: - -1) By using 'git add ...' - -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 'adding' 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 ...' 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'. - +Many revision control systems provide an "add" command that tells the +system to start tracking changes to a new file. Git's "add" command +does something simpler and more powerful: `git add` is used both for new +and newly modified files, and in both cases it takes a snapshot of the +given files and stages that content in the index, ready for inclusion in +the next commit. Viewing the changelog --------------------- -- 2.32.0.93.g670b81a890