Git add documentation error

Git add documentation error

[Angelo Borsotti]

Hello,

the reference manual for the "git add" command does not
specify what that command does when applied to an
unmodified file.
By testing this, I have seen that it does not add the file
to the index, and consequently it does not add it when a
subsequent commit is done.
I think that this should be documented.

Thank you
-Angelo Borsotti

Re: Git add documentation error

[Philip Oakley]

Hi,
On 27/10/2022 12:53, Angelo Borsotti wrote:
> Hello,
>
> the reference manual for the "git add" command does not
> specify what that command does when applied to an
> unmodified file.

I presume that this file is already tracked..
> By testing this, I have seen that it does not add the file
> to the index, 

How was this tested?

If you have no changes, thaen the status diff will have no mention of
that file.
Perhaps change the tracked mode bits to see if that is noticed (note
though, not all mode bits are tracked..)
> and consequently it does not add it when a
> subsequent commit is done.

I suspect this is a subtle mental model misunderstanding about the
distinction between a commit as a snapshot, and a commit being reported
as the diff relative to its parent (and here, there is none, if the file
is unmodified)
> I think that this should be documented.

A test script with sample output would help here.
--
Philip

Re: Git add documentation error

[Philip Oakley]

Hi Angelo, please use 'reply all' so others can participate.
Also, in-line replies are preferred.

On 27/10/2022 16:28, Angelo Borsotti wrote:
> Hi,
>
> I have tested this in the following way: I have two files: C1.java and C2.java
>
>     > git status
>     On branch master
>     nothing added to commit
>     > ... edit C2.java
>     > git status
>     On branch master
>     Changes not staged for commit:
>     (use "git add <file>..." to update what will be committed)
>     (use "git restore <file>..." to discard changes in working directory)
>         modified:   C2.java
>      > git add C1.java
>      > git add C2.java
>      > git commit -m "commit2"
>      D:\gittest>git commit -m "commit1"
>      [master 91ef45d] commit1
>      1 file changed, 1 insertion(+), 1 deletion(-)
>
> In commit1 there is only one file, which is C2.java.

It does say "1 file changed", which is true.
What it fails to mention is all the other files that are included within
the commit, but are unchanged.

