What does git add --intent-to-add or -N do and when should it be used?

Question

On git add -h I can see the following option:

-N, --intent-to-add   record only the fact that the path will be added later

But

Answer 1

Note that before git 2.10 (Q3 2016), git add -N can sometime skips some entries.

See commit 6d6a782, commit c041d54, commit 378932d, commit f9e7d9f (16 Jul 2016) by Nguyễn Thái Ngọc Duy (pclouds).
^{(Merged by Junio C Hamano -- gitster -- in commit 3cc75c1, 25 Jul 2016)}

If you have:

a-file
subdir/file1
subdir/file2
subdir/file3
the-last-file

And you add -N everything... then subdir files are not recorded as i-t-a ("intended to add") entries.

cache-tree.c: fix i-t-a entry skipping directory updates sometimes

Commit 3cf773e (cache-tree: fix writing cache-tree when CE_REMOVE is present - 2012-12-16 - Git v1.8.1.1) skips i-t-a entries when building trees objects from the index. Unfortunately it may skip too much.

If subdir/file1 is an i-t-a, because of the broken condition in this code, we still think "subdir" is an i-t-a file and not writing "subdir" down and jump to the-last-file.
The result tree now only has two items: a-file and the-last-file.
subdir should be there too (even though it only records two sub-entries, file2 and file3).

---

git status has improved, with Git 2.17 (Q2 2018, four years laters): after moving a path in the working tree (hence making it appear "removed") and then adding with the -N option (hence making that appear "added"), git status detected it as a rename, but did not report the old and new pathnames correctly.

See commit 176ea74, commit 5134ccd, commit ea56f97, commit 98bc94e, commit 06dba2b, commit 6de5aaf (27 Dec 2017) by Nguyễn Thái Ngọc Duy (pclouds).
Helped-by: Igor Djordjevic (boogisha).
^{(Merged by Junio C Hamano -- gitster -- in commit 12accdc, 27 Feb 2018)}.

Reminder: ita or i-t-a stands for "intended-to-add", what -N does.

wt-status.c: handle worktree renames

Before 425a28e (diff-lib: allow ita entries treated as "not yet exist in index" - 2016-10-24, Git 2.11.0-rc0) there are never "new files" in the index, which essentially disables rename detection because we only detect renames when a new file appears in a diff pair.

After that commit, an i-t-a entry can appear as a new file in "git diff-files". But the diff callback function in wt-status.c does not handle this case and produces incorrect status output.