@@ -933,7 +933,14 @@ def checkout(self, paths=None, force=False, fprogress=lambda *args: None, **kwar
 			If one of files or directories do not exist in the index
 			( as opposed to the	 original git command who ignores them ).
 			Raise GitCommandError if error lines could not be parsed - this truly is
-			an exceptional state"""
+			an exceptional state
+			
+		.. note:: The checkout is limited to checking out the files in the 
+			index. Files which are not in the index anymore and exist in 
+			the working tree will not be deleted. This behaviour is fundamentally
+			different to *head.checkout*, i.e. if you want git-checkout like behaviour, 
+			use head.checkout instead of index.checkout.
+			"""
 		args = ["--index"]
 		if force:
 			args.append("--force")
@@ -1055,7 +1062,7 @@ def reset(self, commit='HEAD', working_tree=False, paths=None, head=False, **kwa
 			If False, the working tree will not be touched
 			Please note that changes to the working copy will be discarded without
 			warning !
-
+			
 		:param head:
 			If True, the head will be set to the given commit. This is False by default,
 			but if True, this method behaves like HEAD.reset.
@@ -1067,6 +1074,11 @@ def reset(self, commit='HEAD', working_tree=False, paths=None, head=False, **kwa
 
 		:param kwargs:
 			Additional keyword arguments passed to git-reset
+			
+		.. note:: IndexFile.reset, as opposed to HEAD.reset, will not delete anyfiles
+			in order to maintain a consistent working tree. Instead, it will just
+			checkout the files according to their state in the index.
+			If you want git-reset like behaviour, use *HEAD.reset* instead.
 
 		:return: self """
 		# what we actually want to do is to merge the tree into our existing
@@ -1098,7 +1110,7 @@ def reset(self, commit='HEAD', working_tree=False, paths=None, head=False, **kwa
 		# END handle working tree
 
 		if head:
-			self.repo.head.commit = self.repo.commit(commit)
+			self.repo.head.set_commit(self.repo.commit(commit), logmsg="%s: Updating HEAD" % commit)
 		# END handle head change
 
 		return self
 
@@ -356,7 +356,7 @@ def create_from_tree(cls, repo, tree, message, parent_commits=None, head=False):
 				# Happens on first commit
 				import git.refs
 				master = git.refs.Head.create(repo, repo.head.ref, commit=new_commit, logmsg="commit (initial): %s" % message)
-				repo.head.reference = master
+				repo.head.set_reference(master, logmsg='commit: Switching to %s' % master)
 			# END handle empty repositories
 		# END advance head handling 
 
 
@@ -344,7 +344,7 @@ def update(self, recursive=False, init=True, to_latest_revision=False):
 				# END initial checkout + branch creation
 
 				# make sure HEAD is not detached
-				mrepo.head.ref = local_branch
+				mrepo.head.set_reference(local_branch, logmsg="submodule: attaching head to %s" % local_branch)
 				mrepo.head.ref.set_tracking_branch(remote_branch)
 			except IndexError:
 				print >> sys.stderr, "Warning: Failed to checkout tracking branch %s" % self.branch_path 
 
@@ -568,7 +568,7 @@ def test_rev_parse(self):
 		assert rev_parse('@{1}') != head.commit
 
 		# position doesn't exist
-		self.failUnlessRaises(BadObject, rev_parse, '@{10000}')
+		self.failUnlessRaises(IndexError, rev_parse, '@{10000}')
 
 		# currently, nothing more is supported
 		self.failUnlessRaises(NotImplementedError, rev_parse, "@{1 week ago}")