[PATCH v2 5/5] Documentation: add --include_ignored_submodules + ignore=all config

["Claus Schneider(Eficode) via GitGitGadget" <gitgitgadget@gmail.com>]

From: "Claus Schneider(Eficode)" <claus.schneider@eficode.com>

- git-add.adoc: Add new documentation for --include_ignored_submodules
  option to supress ignore=all and new submodule functionality of not
  adding a ignore=all submodule by default.
- gitmodules.adoc and config/submodule.adoc: The submodule config
  ignore=all now need --include_ignored_submodules in order to update
  the index.

Signed-off-by: Claus Schneider(Eficode) <claus.schneider@eficode.com>
---
 .devcontainer/Dockerfile            | 70 ++++++++++++++++++++++++++
 .devcontainer/Dockerfile.standalone | 76 +++++++++++++++++++++++++++++
 .devcontainer/devcontainer.json     | 25 ++++++++++
 Documentation/config/submodule.adoc | 13 ++---
 Documentation/git-add.adoc          |  5 ++
 Documentation/gitmodules.adoc       |  5 +-
 6 files changed, 187 insertions(+), 7 deletions(-)
 create mode 100644 .devcontainer/Dockerfile
 create mode 100644 .devcontainer/Dockerfile.standalone
 create mode 100644 .devcontainer/devcontainer.json

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 0000000000..680ca5f3ad
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,70 @@
+FROM ubuntu:latest
+
+ARG USER_ID
+ARG GROUP_ID
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=Europe/Copenhagen
+
+RUN apt-get update \
+    && \
+    apt-get install -y \
+        sudo \
+        build-essential \
+        libcurl4-gnutls-dev \
+        libexpat1-dev \
+        gettext \
+        libz-dev \
+        libssl-dev \
+        asciidoc \
+        xmlto \
+        docbook-xsl \
+        \
+        tzdata \
+        git \
+        coccinelle \
+    && \
+    ln -fs /usr/share/zoneinfo/$TZ /etc/localtime \
+    && \
+    dpkg-reconfigure --frontend noninteractive tzdata
+
+RUN  apt-get update && apt-get install -y autoconf
+
+RUN addgroup -gid 1001 gituser
+RUN adduser --disabled-password -u 1001 -gid 1001 gituser
+RUN usermod -aG sudo gituser
+RUN echo 'gituser ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/010-gituser
+RUN chmod 0440 /etc/sudoers.d/010-gituser
+
+USER 1001
+
+#WORKDIR /home/gituser/git-src/
+
+#RUN  make configure
+#RUN ./configure --prefix=${HOME}/.local/
+
+#RUN make -j$(nproc) gitweb || make gitweb 
+#RUN make install-gitweb
+
+#RUN make -j$(nproc) || make
+#RUN make -j$(nproc) gitweb || make gitweb 
+#RUN make install-gitweb
+#RUN make -j$(nproc) NO_PERL=YesPlease install || make NO_PERL=YesPlease install
+#RUN make install
+
+
+RUN mkdir -p  ${HOME}/.local/
+#RUN ls -la ${HOME}/.local/bin
+#ENV PATH="/home/gituser/.local/bin:${PATH}"
+#RUN ls -l $HOME/.local/bin
+#RUN echo $PATH $HOME 
+
+#RUN git --version
+#RUN which git 
+
+RUN git config --global user.email "gituser@example.com"
+RUN git config --global user.name "Git User"
+
+#WORKDIR /home/gituser/git-test/
+
+#CMD [ "git" ]
diff --git a/.devcontainer/Dockerfile.standalone b/.devcontainer/Dockerfile.standalone
new file mode 100644
index 0000000000..39bda42c0e
--- /dev/null
+++ b/.devcontainer/Dockerfile.standalone
@@ -0,0 +1,76 @@
+FROM ubuntu:latest
+
+ARG USER_ID
+ARG GROUP_ID
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=Europe/Copenhagen
+
+RUN apt-get update \
+    && \
+    apt-get install -y \
+        build-essential \
+        libcurl4-gnutls-dev \
+        libexpat1-dev \
+        gettext \
+        libz-dev \
+        libssl-dev \
+        asciidoc \
+        xmlto \
+        docbook-xsl \
+        \
+        tzdata \
+        \
+        nano \
+        vim \
+    && \
+    ln -fs /usr/share/zoneinfo/$TZ /etc/localtime \
+    && \
+    dpkg-reconfigure --frontend noninteractive tzdata
+
+RUN  apt-get update && apt-get install -y autoconf
+
+RUN addgroup -gid ${GROUP_ID} gituser
+RUN adduser --disabled-password -u ${USER_ID} -gid ${GROUP_ID} gituser
+
+
+COPY --chown=${USER_ID}:${GROUP_ID} ./git /home/gituser/git-src/
+
+USER ${USER_ID}
+
+WORKDIR /home/gituser/git-src/
+
+RUN  make configure
+RUN ./configure --prefix=${HOME}/.local/
+
+#RUN make -j$(nproc) gitweb || make gitweb 
+#RUN make install-gitweb
+
+#RUN make -j$(nproc) || make
+#RUN make -j$(nproc) gitweb || make gitweb 
+#RUN make install-gitweb
+RUN make -j$(nproc) NO_PERL=YesPlease install || make NO_PERL=YesPlease install
+RUN make install
+
+WORKDIR /home/gituser/git-src/t
+RUN ./t2206-add-submodule-ignored.sh -v
+
+RUN ls -la ${HOME}/.local/
+RUN ls -la ${HOME}/.local/bin
+ENV PATH="/home/gituser/.local/bin:${PATH}"
+RUN ls -l $HOME/.local/bin
+RUN echo $PATH $HOME 
+
+RUN git --version
+RUN which git 
+
+RUN git config --global user.email "gituser@example.com"
+RUN git config --global user.name "Git User"
+
+WORKDIR /home/gituser/git-src/t
+RUN pwd && ls -la 
+RUN ./t2206-add-submodule-ignored.sh -v
+
+WORKDIR /home/gituser/git-test/
+
+CMD [ "git" ]
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000000..2bc13902d8
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,25 @@
+{
+  "name": "Git Dev Container",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "",
+    "args": {
+      "user_id": "1001",
+      "group_id": "1001"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.shell.linux": "/bin/bash"
+      }
+    }
+  },
+  "remoteUser": "gituser",
+  "features": {},
+  "mounts": [
+    "source=${localWorkspaceFolder}/,target=/home/gitusers/git-src,type=bind,consistency=cached",
+    "source=${localWorkspaceFolder}/,target=/home/gitusers/git-test,type=bind,consistency=cached"
+  ],
+  "postCreateCommand": "echo"
+}
diff --git a/Documentation/config/submodule.adoc b/Documentation/config/submodule.adoc
index 0672d99117..0753adbab5 100644
--- a/Documentation/config/submodule.adoc
+++ b/Documentation/config/submodule.adoc
@@ -32,15 +32,16 @@ submodule.<name>.fetchRecurseSubmodules::
 
 submodule.<name>.ignore::
 	Defines under what circumstances "git status" and the diff family show