Maybe have a look at
https://git-scm.com/docs/git-ls-tree#Documentation/git-ls-tree.txt---name-status,
probably with the -r option (check the command's description)

What Git version & OS are you on?
> This is a useful feature: one can stage all its files without
> bothering to remember
> which one had been changed, and then make a commit, and place the commands
> to do it in a script to be used each time a new commit is needed.
>
> -Angelo
>     ...
>
> On Thu, 27 Oct 2022 at 17:10, Philip Oakley <philipoakley@iee.email> wrote:
>> Hi,
>> On 27/10/2022 12:53, Angelo Borsotti wrote:
>>> Hello,
>>>
>>> the reference manual for the "git add" command does not
>>> specify what that command does when applied to an
>>> unmodified file.
>> I presume that this file is already tracked..
>>> By testing this, I have seen that it does not add the file
>>> to the index,
>> How was this tested?
>>
>> If you have no changes, thaen the status diff will have no mention of
>> that file.
>> Perhaps change the tracked mode bits to see if that is noticed (note
>> though, not all mode bits are tracked..)
>>> and consequently it does not add it when a
>>> subsequent commit is done.
>> I suspect this is a subtle mental model misunderstanding about the
>> distinction between a commit as a snapshot, and a commit being reported
>> as the diff relative to its parent (and here, there is none, if the file
>> is unmodified)
>>> I think that this should be documented.
>> A test script with sample output would help here.
>> --
>> Philip
>>
>>

Re: Git add documentation error

[Angelo Borsotti]

Hi Philip.

I have git 2.38.0.windows.1 on  windows 10.

I have then changed again C2.java, and made only one git add, and a commit

     > git add C2.java
     > git commit -m "commit2"
     [master 8ec0c2f] commit2
     1 file changed, 1 insertion(+), 1 deletion(-)

Then I displayed the contents of both commits, and seen that it is pretty much
the same:

D:\gittest>git show --pretty="" --name-only 91ef45d
C2.java

D:\gittest>git show --pretty="" --name-only 8ec0c2f
C2.java

If there is any difference in the files, probably it is under the hood.

-Angelo

On Thu, 27 Oct 2022 at 18:16, Philip Oakley <philipoakley@iee.email> wrote:
>
> Hi Angelo, please use 'reply all' so others can participate.
> Also, in-line replies are preferred.
>
> On 27/10/2022 16:28, Angelo Borsotti wrote:
> > Hi,
> >
> > I have tested this in the following way: I have two files: C1.java and C2.java
> >
> >     > git status
> >     On branch master
> >     nothing added to commit
> >     > ... edit C2.java
> >     > git status
> >     On branch master
> >     Changes not staged for commit:
> >     (use "git add <file>..." to update what will be committed)
> >     (use "git restore <file>..." to discard changes in working directory)
> >         modified:   C2.java
> >      > git add C1.java
> >      > git add C2.java
> >      > git commit -m "commit2"
> >      D:\gittest>git commit -m "commit1"
> >      [master 91ef45d] commit1
> >      1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > In commit1 there is only one file, which is C2.java.
>
> It does say "1 file changed", which is true.
> What it fails to mention is all the other files that are included within
> the commit, but are unchanged.
>
> Maybe have a look at
> https://git-scm.com/docs/git-ls-tree#Documentation/git-ls-tree.txt---name-status,
> probably with the -r option (check the command's description)
>
> What Git version & OS are you on?
> > This is a useful feature: one can stage all its files without
> > bothering to remember
> > which one had been changed, and then make a commit, and place the commands
> > to do it in a script to be used each time a new commit is needed.
> >
> > -Angelo
> >     ...
> >
> > On Thu, 27 Oct 2022 at 17:10, Philip Oakley <philipoakley@iee.email> wrote:
> >> Hi,
> >> On 27/10/2022 12:53, Angelo Borsotti wrote:
> >>> Hello,
> >>>
> >>> the reference manual for the "git add" command does not
> >>> specify what that command does when applied to an
> >>> unmodified file.
> >> I presume that this file is already tracked..
> >>> By testing this, I have seen that it does not add the file
> >>> to the index,
> >> How was this tested?
> >>
> >> If you have no changes, thaen the status diff will have no mention of
> >> that file.
> >> Perhaps change the tracked mode bits to see if that is noticed (note
> >> though, not all mode bits are tracked..)
> >>> and consequently it does not add it when a
> >>> subsequent commit is done.
> >> I suspect this is a subtle mental model misunderstanding about the
> >> distinction between a commit as a snapshot, and a commit being reported
> >> as the diff relative to its parent (and here, there is none, if the file
> >> is unmodified)
> >>> I think that this should be documented.
> >> A test script with sample output would help here.
> >> --
> >> Philip
> >>
> >>
>

Re: Git add documentation error

[Junio C Hamano]

Angelo Borsotti <angelo.borsotti@gmail.com> writes:

> Then I displayed the contents of both commits, and seen that it is pretty much
> the same:
>
> D:\gittest>git show --pretty="" --name-only 91ef45d
> C2.java
>
> D:\gittest>git show --pretty="" --name-only 8ec0c2f
> C2.java

You did not display the contents of these commits, though.  For each
of these commits, you checked the _difference_ between it and its
parent.

In the previous sequence

>> > I have tested this in the following way: I have two files: C1.java and C2.java
>> >
>> >     > git status
>> >     On branch master
>> >     nothing added to commit
>> >     > ... edit C2.java
>> >     > git status
>> >     On branch master
>> >     Changes not staged for commit:
>> >     (use "git add <file>..." to update what will be committed)
>> >     (use "git restore <file>..." to discard changes in working directory)
>> >         modified:   C2.java
>> >      > git add C1.java
>> >      > git add C2.java
>> >      > git commit -m "commit2"
>> >      D:\gittest>git commit -m "commit1"
>> >      [master 91ef45d] commit1
>> >      1 file changed, 1 insertion(+), 1 deletion(-)

91ef45d, relative to its parent (i.e. the previous state before the
commit was made), C2.java was modified.  C1.java was not.

So, what you saw

> D:\gittest>git show --pretty="" --name-only 91ef45d
> C2.java

is very much consistent with what you did.  And the above does not
mean 91ef45d does not have C1.java.  If you want to "display" the
contents of commit 91ef45d, you could

	$ git ls-tree -r --name-only 91ef45d

which lists all the contents in commit 91ef45d

or

	$ git diff --name-only $(git hash-object --stdin -t tree </dev/null) 91ef45d

which compares all the contents in commit 91ef45d with a completely
empty tree.

In them, you'd see both C1 and C2, among other things that you did
not modify in 91ef45d.

Re: Git add documentation error

[Angelo Borsotti]

Hi

I have displayed the contents of the commits with the command you indicate,
but they still look much the same:

D:\gittest>git ls-tree -r --name-only 91ef45d
C1.java
C2.java
C3.java
C4.java
C5.java


D:\gittest>git ls-tree -r --name-only 8ec0c2f
C1.java
C2.java
C3.java
C4.java
C5.java

I thought that in the second one I would see only the changed file.

-Angelo

On Thu, 27 Oct 2022 at 19:28, Junio C Hamano <gitster@pobox.com> wrote:
>
> Angelo Borsotti <angelo.borsotti@gmail.com> writes:
>
> > Then I displayed the contents of both commits, and seen that it is pretty much
> > the same:
> >
> > D:\gittest>git show --pretty="" --name-only 91ef45d
> > C2.java
> >
> > D:\gittest>git show --pretty="" --name-only 8ec0c2f
> > C2.java
>
> You did not display the contents of these commits, though.  For each
> of these commits, you checked the _difference_ between it and its
> parent.
>
> In the previous sequence
>
> >> > I have tested this in the following way: I have two files: C1.java and C2.java
> >> >
> >> >     > git status
> >> >     On branch master
> >> >     nothing added to commit
> >> >     > ... edit C2.java
> >> >     > git status
> >> >     On branch master
> >> >     Changes not staged for commit:
> >> >     (use "git add <file>..." to update what will be committed)
> >> >     (use "git restore <file>..." to discard changes in working directory)
> >> >         modified:   C2.java
> >> >      > git add C1.java
> >> >      > git add C2.java
> >> >      > git commit -m "commit2"
> >> >      D:\gittest>git commit -m "commit1"
> >> >      [master 91ef45d] commit1
> >> >      1 file changed, 1 insertion(+), 1 deletion(-)
>
> 91ef45d, relative to its parent (i.e. the previous state before the
> commit was made), C2.java was modified.  C1.java was not.
>
> So, what you saw
>
> > D:\gittest>git show --pretty="" --name-only 91ef45d
> > C2.java
>
> is very much consistent with what you did.  And the above does not
> mean 91ef45d does not have C1.java.  If you want to "display" the
> contents of commit 91ef45d, you could
>
>         $ git ls-tree -r --name-only 91ef45d
>
> which lists all the contents in commit 91ef45d
>
> or
>
>         $ git diff --name-only $(git hash-object --stdin -t tree </dev/null) 91ef45d
>
> which compares all the contents in commit 91ef45d with a completely
> empty tree.
>
> In them, you'd see both C1 and C2, among other things that you did
> not modify in 91ef45d.

Re: Git add documentation error

[Junio C Hamano]

Angelo Borsotti <angelo.borsotti@gmail.com> writes:

> Hi
>
> I have displayed the contents of the commits with the command you indicate,
> but they still look much the same:
>
> D:\gittest>git ls-tree -r --name-only 91ef45d
> C1.java
> C2.java
> C3.java
> C4.java
> C5.java
>
>
> D:\gittest>git ls-tree -r --name-only 8ec0c2f
> C1.java
> C2.java
> C3.java
> C4.java
> C5.java
>
> I thought that in the second one I would see only the changed file.

Git tracks contents.  What it means is that you should stop thinking
in terms of "changed files".  Each commit (and its tree) represents
a complete snapshot.  Back when you created 8ec0c2f, did you or did
you not have C1.java?  You said you did not modify it, so I assume
you did have it.  As a commit is a complete snapshot of the
contents, when you list the contents of 8ec0c2f, it should be
included.

To put it another way, if you "git checkout --detach 8ec0c2f" in
order to go back to the state you were back when you created that
commit, do you or do you not want to see C1.java and C2.java?  In
order to be able to reproduce the then-current state, of course
you do want to see, and because each commit is a complete snapshot,
you can see C1 and C2.

"git add C1.java" is a way to make sure that, if you make a commit,
the resulting "snapshot" includes the current contents stored in the
C1.java file as you have on the filesystem at the time of issuing
"git add" command.  If you made or did not make changes to C1.java
before running "git add C1.java" is immaterial.  We may optimize out
and make it a no-op if we know you did not make any changes, but it
does not change the fact that the resulting commit will store, and
more importantly, you will be able to recover, the then-current
contents of C1.java out of that commit.

Re: Git add documentation error

[Angelo Borsotti]

Hi Junio,

> Git tracks contents.  What it means is that you should stop thinking
> in terms of "changed files".  Each commit (and its tree) represents
> a complete snapshot.

Sure. I know it well and know that this is one of the most important
features of git.

> "git add C1.java" is a way to make sure that, if you make a commit,
> the resulting "snapshot" includes the current contents stored in the
> C1.java file as you have on the filesystem at the time of issuing
> "git add" command.

The behavior I have seen tells me that the safest thing to do is to
have a list of the files of the software, and build a script that makes
a git add for each of them, to be run each time before I make a commit.

Concerning the fact that changes are somehow "immaterial", this is
good for a software that is developed by one person, but when there
are several, and the released software has some unwanted changes
in it, one may wonder who changed what. It could happen that a developer
added some changes of his own without telling anybody (perhaps using
files that he has prepared for a next version).

Have a good night
-Angelo

On Thu, 27 Oct 2022 at 20:44, Junio C Hamano <gitster@pobox.com> wrote:
>
> Angelo Borsotti <angelo.borsotti@gmail.com> writes:
>
> > Hi
> >
> > I have displayed the contents of the commits with the command you indicate,
> > but they still look much the same:
> >
> > D:\gittest>git ls-tree -r --name-only 91ef45d
> > C1.java
> > C2.java
> > C3.java
> > C4.java
> > C5.java
> >
> >
> > D:\gittest>git ls-tree -r --name-only 8ec0c2f
> > C1.java
> > C2.java
> > C3.java
> > C4.java
> > C5.java
> >
> > I thought that in the second one I would see only the changed file.
>
> Git tracks contents.  What it means is that you should stop thinking
> in terms of "changed files".  Each commit (and its tree) represents
> a complete snapshot.  Back when you created 8ec0c2f, did you or did
> you not have C1.java?  You said you did not modify it, so I assume
> you did have it.  As a commit is a complete snapshot of the
> contents, when you list the contents of 8ec0c2f, it should be
> included.
>
> To put it another way, if you "git checkout --detach 8ec0c2f" in
> order to go back to the state you were back when you created that
> commit, do you or do you not want to see C1.java and C2.java?  In
> order to be able to reproduce the then-current state, of course
> you do want to see, and because each commit is a complete snapshot,
> you can see C1 and C2.
>
> "git add C1.java" is a way to make sure that, if you make a commit,
> the resulting "snapshot" includes the current contents stored in the
> C1.java file as you have on the filesystem at the time of issuing
> "git add" command.  If you made or did not make changes to C1.java
> before running "git add C1.java" is immaterial.  We may optimize out
> and make it a no-op if we know you did not make any changes, but it
> does not change the fact that the resulting commit will store, and
> more importantly, you will be able to recover, the then-current
> contents of C1.java out of that commit.