threads / patch / 9241

patchgit-gui wording suggestions

Subject: [PATCH] git-gui wording suggestions

## tl;dr

6 messages between Jul 26, 2007 and Jul 29, 2007. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

Christian Stimming· Jul 26, 2007, 09:19 UTC · lore
Unifiy wording to say "to stage" instead of "to add" always.

Currently, there is a mixup of saying "staged changes" vs. "added changes" in the git-gui program. You obviously decided to say "staging area" instead of "index", hence "add to staging area"/"stage" instead of "add to index". I think this change is very good. Talking about the "staging area" explains the nature of this thingy much better and much more unambiguous than "index". Actually only after reading the wording "staging area" I eventually understood what this "index" thing is about... (Also, your chosen wording helps for creating a nice and consistent translation of that, but that's only an added bonus.)

With this patch I'd propose to talk every only about "stage" instead of "add". IMHO that's just the logical conclusion of the above wording decision. What do you think?

---
  git-gui.sh          |    6 +++---
  lib/checkout_op.tcl |    2 +-
  lib/commit.tcl      |    4 ++--
  lib/index.tcl       |    2 +-
  lib/merge.tcl       |    2 +-
  5 files changed, 8 insertions(+), 8 deletions(-)
Show changes to 5 files +8 −8

git-gui.sh, lib/checkout_op.tcl, lib/commit.tcl, lib/index.tcl, lib/merge.tcl

diff --git a/git-gui.sh b/git-gui.sh
index 3536d38..fd8b4b4 100755
--- a/git-gui.sh
+++ b/git-gui.sh
@@ -1824,12 +1824,12 @@ if {[is_enabled multicommit] || [is_enabled  
singlecommit]} {
  	lappend disable_on_lock \
  		[list .mbar.commit entryconf [.mbar.commit index last] -state]

-	.mbar.commit add command -label [mc "Add To Commit"] \
+	.mbar.commit add command -label [mc "Stage To Commit"] \
  		-command do_add_selection
  	lappend disable_on_lock \
  		[list .mbar.commit entryconf [.mbar.commit index last] -state]

-	.mbar.commit add command -label [mc "Add Existing To Commit"] \
+	.mbar.commit add command -label [mc "Stage Changed Files To Commit"] \
  		-command do_add_all \
  		-accelerator $M1T-I
  	lappend disable_on_lock \
@@ -2180,7 +2180,7 @@ pack .vpane.lower.commarea.buttons.rescan -side  
top -fill x
  lappend disable_on_lock \
  	{.vpane.lower.commarea.buttons.rescan conf -state}

-button .vpane.lower.commarea.buttons.incall -text [mc "Add Existing"] \
+button .vpane.lower.commarea.buttons.incall -text [mc "Stage Changed"] \
  	-command do_add_all
  pack .vpane.lower.commarea.buttons.incall -side top -fill x
  lappend disable_on_lock \
diff --git a/lib/checkout_op.tcl b/lib/checkout_op.tcl
index 25bf9cf..a2f2509 100644
--- a/lib/checkout_op.tcl
+++ b/lib/checkout_op.tcl
@@ -247,7 +247,7 @@ method _checkout {} {
  	if {[lock_index checkout_op]} {
  		after idle [cb _start_checkout]
  	} else {
-		_error $this [mc "Index is already locked."]
+		_error $this [mc "Staging area (index) is already locked."]
  		delete_this
  	}
  }
diff --git a/lib/commit.tcl b/lib/commit.tcl
index f60b11e..aa9110d 100644
--- a/lib/commit.tcl
+++ b/lib/commit.tcl
@@ -153,7 +153,7 @@ The rescan will be automatically started now.
  		U? {
  			error_popup [mc "Unmerged files cannot be committed.

-File %s has merge conflicts.  You must resolve them and add the file  
before committing.
+File %s has merge conflicts.  You must resolve them and stage the  
file before committing.
  " [short_path $path]]
  			unlock_index
  			return
@@ -169,7 +169,7 @@ File %s cannot be committed by this program.
  	if {!$files_ready && ![string match *merge $curType]} {
  		info_popup [mc "No changes to commit.

-You must add at least 1 file before you can commit.
+You must stage at least 1 file before you can commit.
  "]
  		unlock_index
  		return
diff --git a/lib/index.tcl b/lib/index.tcl
index 38aa6ee..e91b864 100644
--- a/lib/index.tcl
+++ b/lib/index.tcl
@@ -367,7 +367,7 @@ proc revert_helper {txt paths} {
  		"[appname] ([reponame])" \
  		[mc "%s

-Any unadded changes will be permanently lost by the revert." $query] \
+Any unstaged changes will be permanently lost by the revert." $query] \
  		question \
  		1 \
  		[mc "Do Nothing"] \
diff --git a/lib/merge.tcl b/lib/merge.tcl
index 40e82a9..a6e8cc9 100644
--- a/lib/merge.tcl
+++ b/lib/merge.tcl
@@ -46,7 +46,7 @@ The rescan will be automatically started now.

  File %s has merge conflicts.

-You must resolve them, add the file, and commit to complete the  
current merge.  Only then can you begin another merge.
+You must resolve them, stage the file, and commit to complete the  
current merge.  Only then can you begin another merge.
  " [short_path $path]]
  			unlock_index
  			return 0
-- 
1.5.3.rc2.12.gbc280
Shawn O. Pearce· Jul 27, 2007, 04:40 UTC · re: Christian Stimming · lore

Re: [PATCH] git-gui wording suggestions

Christian Stimming <stimming@tuhh.de> wrote:
> Unifiy wording to say "to stage" instead of "to add" always.
...
> With this patch I'd propose to talk every only about "stage" instead  
> of "add". IMHO that's just the logical conclusion of the above wording  
> decision. What do you think?

Yes, I agree. This is a necessary change, the current wording is very confusing. I would apply this earlier than the other i18n stuff, but this patch is written based upon the current i18n work. :-|

Show 14 quoted lines
> diff --git a/git-gui.sh b/git-gui.sh
> index 3536d38..fd8b4b4 100755
> --- a/git-gui.sh
> +++ b/git-gui.sh
> @@ -1824,12 +1824,12 @@ if {[is_enabled multicommit] || [is_enabled  
> singlecommit]} {
>   	lappend disable_on_lock \
>   		[list .mbar.commit entryconf [.mbar.commit index last] -state]
> 
> -	.mbar.commit add command -label [mc "Add To Commit"] \
> +	.mbar.commit add command -label [mc "Stage To Commit"] \
>   		-command do_add_selection
>   	lappend disable_on_lock \
>   		[list .mbar.commit entryconf [.mbar.commit index last] -state]
...
-- 
Shawn.
Junio C Hamano· Jul 27, 2007, 05:09 UTC · re: Shawn O. Pearce · lore

Re: [PATCH] git-gui wording suggestions

"Shawn O. Pearce" <spearce@spearce.org> writes:
Show 9 quoted lines
> Christian Stimming <stimming@tuhh.de> wrote:
>> Unifiy wording to say "to stage" instead of "to add" always.
> ...
>> With this patch I'd propose to talk every only about "stage" instead  
>> of "add". IMHO that's just the logical conclusion of the above wording  
>> decision. What do you think?
>
> Yes, I agree.  This is a necessary change, the current wording is
> very confusing.

Looking at the expressions used in the application from the point of view of translating the words to (or expressing the concept in) another language helps finding more appropriate wording even in the original language.

"Add" is a simple and nice word, but it is too broad, so "to stage" is an improvement. The translated message for "to stage" for Japanese we will probably end up choosing would translate back to English as "Schedule for commit".

Christian Stimming· Jul 27, 2007, 11:42 UTC · re: Shawn O. Pearce · lore

Re: [PATCH] git-gui wording suggestions

Quoting "Shawn O. Pearce" <spearce@spearce.org>:
Show 10 quoted lines
>> Unifiy wording to say "to stage" instead of "to add" always.
> ...
>> With this patch I'd propose to talk every only about "stage" instead
>> of "add". IMHO that's just the logical conclusion of the above wording
>> decision. What do you think?
>
> Yes, I agree.  This is a necessary change, the current wording is
> very confusing.  I would apply this earlier than the other i18n
> stuff, but this patch is written based upon the current i18n work.
> :-|

Well, of course I have supplied this patch on top of the current i18n markup work... on the other hand, back-porting the string changes to the non-i18n code means that the i18n changes themselves won't merge anymore. For that reason I wouldn't suggest to apply this separately from the i18n commits, unless you would want to adapt the i18n patches as well.

I'd rather suggest to consider the i18n changes rather soon by now, even if the actual translations will be merged later. The [mc...] calls itself don't change the behaviour of the application, so I don't think it would be very risky do merge them sooner than later. Eventually, that's of course up to you.

Christian
Christian Stimming· Jul 28, 2007, 20:17 UTC · lore

Re: [PATCH] git-gui.git: Wording suggestions, 2nd try

Unify wording to say "to stage" instead of "to add" always.

Also, the warning message when clicking "Reset" is adapted to the wording "Reset" rather than a confusion "Cancel commit?".

Signed-off-by: Christian Stimming <stimming@tuhh.de>
---
This time, this patch is actually based on git-gui.git's master. If you want to, you can directly apply this regardless of i18n work that was deferred until later.
The last hunk in lib/merge.tcl looks a bit confusing; in preparation of i18n work, the previous message that inserted a single word into the long english sentence was already replaced by the i18n'able form of two completely different messages. But nevertheless the main point is that when clicking "Reset", the upcoming question should use the wording "reset", which it will do after this patch.
 git-gui.sh          |    6 +++---
 lib/checkout_op.tcl |    2 +-
 lib/commit.tcl      |    4 ++--
 lib/index.tcl       |    2 +-
 lib/merge.tcl       |   18 +++++++++++-------
 5 files changed, 18 insertions(+), 14 deletions(-)
Show changes to 5 files +18 −14

git-gui.sh, lib/checkout_op.tcl, lib/commit.tcl, lib/index.tcl, lib/merge.tcl

diff --git a/git-gui.sh b/git-gui.sh
index f87b955..d7fad46 100755
--- a/git-gui.sh
+++ b/git-gui.sh
@@ -1827,12 +1827,12 @@ if {[is_enabled multicommit] || [is_enabled singlecommit]} {
 	lappend disable_on_lock \
 		[list .mbar.commit entryconf [.mbar.commit index last] -state]
 
-	.mbar.commit add command -label {Add To Commit} \
+	.mbar.commit add command -label {Stage To Commit} \
 		-command do_add_selection
 	lappend disable_on_lock \
 		[list .mbar.commit entryconf [.mbar.commit index last] -state]
 
-	.mbar.commit add command -label {Add Tracked Files To Commit} \
+	.mbar.commit add command -label {Stage Changed Files To Commit} \
 		-command do_add_all \
 		-accelerator $M1T-I
 	lappend disable_on_lock \
@@ -2154,7 +2154,7 @@ pack .vpane.lower.commarea.buttons.rescan -side top -fill x
 lappend disable_on_lock \
 	{.vpane.lower.commarea.buttons.rescan conf -state}
 
-button .vpane.lower.commarea.buttons.incall -text {Add Tracked} \
+button .vpane.lower.commarea.buttons.incall -text {Stage Changed} \
 	-command do_add_all
 pack .vpane.lower.commarea.buttons.incall -side top -fill x
 lappend disable_on_lock \
diff --git a/lib/checkout_op.tcl b/lib/checkout_op.tcl
index 40cc73a..170f737 100644
--- a/lib/checkout_op.tcl
+++ b/lib/checkout_op.tcl
@@ -248,7 +248,7 @@ method _checkout {} {
 	if {[lock_index checkout_op]} {
 		after idle [cb _start_checkout]
 	} else {
-		_error $this "Index is already locked."
+		_error $this "Staging area (index) is already locked."
 		delete_this
 	}
 }
diff --git a/lib/commit.tcl b/lib/commit.tcl
index 1f5c2c3..f857a2f 100644
--- a/lib/commit.tcl
+++ b/lib/commit.tcl
@@ -153,7 +153,7 @@ The rescan will be automatically started now.
 		U? {
 			error_popup "Unmerged files cannot be committed.
 
-File [short_path $path] has merge conflicts.  You must resolve them and add the file before committing.
+File [short_path $path] has merge conflicts.  You must resolve them and stage the file before committing.
 "
 			unlock_index
 			return
@@ -169,7 +169,7 @@ File [short_path $path] cannot be committed by this program.
 	if {!$files_ready && ![string match *merge $curType]} {
 		info_popup {No changes to commit.
 
-You must add at least 1 file before you can commit.
+You must stage at least 1 file before you can commit.
 }
 		unlock_index
 		return
diff --git a/lib/index.tcl b/lib/index.tcl
index 3ea72e1..f47f929 100644
--- a/lib/index.tcl
+++ b/lib/index.tcl
@@ -360,7 +360,7 @@ proc revert_helper {txt paths} {
 		"[appname] ([reponame])" \
 		"Revert changes in $s?
 
-Any unadded changes will be permanently lost by the revert." \
+Any unstaged changes will be permanently lost by the revert." \
 		question \
 		1 \
 		{Do Nothing} \
diff --git a/lib/merge.tcl b/lib/merge.tcl
index 148d859..f6a2df3 100644
--- a/lib/merge.tcl
+++ b/lib/merge.tcl
@@ -45,7 +45,7 @@ The rescan will be automatically started now.
 
 File [short_path $path] has merge conflicts.
 
-You must resolve them, add the file, and commit to complete the current merge.  Only then can you begin another merge.
+You must resolve them, stage the file, and commit to complete the current merge.  Only then can you begin another merge.
 "
 			unlock_index
 			return 0
@@ -219,16 +219,20 @@ You must finish amending this commit.
 	if {![lock_index abort]} return
 
 	if {[string match *merge* $commit_type]} {
-		set op merge
+		set op_question "Abort merge?
+
+Aborting the current merge will cause *ALL* uncommitted changes to be lost.
+
+Continue with aborting the current merge?"
 	} else {
-		set op commit
-	}
+		set op_question "Reset changes?
 
-	if {[ask_popup "Abort $op?
+Resetting the changes will cause *ALL* uncommitted changes to be lost.
 
-Aborting the current $op will cause *ALL* uncommitted changes to be lost.
+Continue with resetting the current changes?"
+	}
 
-Continue with aborting the current $op?"] eq {yes}} {
+	if {[ask_popup $op_question] eq {yes}} {
 		set fd [git_read read-tree --reset -u HEAD]
 		fconfigure $fd -blocking 0 -translation binary
 		fileevent $fd readable [namespace code [list _reset_wait $fd]]
-- 
1.5.2
Shawn O. Pearce· Jul 29, 2007, 07:08 UTC · re: Christian Stimming · lore

Re: [PATCH] git-gui.git: Wording suggestions, 2nd try

Christian Stimming <stimming@tuhh.de> wrote:
Show 16 quoted lines
> Unify wording to say "to stage" instead of "to add" always.
> 
> Also, the warning message when clicking "Reset" is adapted to
> the wording "Reset" rather than a confusion "Cancel commit?".
> 
> Signed-off-by: Christian Stimming <stimming@tuhh.de>
> ---
> This time, this patch is actually based on git-gui.git's master. If
> you want to, you can directly apply this regardless of i18n work that
> was deferred until later.  The last hunk in lib/merge.tcl looks a
> bit confusing; in preparation of i18n work, the previous message
> that inserted a single word into the long english sentence was
> already replaced by the i18n'able form of two completely different
> messages. But nevertheless the main point is that when clicking
> "Reset", the upcoming question should use the wording "reset",
> which it will do after this patch.

Thanks, I'm including this in 0.8.0 as I think it makes things a lot clearer, at least for English speakers. ;-)

As soon as git 1.5.3 ships I'll start work on 0.9.0, and I'm
looking to bringing the i18n work in as the first series of
changes for the 0.9.x series...
 
-- 
Shawn.

← back to recent threads