@matheusbsbs / matheus-bagliano / commits / 93f9cc675d
Fork 0

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" <bfields@citi.umich.edu>

J. Bruce Fields committed May 18, 2007 at 00:51 UTC 93f9cc675d6ca9d9170f72def005ecffd9590e9c
1 file changed +45 -49
Documentation/tutorial.txt
+45 -49
@@ -44,42 +44,67 @@ Initialized empty Git repository in .git/
44 ------------------------------------------------
45
46 You've now initialized the working directory--you may notice a new
47 -directory created, named ".git". Tell git that you want it to track
48 -every file under the current directory (note the '.') with:
47 +directory created, named ".git".
48 +
49 +Next, tell git to take a snapshot of the contents of all files under the
50 +current directory (note the '.'), with gitlink:git-add[1]:
51
52 ------------------------------------------------
53 $ git add .
54 ------------------------------------------------
55
54 -Finally,
56 +This snapshot is now stored in a temporary staging area which git calls
57 +the "index". You can permanently store the contents of the index in the
58 +repository with gitlink:git-commit[1]:
59
60 ------------------------------------------------
61 $ git commit
62 ------------------------------------------------
63
60 -will prompt you for a commit message, then record the current state
61 -of all the files to the repository.
64 +This will prompt you for a commit message. You've now stored the first
65 +version of your project in git.
66
67 Making changes
68 --------------
69
66 -Try modifying some files, then run
70 +Modify some files, then add their updated contents to the index:
71
72 ------------------------------------------------
69 -$ git diff
73 +$ git add file1 file2 file3
74 ------------------------------------------------
75
72 -to review your changes. When you're done, tell git that you
73 -want the updated contents of these files in the commit and then
74 -make a commit, like this:
76 +You are now ready to commit. You can see what is about to be committed
77 +using gitlink:git-diff[1] with the --cached option:
78 +
79 +------------------------------------------------
80 +$ git diff --cached
81 +------------------------------------------------
82 +
83 +(Without --cached, gitlink:git-diff[1] will show you any changes that
84 +you've made but not yet added to the index.) You can also get a brief
85 +summary of the situation with gitlink:git-status[1]:
86 +
87 +------------------------------------------------
88 +$ git status
89 +# On branch master
90 +# Changes to be committed:
91 +# (use "git reset HEAD <file>..." to unstage)
92 +#
93 +# modified: file1
94 +# modified: file2
95 +# modified: file3
96 +#
97 +------------------------------------------------
98 +
99 +If you need to make any further adjustments, do so now, and then add any
100 +newly modified content to the index. Finally, commit your changes with:
101
102 ------------------------------------------------
77 -$ git add file1 file2 file3
103 $ git commit
104 ------------------------------------------------
105
106 This will again prompt your for a message describing the change, and then
82 -record the new versions of the files you listed.
107 +record a new version of the project.
108
109 Alternatively, instead of running `git add` beforehand, you can use
110
@@ -87,7 +112,8 @@ Alternatively, instead of running `git add` beforehand, you can use
112 $ git commit -a
113 ------------------------------------------------
114
90 -which will automatically notice modified (but not new) files.
115 +which will automatically notice any modified (but not new) files, add
116 +them to the index, and commit, all in one step.
117
118 A note on commit messages: Though not required, it's a good idea to
119 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
122 example, use the first line on the Subject: line and the rest of the
123 commit in the body.
124
99 -
125 Git tracks content not files
126 ----------------------------
127
103 -With git you have to explicitly "add" all the changed _content_ you
104 -want to commit together. This can be done in a few different ways:
105 -
106 -1) By using 'git add <file_spec>...'
107 -
108 -This can be performed multiple times before a commit. Note that this
109 -is not only for adding new files. Even modified files must be
110 -added to the set of changes about to be committed. The "git status"
111 -command gives you a summary of what is included so far for the
112 -next commit. When done you should use the 'git commit' command to
113 -make it real.
114 -
115 -Note: don't forget to 'add' a file again if you modified it after the
116 -first 'add' and before 'commit'. Otherwise only the previous added
117 -state of that file will be committed. This is because git tracks
118 -content, so what you're really 'adding' to the commit is the *content*
119 -of the file in the state it is in when you 'add' it.
120 -
121 -2) By using 'git commit -a' directly
122 -
123 -This is a quick way to automatically 'add' the content from all files
124 -that were modified since the previous commit, and perform the actual
125 -commit without having to separately 'add' them beforehand. This will
126 -not add content from new files i.e. files that were never added before.
127 -Those files still have to be added explicitly before performing a
128 -commit.
129 -
130 -But here's a twist. If you do 'git commit <file1> <file2> ...' then only
131 -the changes belonging to those explicitly specified files will be
132 -committed, entirely bypassing the current "added" changes. Those "added"
133 -changes will still remain available for a subsequent commit though.
134 -
135 -However, for normal usage you only have to remember 'git add' + 'git commit'
136 -and/or 'git commit -a'.
137 -
128 +Many revision control systems provide an "add" command that tells the
129 +system to start tracking changes to a new file. Git's "add" command
130 +does something simpler and more powerful: `git add` is used both for new
131 +and newly modified files, and in both cases it takes a snapshot of the
132 +given files and stages that content in the index, ready for inclusion in
133 +the next commit.
134
135 Viewing the changelog
136 ---------------------