| Message ID | 20190312233040.GE16414@hank.intra.tgummerer.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] glossary: add definition for overlay | expand |
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.
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.
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/
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!
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).
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(+)