-	a submodule as modified. When set to "all", it will never be considered
-	modified (but it will nonetheless show up in the output of status and
-	commit when it has been staged), "dirty" will ignore all changes
-	to the submodule's work tree and
+	a submodule as modified.
+	Set to "all" will never considered the submodule modified. It can
+	nevertheless be staged using the option --include_ignored_submodules and
+	it will then show up in the output of status.
+	Set to "dirty" will ignore all changes to the submodule's work tree and
 	takes only differences between the HEAD of the submodule and the commit
 	recorded in the superproject into account. "untracked" will additionally
 	let submodules with modified tracked files in their work tree show up.
-	Using "none" (the default when this option is not set) also shows
-	submodules that have untracked files in their work tree as changed.
+	Set to "none"(default) It is also shows submodules that have untracked
+	files in their work tree as changed.
 	This setting overrides any setting made in .gitmodules for this submodule,
 	both settings can be overridden on the command line by using the
 	"--ignore-submodules" option. The 'git submodule' commands are not
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index b7a735824d..ab72fad651 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -79,6 +79,11 @@ in linkgit:gitglossary[7].
 `--force`::
 	Allow adding otherwise ignored files.
 
+`--include_ignored_submodules`::
+	The option is also used when `submodule.<name>.ignore=all`
+	is set, but you want to stage an update of the submodule. The
+	`path` to the submodule must be explicitly specified.
+
 `--sparse`::
 	Allow updating index entries outside of the sparse-checkout cone.
 	Normally, `git add` refuses to update index entries whose paths do
diff --git a/Documentation/gitmodules.adoc b/Documentation/gitmodules.adoc
index d9bec8b187..ea1fd377e6 100644
--- a/Documentation/gitmodules.adoc
+++ b/Documentation/gitmodules.adoc
@@ -70,7 +70,10 @@ submodule.<name>.ignore::
 --
 	all;; The submodule will never be considered modified (but will
 	    nonetheless show up in the output of status and commit when it has
-	    been staged).
+	    been staged). Add `(new commits)` can be overruled using the
+	    `git add --include_ignored_submodules <submodule.path>` 
+		The setting affects `status`, `update-index`, `diff` and `log`(due 
+		to underlaying `diff`).
 
 	dirty;; All changes to the submodule's work tree will be ignored, only
 	    committed differences between the `HEAD` of the submodule and its
-- 
gitgitgadget