[v3] glossary: add definition for overlay
diff mbox series

Message ID 20190317201956.GB1216@hank.intra.tgummerer.com
State New
Headers show
Series
  • [v3] glossary: add definition for overlay
Related show

Commit Message

Thomas Gummerer March 17, 2019, 8:19 p.m. UTC
Add a definition for what overlay means in the context of git, to
clarify the recently introduced overlay-mode in git checkout.

Helped-by: Elijah Newren <newren@gmail.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com>
---

v3 incorporates Junios suggestions from [*1*], and clarifies that this
only applies to checking out from the index or a tree-ish, and
clarifies that the files are updated like in the destination directory
of 'cp -R'.  I thought of making the same clarification for 'rsync
--delete' as well, however I think with it being explicitly specified
for 'cp -R', readers should be able to deduce that we are talking
about the destination directory there as well.

*1*: <xmqq5zsnh7my.fsf@gitster-ct.c.googlers.com>

 Documentation/glossary-content.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

Comments

Philip Oakley March 21, 2019, 2:48 p.m. UTC | #1
Hi, sorry for the late response..

On 17/03/2019 20:19, Thomas Gummerer wrote:
> Add a definition for what overlay means in the context of git, to
> clarify the recently introduced overlay-mode in git checkout.
>
> Helped-by: Elijah Newren <newren@gmail.com>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com>
> ---
>
> v3 incorporates Junios suggestions from [*1*], and clarifies that this
> only applies to checking out from the index or a tree-ish, and
> clarifies that the files are updated like in the destination directory
> of 'cp -R'.  I thought of making the same clarification for 'rsync
> --delete' as well, however I think with it being explicitly specified
> for 'cp -R', readers should be able to deduce that we are talking
> about the destination directory there as well.
As a historically Windows user, we should ensure that the meaning is 
clear to all without the otherwise helpful *nix command examples.
>
> *1*: <xmqq5zsnh7my.fsf@gitster-ct.c.googlers.com>
>
>   Documentation/glossary-content.txt | 9 +++++++++
>   1 file changed, 9 insertions(+)
>
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index 023ca95e7c..0f29075551 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -287,6 +287,15 @@ This commit is referred to as a "merge commit", or sometimes just a
>   	origin/name-of-upstream-branch, which you can see using
>   	`git branch -r`.
>   
> +[[def_overlay]]overlay::
> +	Only update and add files to the working directory, but don't
> +	delete them, similar to how 'cp -R' would update the contents
perhapsĀ  s/them/any files/
> +	in the destination directory.  This is the default mode in a
> +	<<def_checkout,checkout>> when checking out files from the
> +	<<def_index,index>> or a <<def_tree-ish,tree-ish>>.  In
> +	contrast, no-overlay mode also deletes tracked files not

understanding the past/future distinction is tricky here. Maybe 'deletes 
previously tracked files that are no longer present in the new source'.

It's tricky talking about deleting things that are not there.

> +	present in the source, similar to 'rsync --delete'.
> +
>   [[def_pack]]pack::
>   	A set of objects which have been compressed into one file (to save space
>   	or to transmit them efficiently).

--

Philip
Junio C Hamano March 22, 2019, 4:54 a.m. UTC | #2
Philip Oakley <philipoakley@iee.org> writes:

>> of 'cp -R'.  I thought of making the same clarification for 'rsync
>> --delete' as well, however I think with it being explicitly specified
>> for 'cp -R', readers should be able to deduce that we are talking
>> about the destination directory there as well.
> As a historically Windows user, we should ensure that the meaning is
> clear to all without the otherwise helpful *nix command examples.

I do not know about "cp -R", but surely "rsync" is used by Windows
users as well as users of Unix based systems, isn't it?

>> +	Only update and add files to the working directory, but don't
>> +	delete them, similar to how 'cp -R' would update the contents

> perhapsĀ  s/them/any files/

Probably.  The paths that are not deleted are certainly different
set of paths from those that are updated and/or added, so it sounds
like a reasonable thing to do.

