Support --cached in RmCommand

Also extend documentation and add examples.

Bug: 395599
Change-Id: Id1ddbc9da787472f82e58834092bc073224b262b
Signed-off-by: Chris Aniszczyk <zx@twitter.com>

org.eclipse.jgit.test/tst/org/eclipse/jgit/api/RmCommandTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2010, Chris Aniszczyk <caniszczyk@gmail.com>
+ * Copyright (C) 2010, 2012 Chris Aniszczyk <caniszczyk@gmail.com>
  * and other copyright owners as documented in the project's IP log.
  *
  * This program and the accompanying materials are made available
@@ -43,7 +43,9 @@
 package org.eclipse.jgit.api;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
 
+import java.io.File;
 import java.io.IOException;
 
 import org.eclipse.jgit.api.errors.GitAPIException;
@@ -80,4 +82,16 @@ public class RmCommandTest extends RepositoryTestCase {
 		assertEquals("", indexState(CONTENT));
 	}
 
+	@Test
+	public void testRemoveCached() throws Exception {
+		File newFile = writeTrashFile("new.txt", "new");
+		git.add().addFilepattern(newFile.getName()).call();
+		assertEquals("[new.txt, mode:100644][test.txt, mode:100644]",
+				indexState(0));
+
+		git.rm().setCached(true).addFilepattern(newFile.getName()).call();
+
+		assertEquals("[test.txt, mode:100644]", indexState(0));
+		assertTrue("File should not have been removed.", newFile.exists());
+	}
 }

org.eclipse.jgit/src/org/eclipse/jgit/api/RmCommand.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2010, Chris Aniszczyk <caniszczyk@gmail.com>
+ * Copyright (C) 2010, 2012 Chris Aniszczyk <caniszczyk@gmail.com>
  * and other copyright owners as documented in the project's IP log.
  *
  * This program and the accompanying materials are made available
@@ -61,10 +61,27 @@ import org.eclipse.jgit.treewalk.TreeWalk;
 import org.eclipse.jgit.treewalk.filter.PathFilterGroup;
 
 /**
- * A class used to execute a {@code Rm} command. It has setters for all
- * supported options and arguments of this command and a {@link #call()} method
- * to finally execute the command. Each instance of this class should only be
- * used for one invocation of the command (means: one call to {@link #call()})
+ * Remove files from the index and working directory (or optionally only from
+ * the index).
+ * <p>
+ * It has setters for all supported options and arguments of this command and a
+ * {@link #call()} method to finally execute the command. Each instance of this
+ * class should only be used for one invocation of the command (means: one call
+ * to {@link #call()}).
+ * <p>
+ * Examples (<code>git</code> is a {@link Git} instance):
+ * <p>
+ * Remove file "test.txt" from both index and working directory:
+ *
+ * <pre>
+ * git.rm().addFilepattern(&quot;test.txt&quot;).call();
+ * </pre>
+ * <p>
+ * Remove file "new.txt" from the index (but not from the working directory):
+ *
+ * <pre>
+ * git.rm().setCached(true).addFilepattern(&quot;new.txt&quot;).call();
+ * </pre>
  *
  * @see <a href="http://www.kernel.org/pub/software/scm/git/docs/git-rm.html"
  *      >Git documentation about Rm</a>
@@ -73,6 +90,9 @@ public class RmCommand extends GitCommand<DirCache> {
 
 	private Collection<String> filepatterns;
 
+	/** Only remove files from index, not from working directory */
+	private boolean cached = false;
+
 	/**
 	 *
 	 * @param repo
@@ -93,6 +113,21 @@ public class RmCommand extends GitCommand<DirCache> {
 		return this;
 	}
 
+	/**
+	 * Only remove the specified files from the index.
+	 *
+	 * @param cached
+	 *            true if files should only be removed from index, false if
+	 *            files should also be deleted from the working directory
+	 * @return {@code this}
+	 * @since 2.2
+	 */
+	public RmCommand setCached(boolean cached) {
+		checkCallable();
+		this.cached = cached;
+		return this;
+	}
+
 	/**
 	 * Executes the {@code Rm} command. Each instance of this class should only
 	 * be used for one invocation of the command. Don't call this method twice
@@ -118,15 +153,17 @@ public class RmCommand extends GitCommand<DirCache> {
 			tw.addTree(new DirCacheBuildIterator(builder));
 
 			while (tw.next()) {
-				final File path = new File(repo.getWorkTree(),
-						tw.getPathString());
+				if (!cached) {
 					final FileMode mode = tw.getFileMode(0);
 					if (mode.getObjectType() == Constants.OBJ_BLOB) {
+						final File path = new File(repo.getWorkTree(),
+								tw.getPathString());
 						// Deleting a blob is simply a matter of removing
 						// the file or symlink named by the tree entry.
 						delete(path);
 					}
 				}
+			}
 			builder.commit();
 			setCallable(false);
 		} catch (IOException e) {