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

Message ID 20190312233040.GE16414@hank.intra.tgummerer.com
State New
Headers show
Series
  • [v2] glossary: add definition for overlay
Related show

Commit Message

Thomas Gummerer March 12, 2019, 11:30 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>
Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com>
---

v2 addresses Elijah's comments (thanks!), using the wording he
suggested in [*1*], which I agree is slightly better, as no-overlay
mode doesn't touch untracked files.

*1*: https://public-inbox.org/git/CABPp-BEv1taYym_084qVJj3-jkWWS9hKXZ=grrmH7PDUb5ASwA@mail.gmail.com/

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

Comments

Duy Nguyen March 13, 2019, 1:13 a.m. UTC | #1
On Wed, Mar 13, 2019 at 6:30 AM Thomas Gummerer <t.gummerer@gmail.com> 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>
> Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com>
> ---
>
> v2 addresses Elijah's comments (thanks!), using the wording he
> suggested in [*1*], which I agree is slightly better, as no-overlay
> mode doesn't touch untracked files.

It could overwrite untracked files (e.g. the file is present in the
source, but not tracked) but never delete them. But I think it's the
little detail that we could skip.
Junio C Hamano March 13, 2019, 1:42 a.m. UTC | #2
Thomas Gummerer <t.gummerer@gmail.com> writes:

> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index 023ca95e7c..53df6ecb0a 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -287,6 +287,13 @@ 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 work.  This is the
> +	default mode in a <<def_checkout,checkout>>.  In contrast,
> +	no-overlay mode will also delete tracked files not present in
> +	the source, similar to 'rsync --delete'.
> +

At least the mention of "checkout" needs to be a lot tightened to
clarify that it is talking about "checkout <pathspec>", aka
"checking out files out of the index or a tree-ish", as opposed to
"checking out a branch to work on it", as checking out a branch will
not work in the overlay fashion.  What's not in the newly checked
out branch will disappear from the working tree.

If readers happen to be not paying close attention to the fact that
the difference between overlay and non-overlay is about the
destination, "similar to how 'cp -R' would work" may not click to
their minds.  "similar to how 'cp -R' updates the contents in the
destination directory" may avoid such a risk, albeit it might be a
bit too verbose.  I dunno.

Thanks.
Thomas Gummerer March 15, 2019, 10:31 p.m. UTC | #3
On 03/13, Duy Nguyen wrote:
> On Wed, Mar 13, 2019 at 6:30 AM Thomas Gummerer <t.gummerer@gmail.com> 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>
> > Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com>
> > ---
> >
> > v2 addresses Elijah's comments (thanks!), using the wording he
> > suggested in [*1*], which I agree is slightly better, as no-overlay
> > mode doesn't touch untracked files.
> 
> It could overwrite untracked files (e.g. the file is present in the
> source, but not tracked) but never delete them. But I think it's the
> little detail that we could skip.

Right, we decided to go without that detail in the documentation for
the command line option as well [*1*].  I think the argument that an
overly precise description would make the description harder to
understand is also valid here.  Though if someone can come up with a
nice phrasing for that I'd be happy to add that.

*1*: https://public-inbox.org/git/xmqqo98yiq8i.fsf@gitster-ct.c.googlers.com/
Thomas Gummerer March 15, 2019, 11:10 p.m. UTC | #4
On 03/13, Junio C Hamano wrote:
> Thomas Gummerer <t.gummerer@gmail.com> writes:
> 
> > diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> > index 023ca95e7c..53df6ecb0a 100644
> > --- a/Documentation/glossary-content.txt
> > +++ b/Documentation/glossary-content.txt
> > @@ -287,6 +287,13 @@ 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 work.  This is the
> > +	default mode in a <<def_checkout,checkout>>.  In contrast,
> > +	no-overlay mode will also delete tracked files not present in
> > +	the source, similar to 'rsync --delete'.
> > +
> 
> At least the mention of "checkout" needs to be a lot tightened to
> clarify that it is talking about "checkout <pathspec>", aka
> "checking out files out of the index or a tree-ish", as opposed to
> "checking out a branch to work on it", as checking out a branch will
> not work in the overlay fashion.  What's not in the newly checked
> out branch will disappear from the working tree.

Good point, I'll fix that in v3.

> If readers happen to be not paying close attention to the fact that
> the difference between overlay and non-overlay is about the
> destination, "similar to how 'cp -R' would work" may not click to
> their minds.  "similar to how 'cp -R' updates the contents in the
> destination directory" may avoid such a risk, albeit it might be a
> bit too verbose.  I dunno.

I feel like it's okay to be a bit more verbose in the glossary.  I
think your suggestion above is better than what I had, I'll use that
in v3, thanks!

Patch
diff mbox series

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 023ca95e7c..53df6ecb0a 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -287,6 +287,13 @@  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 work.  This is the
+	default mode in a <<def_checkout,checkout>>.  In contrast,
+	no-overlay mode will also delete 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).