Subject: Re: Git terminology: remote, add, track, stage, etc.

From: Ramkumar Ramachandra <[email-masked]>
Date: Tue, 19 Oct 2010 23:21:12 +0530

Sverre Rabbelier writes:
> On Mon, Oct 18, 2010 at 15:45, Thore Husfeldt <[email-masked]> wrote:
> > The hyphenated *remote-tracking* is a lot better terminology already
> > (and sometimes even used in the documentation), because at least it
> > doesn't pretend to be a remote branch (`git branch -r`, of course,
> > still does).
> 
> What do you mean with the last part (about `git branch -r`)? The fact
> that 'refs/remotes' is not immutable?
> 
> > So that single hyphen already does some good, and should
> > be edited for consistency.
> 
> If we agree that "remote-tracking" is the way to go, a patch doing
> such editing would be very welcome.

-- 8< --
From a863e58d240956191c2fa9cbe992aaca5786730b Mon Sep 17 00:00:00 2001
From: Ramkumar Ramachandra <[email-masked]>
Date: Tue, 19 Oct 2010 22:42:05 +0530
Subject: [PATCH] Documentation: Consistently use the hyphenated "remote-tracking"

Replace instances of the term "remote tracking" with "remote-tracking"
in the documentation for clarity.

Reported-by: Thore Husfeldt <[email-masked]>
Signed-off-by: Ramkumar Ramachandra <[email-masked]>
---
 Documentation/config.txt           |    2 +-
 Documentation/fetch-options.txt    |    2 +-
 Documentation/git-gc.txt           |    2 +-
 Documentation/git-log.txt          |    2 +-
 Documentation/git-pull.txt         |    2 +-
 Documentation/git-remote.txt       |    4 ++--
 Documentation/gittutorial.txt      |    6 +++---
 Documentation/rev-list-options.txt |    2 +-
 Documentation/user-manual.txt      |    2 +-
 9 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 71ddb6c..736b22f 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -708,7 +708,7 @@ color.diff.<slot>::
 color.decorate.<slot>::
 	Use customized color for 'git log --decorate' output.  `<slot>` is one
 	of `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local
-	branches, remote tracking branches, tags, stash and HEAD, respectively.
+	branches, remote-tracking branches, tags, stash and HEAD, respectively.
 
 color.grep::
 	When set to `always`, always highlight matches.  When `false` (or
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 470ac31..a435c23 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -36,7 +36,7 @@ ifndef::git-pull[]
 
 -p::
 --prune::
-	After fetching, remove any remote tracking branches which
+	After fetching, remove any remote-tracking branches which
 	no longer exist	on the remote.
 endif::git-pull[]
 
diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
index 315f07e..d6d6833 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.txt
@@ -89,7 +89,7 @@ are not part of the current project most users will want to expire
 them sooner.  This option defaults to '30 days'.
 
 The above two configuration variables can be given to a pattern.  For
-example, this sets non-default expiry values only to remote tracking
+example, this sets non-default expiry values only to remote-tracking
 branches:
 
 ------------
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 6d40f00..ff41784 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -116,7 +116,7 @@ git log --follow builtin-rev-list.c::
 git log --branches --not --remotes=origin::
 
 	Shows all commits that are in any of local branches but not in
-	any of remote tracking branches for 'origin' (what you have that
+	any of remote-tracking branches for 'origin' (what you have that
 	origin doesn't).
 
 git log master --not --remotes=*/master::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index c50f7dc..33e8438 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -26,7 +26,7 @@ With `--rebase`, it runs 'git rebase' instead of 'git merge'.
 <repository> should be the name of a remote repository as
 passed to linkgit:git-fetch[1].  <refspec> can name an
 arbitrary remote ref (for example, the name of a tag) or even
-a collection of refs with corresponding remote tracking branches
+a collection of refs with corresponding remote-tracking branches
 (e.g., refs/heads/*:refs/remotes/origin/*), but usually it is
 the name of a branch in the remote repository.
 
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index aa021b0..3143c89 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -75,7 +75,7 @@ was passed.
 
 'rename'::
 
-Rename the remote named <old> to <new>. All remote tracking branches and
+Rename the remote named <old> to <new>. All remote-tracking branches and
 configuration settings for the remote are updated.
 +
 In case <old> and <new> are the same, and <old> is a file under
@@ -84,7 +84,7 @@ the configuration file format.
 
 'rm'::
 
-Remove the remote named <name>. All remote tracking branches and
+Remove the remote named <name>. All remote-tracking branches and
 configuration settings for the remote are removed.
 
 'set-head'::
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index 1c16066..0982f74 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -385,7 +385,7 @@ alice$ git fetch bob
 
 Unlike the longhand form, when Alice fetches from Bob using a
 remote repository shorthand set up with 'git remote', what was
-fetched is stored in a remote tracking branch, in this case
+fetched is stored in a remote-tracking branch, in this case
 `bob/master`.  So after this:
 
 -------------------------------------
@@ -402,8 +402,8 @@ could merge the changes into her master branch:
 alice$ git merge bob/master
 -------------------------------------
 
-This `merge` can also be done by 'pulling from her own remote
-tracking branch', like this:
+This `merge` can also be done by 'pulling from her own remote-tracking
+branch', like this:
 
 -------------------------------------
 alice$ git pull . remotes/bob/master
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index ebc0108..052e64f 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -264,7 +264,7 @@ endif::git-rev-list[]
 
 	Pretend as if all the refs in `refs/remotes` are listed
 	on the command line as '<commit>'. If `pattern`is given, limit
-	remote tracking branches to ones matching given shell glob.
+	remote-tracking branches to ones matching given shell glob.
 	If pattern lacks '?', '*', or '[', '/*' at the end is implied.
 
 --glob=glob-pattern::
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 77eb483..cc65077 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1700,7 +1700,7 @@ may wish to check the original repository for updates and merge them
 into your own work.
 
 We have already seen <<Updating-a-repository-With-git-fetch,how to
-keep remote tracking branches up to date>> with linkgit:git-fetch[1],
+keep remote-tracking branches up to date>> with linkgit:git-fetch[1],
 and how to merge two branches.  So you can merge in changes from the
 original repository's master branch with:
 
-- 
1.7.2.2.409.gdbb11.dirty

> > (Comment: maybe “... but working directory contains untracked files.”
> > I realise that “directory” is not quite comprehensive here, because
> > files can reside in subdirectories.
> 
> We use "worktree" elsewhere, how about that?

$ git grep "worktree" | wc -l
281
$ git grep "working directory" | wc -l
246
$ git grep "working tree" | wc -l
449

Additionally, "working directory" also really refers to a (current)
working *directory* in many places.

I like "worktree" too, but for consistency I've replaced the
inconsistent usage of "working directory" in the UI with "working
tree". No, I haven't updated the documentation because it's frankly
too painful.

-- 8< --
From 7422c2af1ef40c922d8f628715ad96172e4a5734 Mon Sep 17 00:00:00 2001
From: Ramkumar Ramachandra <[email-masked]>
Date: Tue, 19 Oct 2010 23:16:04 +0530
Subject: [PATCH] UI: Don't say "working directory" when we really mean "working tree"

While in some places "working directory" is used to refer to the
(current) working directory, it's incorrectly used in places where Git
actually means "working tree" or worktree. Weed out and replace these
instances in the UI.

Reported-by: Thore Husfeldt <[email-masked]>
Signed-off-by: Ramkumar Ramachandra <[email-masked]>
---
 builtin/apply.c      |    2 +-
 convert.c            |    4 ++--
 git-filter-branch.sh |    2 +-
 git-stash.sh         |    2 +-
 setup.c              |    2 +-
 unpack-trees.c       |    2 +-
 wt-status.c          |    4 ++--
 7 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/builtin/apply.c b/builtin/apply.c
index 23c18c5..9166320 100644
--- a/builtin/apply.c
+++ b/builtin/apply.c
@@ -2934,7 +2934,7 @@ static int check_to_create_blob(const char *new_name, int ok_if_exists)
 		if (has_symlink_leading_path(new_name, strlen(new_name)))
 			return 0;
 
-		return error("%s: already exists in working directory", new_name);
+		return error("%s: already exists in working tree", new_name);
 	}
 	else if ((errno != ENOENT) && (errno != ENOTDIR))
 		return error("%s: %s", new_name, strerror(errno));
diff --git a/convert.c b/convert.c
index 01de9a8..441708e 100644
--- a/convert.c
+++ b/convert.c
@@ -131,7 +131,7 @@ static void check_safe_crlf(const char *path, enum action action,
 		 */
 		if (stats->crlf) {
 			if (checksafe == SAFE_CRLF_WARN)
-				warning("CRLF will be replaced by LF in %s.\nThe file will have its original line endings in your working directory.", path);
+				warning("CRLF will be replaced by LF in %s.\nThe file will have its original line endings in your working tree.", path);
 			else /* i.e. SAFE_CRLF_FAIL */
 				die("CRLF would be replaced by LF in %s.", path);
 		}
@@ -142,7 +142,7 @@ static void check_safe_crlf(const char *path, enum action action,
 		 */
 		if (stats->lf != stats->crlf) {
 			if (checksafe == SAFE_CRLF_WARN)
-				warning("LF will be replaced by CRLF in %s.\nThe file will have its original line endings in your working directory.", path);
+				warning("LF will be replaced by CRLF in %s.\nThe file will have its original line endings in your working tree.", path);
 			else /* i.e. SAFE_CRLF_FAIL */
 				die("LF would be replaced by CRLF in %s", path);
 		}
diff --git a/git-filter-branch.sh b/git-filter-branch.sh
index 962a93b..0ab5551 100755
--- a/git-filter-branch.sh
+++ b/git-filter-branch.sh
@@ -110,7 +110,7 @@ OPTIONS_SPEC=
 if [ "$(is_bare_repository)" = false ]; then
 	git diff-files --ignore-submodules --quiet &&
 	git diff-index --cached --quiet HEAD -- ||
-	die "Cannot rewrite branch(es) with a dirty working directory."
+	die "Cannot rewrite branch(es) with a dirty working tree."
 fi
 
 tempdir=.git-rewrite
diff --git a/git-stash.sh b/git-stash.sh
index 7561b37..86cf24e 100755
--- a/git-stash.sh
+++ b/git-stash.sh
@@ -179,7 +179,7 @@ save_stash () {
 
 	git update-ref -m "$stash_msg" $ref_stash $w_commit ||
 		die "Cannot save the current status"
-	say Saved working directory and index state "$stash_msg"
+	say Saved working tree and index state "$stash_msg"
 
 	if test -z "$patch_mode"
 	then
diff --git a/setup.c b/setup.c
index a3b76de..55f8fe3 100644
--- a/setup.c
+++ b/setup.c
@@ -611,7 +611,7 @@ const char *setup_git_directory(void)
 			die_errno ("Could not jump back into original cwd");
 		rel = get_relative_cwd(buffer, PATH_MAX, get_git_work_tree());
 		if (rel && *rel && chdir(get_git_work_tree()))
-			die_errno ("Could not jump to working directory");
+			die_errno ("Could not jump to working tree");
 		return rel && *rel ? strcat(rel, "/") : NULL;
 	}
 
diff --git a/unpack-trees.c b/unpack-trees.c
index 803445a..a70b57c 100644
--- a/unpack-trees.c
+++ b/unpack-trees.c
@@ -934,7 +934,7 @@ int unpack_trees(unsigned len, struct tree_desc *t, struct unpack_trees_options
 
 		}
 		if (o->result.cache_nr && empty_worktree) {
-			ret = unpack_failed(o, "Sparse checkout leaves no entry on working directory");
+			ret = unpack_failed(o, "Sparse checkout leaves no entry on working tree");
 			goto done;
 		}
 	}
diff --git a/wt-status.c b/wt-status.c
index fc2438f..89831cb 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -95,7 +95,7 @@ static void wt_status_print_dirty_header(struct wt_status *s,
 		color_fprintf_ln(s->fp, c, "#   (use \"git add <file>...\" to update what will be committed)");
 	else
 		color_fprintf_ln(s->fp, c, "#   (use \"git add/rm <file>...\" to update what will be committed)");
-	color_fprintf_ln(s->fp, c, "#   (use \"git checkout -- <file>...\" to discard changes in working directory)");
+	color_fprintf_ln(s->fp, c, "#   (use \"git checkout -- <file>...\" to discard changes in working tree)");
 	if (has_dirty_submodules)
 		color_fprintf_ln(s->fp, c, "#   (commit or discard the untracked or modified content in submodules)");
 	color_fprintf_ln(s->fp, c, "#");
@@ -690,7 +690,7 @@ void wt_status_print(struct wt_status *s)
 				? " (use -u to show untracked files)" : "");
 		else
 			printf("nothing to commit%s\n", advice_status_hints
-				? " (working directory clean)" : "");
+				? " (working tree clean)" : "");
 	}
 }
 
-- 
1.7.2.2.409.gdbb11.dirty

> >    Changes to be committed:
> >    (use "git reset HEAD <file>..." to unstage)
> >
> > should be
> >
> >    Staged to be committed:
> >    (use "git unstage <file>" to unstage)
> 
> This would be extra nice since 'git unstage' could also be used in a
> fresh repository.

[`git unstage` patch still cooking]

Sverre: Thanks!
Thore: Thanks for the feedback. Please read
Documentation/SubmittingPatches and submit more patches.

-- Ram