>> +	in the destination directory.  This is the default mode in a
>> +	<<def_checkout,checkout>> when checking out files from the
>> +	<<def_index,index>> or a <<def_tree-ish,tree-ish>>.  In
>> +	contrast, no-overlay mode also deletes tracked files not
>
> understanding the past/future distinction is tricky here. Maybe
> 'deletes previously tracked files that are no longer present in the
> new source'.
>
> It's tricky talking about deleting things that are not there.

I am afraid that "previously" may be taken too literally by readers
and misunderstood as paths that had been tracked even once in the
past.  

If you think that is worried too much because we can only delete
what is _currently_ in the index, and any past before what is in the
current index cannot ever affect the outcome, the same reasoning
tells me that the original is clear enough without "previously",
i.e. "tracked ones not present in..." are the ones that are in the
index currently, but the tree that we are taking new contents from
does not have them.

I dunno.

>> +	present in the source, similar to 'rsync --delete'.
Thomas Gummerer March 28, 2019, 9:05 p.m. UTC | #3
On 03/22, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.org> writes:
> 
> >> of 'cp -R'.  I thought of making the same clarification for 'rsync
> >> --delete' as well, however I think with it being explicitly specified
> >> for 'cp -R', readers should be able to deduce that we are talking
> >> about the destination directory there as well.
> > As a historically Windows user, we should ensure that the meaning is
> > clear to all without the otherwise helpful *nix command examples.

Sure, it would definitely be good to be clear to users of all
platforms.  Is the text by itself not understandable enough?  If not
do you have any suggestions to improve it?

I think giving the example of 'cp -R' is still good, even if not all
Windows users are familiar with it, as it's supposed to provide some
additional context.  But it's only an additional example, the sentence
is supposed to be understandable either way.  Would there be a similar
command for Windows that could be used as an example?

> I do not know about "cp -R", but surely "rsync" is used by Windows
> users as well as users of Unix based systems, isn't it?
> 
> >> +	Only update and add files to the working directory, but don't
> >> +	delete them, similar to how 'cp -R' would update the contents
> 
> > perhapsĀ  s/them/any files/
> 
> Probably.  The paths that are not deleted are certainly different
> set of paths from those that are updated and/or added, so it sounds
> like a reasonable thing to do.

Thanks, will update this.

> >> +	in the destination directory.  This is the default mode in a
> >> +	<<def_checkout,checkout>> when checking out files from the
> >> +	<<def_index,index>> or a <<def_tree-ish,tree-ish>>.  In
> >> +	contrast, no-overlay mode also deletes tracked files not
> >
> > understanding the past/future distinction is tricky here. Maybe
> > 'deletes previously tracked files that are no longer present in the
> > new source'.
> >
> > It's tricky talking about deleting things that are not there.
> 
> I am afraid that "previously" may be taken too literally by readers
> and misunderstood as paths that had been tracked even once in the
> past.  
> 
> If you think that is worried too much because we can only delete
> what is _currently_ in the index, and any past before what is in the
> current index cannot ever affect the outcome, the same reasoning
> tells me that the original is clear enough without "previously",
> i.e. "tracked ones not present in..." are the ones that are in the
> index currently, but the tree that we are taking new contents from
> does not have them.

Agreed, I think I prefer the current version over the suggested change
here too.

> I dunno.
> 
> >> +	present in the source, similar to 'rsync --delete'.

Patch
diff mbox series

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 023ca95e7c..0f29075551 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -287,6 +287,15 @@  This commit is referred to as a "merge commit", or sometimes just a
 	origin/name-of-upstream-branch, which you can see using
 	`git branch -r`.
 
+[[def_overlay]]overlay::
+	Only update and add files to the working directory, but don't
+	delete them, similar to how 'cp -R' would update the contents
+	in the destination directory.  This is the default mode in a
+	<<def_checkout,checkout>> when checking out files from the
+	<<def_index,index>> or a <<def_tree-ish,tree-ish>>.  In
+	contrast, no-overlay mode also deletes tracked files not
+	present in the source, similar to 'rsync --delete'.
+
 [[def_pack]]pack::
 	A set of objects which have been compressed into one file (to save space
 	or to transmit them efficiently).