[PATCH v4] submodule: allow tracking of the newest revision of a branch in a submodule

[PATCH v4] submodule: allow tracking of the newest revision of a branch in a submodule

[Fabian Franz]

Submodules currently only allow tracking a specific revision
and each update in a submodule leads to a new commit in the
master repository. However some users may want to always track
the newest revision of a specific (named) tag or branch or HEAD.
For example the user might want to track a staging branch in all
submodules.

To allow this the "--track|-t <branch>" parameter was added to
git-submodule.sh, which is added to .gitmodules config file as
well as "track" parameter.

Signed-off-by: Fabian Franz <git@fabian-franz.de>
---

This patch now uses the --assume-unchanged approach to be able to track any
revision in the submodule.

It adresses the issues that were in the comments for the previous patches.

And it does even more, it consists of 5 patches:

(1) allow tracking of the newest revision of a branch in a submodule
----------------------------------------------------------------

Is just handling tracked submodules the same way as if the sha1 sum
was directly in the index (i.e. detached head, checkout by sha1 id)
only that the information comes from the track parameter.
Here one can either track local branches like master or remote branches
via track = origin/master or anything else that is a pathspec. 
(like: refs/remotes/origin/master)

(2) add --no-fetch parameter to update command
----------------------------------------------
 
Junio commented that it was bad that the submodule update needed a
online connection to update. This was true even before the "tracking"
patch and for normal operation can update --no-fetch be useful as well.
This was implemented by first fetching and then checking out instead
of doing it in one step.

(3) add --use-gitmodules parameter to update command 
----------------------------------------------------

Lars correctly commented that the track parameter should be read from
.git/config and also added when init is used.

However there _are_ uses for directly reading .gitmodules and such
not using .git/config for the track parameter.

Example: I want to quickly change my tree to staging mode to test something:

$ git checkout staging
$ git submodule update -u

Now it can be that: submodule one is at master, submodule 2 at staging and
submodule3 at tagXYZ and all this was recorded in .gitmodules, which is more powerful than git submodule foreach "git checkout staging".

(4) add +<branch> syntax for track to allow automatic pulling.
--------------------------------------------------------------

As I inititially already tried, I want some branches that are automatically
pulling when I update the submodules, so I can use the submodule mechanism
to update my tree with updates, but still keep my head attached to my branch.

Syntax for the track parameter is here: +<branchname>

And it does checkout or create branch based on the origin and then do a
git-pull.

Of course conflicts arising need to be fixed manually like normal, but that
is okay, as the person adding that to .git/config or .gitmodules knows what
he/she is doing.

(5) add --recursive parameter to update command
-----------------------------------------------

I just need it. We have a fairly complex setup in the company I work for
and now that we are migrating to git, we find that we have a complex software
inside already one git repository.

And this software is going to use git submodules as well for tracking vendor
dependencies, but this can't (policy) be added to master repository as its
an component by itself.

Anyway recursive operation is lots of fun :).

Example:

$ git submodule update -r audio/
Entering submodule path 'audio/software/'
Submodule path 'dependencies/vendor1': checked out 
'8b3b8ebca95d5a7e09760916ae38e4fe494ad2a2'
Leaving submodule path 'audio/software/'

And we have more software (X11) that can have submodules
inside of submodules.

So, that is all and it works perfect for me and is suited to our
needs.

Let me know, what you think.

Best Wishes,

Fabian
        
 Documentation/git-submodule.txt |   10 +++++-
 git-submodule.sh                |   64 +++++++++++++++++++++++++++++++++++---
 2 files changed, 68 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 2f207fb..232697d 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,7 +9,7 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
-'git submodule' [--quiet] add [-b branch] [--] <repository> <path>
+'git submodule' [--quiet] add [-b branch] [-t|--track <branch>] [--] <repository> <path>
 'git submodule' [--quiet] status [--cached] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] update [--init] [--] [<path>...]
@@ -118,6 +118,10 @@ update::
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
 submodule with the --init option.
++
+If you used --track or set the "track" option this will automatically checkout
+the newest available revision instead of the commit specified in the index of
+the containing repository.
 
 summary::
 	Show commit summary between the given commit (defaults to HEAD) and
@@ -159,6 +163,10 @@ OPTIONS
 --branch::
 	Branch of repository to add as submodule.
 
+-t::
+--track::
+	Branch/Tag/HEAD (pathspec) of repository to track in a submodule.
+
 --cached::
 	This option is only valid for status and summary commands.  These
 	commands typically use the commit found in the submodule HEAD, but
diff --git a/git-submodule.sh b/git-submodule.sh
index 2f47e06..6af3d96 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -5,7 +5,7 @@
 # Copyright (c) 2007 Lars Hjemli
 
 USAGE="[--quiet] [--cached] \
-[add <repo> [-b branch] <path>]|[status|init|update [-i|--init]|summary [-n|--summary-limit <n>] [<commit>]] \
+[add <repo> [-b branch] [--track|-t <branch>] <path>]|[status|init|update [-i|--init]|summary [-n|--summary-limit <n>] [<commit>]] \
 [--] [<path>...]|[foreach <command>]|[sync [--] [<path>...]]"
 OPTIONS_SPEC=
 . git-sh-setup
@@ -16,6 +16,7 @@ command=
 branch=
 quiet=
 cached=
+track=
 
 #
 # print stuff on stdout unless -q was specified
@@ -130,6 +131,11 @@ cmd_add()
 		-q|--quiet)
 			quiet=1
 			;;
+		-t|--track)
+			case "$2" in '') usage ;; esac
+			track=$2
+			shift
+			;;
 		--)
 			shift
 			break
@@ -201,8 +207,11 @@ cmd_add()
 	git add "$path" ||
 	die "Failed to add submodule '$path'"
 
+	test -n "$track" && git-update-index --assume-unchanged "$path"
+
 	git config -f .gitmodules submodule."$path".path "$path" &&
 	git config -f .gitmodules submodule."$path".url "$repo" &&
+	git config -f .gitmodules submodule."$path".track "$track" &&
 	git add .gitmodules ||
 	die "Failed to register submodule '$path'"
 }
@@ -277,6 +286,10 @@ cmd_init()
 		git config submodule."$name".url "$url" ||
 		die "Failed to register url for submodule path '$path'"
 
+		track=$(git config -f .gitmodules submodule."$name".track)
+		git config submodule."$name".track "$track" ||
+		die "Failed to register track for submodule path '$path'"
+
 		say "Submodule '$name' ($url) registered for path '$path'"
 	done
 }
@@ -328,6 +341,15 @@ cmd_update()
 			continue
 		fi
 
+		track=$(git config submodule."$name".track)
+		if test -n "$track"
+		then
+			git-update-index --assume-unchanged "$path"
+			sha1="NULL"
+		else
+			git-update-index --no-assume-unchanged "$path"
+		fi
+
 		if ! test -d "$path"/.git -o -f "$path"/.git
 		then
 			module_clone "$path" "$url" || exit
@@ -345,11 +367,42 @@ cmd_update()
 			then
 				force="-f"
 			fi
-			(unset GIT_DIR; cd "$path" && git-fetch &&
-				git-checkout $force -q "$sha1") ||
+
+			# First fetch ...
+
+			(unset GIT_DIR; cd "$path" &&
+				git-fetch) ||
+			die "Unable to fetch in submodule path '$path'"
+
+			if test "$sha1" = "NULL"
+			then
+				: ${track:="HEAD"}
+
+				sha1=$(unset GIT_DIR; cd "$path" &&
+					git-rev-parse --verify --quiet "$track")
+
+				# Only use $origin/$track path if the user
+				# supplied path does not work
+				if test -z "$sha1"
+				then
+					origin=$(unset GIT_DIR; cd "$path" &&
+						get_default_remote) ||
+					die "Unable to get default remote destination in submodule path '$path'."
+					track="$origin/$track"
+
+					sha1=$(unset GIT_DIR; cd "$path" &&
+						git-rev-parse --verify "$track") ||
+					die "Unable to find newest revision of '$track' in submodule path '$path'."
+				fi
+			fi
+
+			# ... then checkout
+
+			(unset GIT_DIR; cd "$path" &&
+				  git-checkout $force -q "$sha1") ||
 			die "Unable to checkout '$sha1' in submodule path '$path'"
 
-			say "Submodule path '$path': checked out '$sha1'"
+			say "Submodule path '$path': checked out '$sha1'${track:+ ($track)}"
 		fi
 	done
 }
@@ -596,7 +649,8 @@ cmd_status()
 		set_name_rev "$path" "$sha1"
 		if git diff-files --quiet -- "$path"
 		then
-			say " $sha1 $path$revname"
+			track=$(git config submodule."$name".track)
+			say " $sha1 $path$revname${track:+ (tracking "$track")}"
 		else
 			if test -z "$cached"
 			then
-- 
1.5.3.6

[PATCH v4] submodule: add --no-fetch parameter to update command

[Fabian Franz]

git submodule update --no-fetch makes it possible to use git submodule
update in complete offline mode by not fetching new revisions.

Signed-off-by: Fabian Franz <git@fabian-franz.de>
---
 Documentation/git-submodule.txt |    7 ++++++-
 git-submodule.sh                |   16 ++++++++++++----
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 232697d..14c1d5c 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 'git submodule' [--quiet] add [-b branch] [-t|--track <branch>] [--] <repository> <path>
 'git submodule' [--quiet] status [--cached] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] update [--init] [--] [<path>...]
+'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--] [<path>...]
 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
 'git submodule' [--quiet] foreach <command>
 'git submodule' [--quiet] sync [--] [<path>...]
@@ -180,6 +180,11 @@ OPTIONS
 	(the default). This limit only applies to modified submodules. The
 	size is always limited to 1 for added/deleted/typechanged submodules.
 
+-N::
+--no-fetch::
+	This option is only valid for the update command.
+	Don't fetch new objects from the remote site.
+
 <path>...::
 	Paths to submodule(s). When specified this will restrict the command
 	to only operate on the submodules found at the specified paths.
diff --git a/git-submodule.sh b/git-submodule.sh
index 6af3d96..f66622b 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -5,7 +5,7 @@
 # Copyright (c) 2007 Lars Hjemli
 
 USAGE="[--quiet] [--cached] \
-[add <repo> [-b branch] [--track|-t <branch>] <path>]|[status|init|update [-i|--init]|summary [-n|--summary-limit <n>] [<commit>]] \
+[add <repo> [-b branch] [--track|-t <branch>] <path>]|[status|init|update [-i|--init] [-N|--no-fetch]|summary [-n|--summary-limit <n>] [<commit>]] \
 [--] [<path>...]|[foreach <command>]|[sync [--] [<path>...]]"
 OPTIONS_SPEC=
 . git-sh-setup
@@ -17,6 +17,7 @@ branch=
 quiet=
 cached=
 track=
+nofetch=
 
 #
 # print stuff on stdout unless -q was specified
@@ -313,6 +314,10 @@ cmd_update()
 			shift
 			cmd_init "$@" || return
 			;;
+		-N|--no-fetch)
+			shift
+			nofetch=1
+			;;
 		--)
 			shift
 			break
@@ -370,9 +375,12 @@ cmd_update()
 
 			# First fetch ...
 
-			(unset GIT_DIR; cd "$path" &&
-				git-fetch) ||
-			die "Unable to fetch in submodule path '$path'"
+			if test -z "$nofetch"
+			then
+				(unset GIT_DIR; cd "$path" &&
+					git-fetch) ||
+				die "Unable to fetch in submodule path '$path'"
+			fi
 
 			if test "$sha1" = "NULL"
 			then
-- 
1.5.3.6

[PATCH v4] submodule: add --use-gitmodules parameter to update command

[Fabian Franz]

When -u|--use-gitmodules is given the update command uses the .gitmodules
config file instead of the .git/config file to obtain the track parameter.
This makes it for example possible to change branches for all submodules
at the same time without having to sync up .git/config first.

Signed-off-by: Fabian Franz <git@fabian-franz.de>
---
 Documentation/git-submodule.txt |    8 +++++++-
 git-submodule.sh                |    9 ++++++++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 14c1d5c..175b4b5 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 'git submodule' [--quiet] add [-b branch] [-t|--track <branch>] [--] <repository> <path>
 'git submodule' [--quiet] status [--cached] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--] [<path>...]
+'git submodule' [--quiet] update [--init] [-N|--no-fetch] [-u|--use-gitmodules] [--] [<path>...]
 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
 'git submodule' [--quiet] foreach <command>
 'git submodule' [--quiet] sync [--] [<path>...]
@@ -185,6 +185,12 @@ OPTIONS
 	This option is only valid for the update command.
 	Don't fetch new objects from the remote site.
 
+-u::
+--use-gitmodules::
+	This option is only valid for the update command.
+	Use the tracking information found in .gitmodules
+	(track) and ignore .git/config.
+
 <path>...::
 	Paths to submodule(s). When specified this will restrict the command
 	to only operate on the submodules found at the specified paths.
diff --git a/git-submodule.sh b/git-submodule.sh
index f66622b..81b96dd 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -5,7 +5,7 @@
 # Copyright (c) 2007 Lars Hjemli
 
 USAGE="[--quiet] [--cached] \
-[add <repo> [-b branch] [--track|-t <branch>] <path>]|[status|init|update [-i|--init] [-N|--no-fetch]|summary [-n|--summary-limit <n>] [<commit>]] \
+[add <repo> [-b branch] [--track|-t <branch>] <path>]|[status|init|update [-i|--init] [-N|--no-fetch] [-u|--use-gitmodules]|summary [-n|--summary-limit <n>] [<commit>]] \
 [--] [<path>...]|[foreach <command>]|[sync [--] [<path>...]]"
 OPTIONS_SPEC=
 . git-sh-setup
@@ -18,6 +18,7 @@ quiet=
 cached=
 track=
 nofetch=
+usegitmodules=
 
 #
 # print stuff on stdout unless -q was specified
@@ -318,6 +319,10 @@ cmd_update()
 			shift
 			nofetch=1
 			;;
+		-u|--use-gitmodules)
+			shift
+			usegitmodules=1
+			;;
 		--)
 			shift
 			break
@@ -347,6 +352,8 @@ cmd_update()
 		fi
 
 		track=$(git config submodule."$name".track)
+		test -n "$usegitmodules" &&
+			track=$(git config -f .gitmodules submodule."$name".track)
 		if test -n "$track"
 		then
 			git-update-index --assume-unchanged "$path"
-- 
1.5.3.6

[PATCH v4] submodule: add +<branch> syntax for track to allow automatic pulling.

[Fabian Franz]

When the track parameter is set to +<branch>, on update command a
new branch is created tracking the remote branch (if it does not
yet exist). Then the branch is checked out and git-pull is run.

Signed-off-by: Fabian Franz <git@fabian-franz.de>
---
 Documentation/git-submodule.txt |    3 +++
 git-submodule.sh                |   26 ++++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 175b4b5..fbb18ee 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -166,6 +166,9 @@ OPTIONS
 -t::
 --track::
 	Branch/Tag/HEAD (pathspec) of repository to track in a submodule.
+	If you give +<branch> as parameter, a new branch will be created and
+	setup to track the remote branch. Then on update git-pull is used to
+	update the branch.
 
 --cached::
 	This option is only valid for status and summary commands.  These
diff --git a/git-submodule.sh b/git-submodule.sh
index 81b96dd..54b59b2 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -372,6 +372,32 @@ cmd_update()
 			die "Unable to find current revision in submodule path '$path'"
 		fi
 
+		pull=
+		case "$track" in
+			"+"*)
+				pull=1
+				track=${track#+}
+			;;
+		esac
+
+		if test -n "$pull"
+		then
+			say "Pulling updates for branch '$track' for submodule path '$path'"
+			origin=$(unset GIT_DIR; cd "$path" &&
+				get_default_remote) ||
+			die "Unable to get default remote destination in submodule path '$path'."
+			(unset GIT_DIR; cd "$path" &&
+				git-rev-parse --verify --quiet "refs/heads/$track" >/dev/null || 
+				git-branch --track "$track" "$origin/$track") || 
+			die "Unable to create branch '$track' in submodule path '$path'"
+
+			(unset GIT_DIR; cd "$path" &&
+				git-checkout -q "$track" &&
+				git-pull ${quiet:+-q}) ||
+			die "Unable to pull for branch '$track' in submodule path '$path'"
+			sha1="$track"
+		fi
+
 		if test "$subsha1" != "$sha1"
 		then
 			force=
-- 
1.5.3.6

[PATCH v4] submodule: add --recursive parameter to update command

[Fabian Franz]

If --recursive is specified on update, then recursively check for
.gitmodules in each updated submodule and run init and update commands.
The update command is run with the same parameters as the original update
command with the exception of the path.

Signed-off-by: Fabian Franz <git@fabian-franz.de>
---
 Documentation/git-submodule.txt |    8 ++++++++
 git-submodule.sh                |   17 ++++++++++++++++-
 2 files changed, 24 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index fbb18ee..c9adc43 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -188,6 +188,14 @@ OPTIONS
 	This option is only valid for the update command.
 	Don't fetch new objects from the remote site.
 
+-r::
+--recursive::
+	This option is only valid for the update command.
+	Recursively check for .gitmodules in each updated submodule and run
+	init and update commands. The update command is run with the same
+	parameters as the original update command with the exception of the
+	path.
+
 -u::
 --use-gitmodules::
 	This option is only valid for the update command.
diff --git a/git-submodule.sh b/git-submodule.sh
index 54b59b2..8bb00b7 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -5,7 +5,7 @@
 # Copyright (c) 2007 Lars Hjemli
 
 USAGE="[--quiet] [--cached] \
-[add <repo> [-b branch] [--track|-t <branch>] <path>]|[status|init|update [-i|--init] [-N|--no-fetch] [-u|--use-gitmodules]|summary [-n|--summary-limit <n>] [<commit>]] \
+[add <repo> [-b branch] [--track|-t <branch>] <path>]|[status|init|update [-i|--init] [-N|--no-fetch] [-r|--recursive] [-u|--use-gitmodules]|summary [-n|--summary-limit <n>] [<commit>]] \
 [--] [<path>...]|[foreach <command>]|[sync [--] [<path>...]]"
 OPTIONS_SPEC=
 . git-sh-setup
@@ -19,6 +19,7 @@ cached=
 track=
 nofetch=
 usegitmodules=
+recursive=
 
 #
 # print stuff on stdout unless -q was specified
@@ -319,6 +320,10 @@ cmd_update()
 			shift
 			nofetch=1
 			;;
+		-r|--recursive)
+			shift
+			recursive=1
+			;;
 		-u|--use-gitmodules)
 			shift
 			usegitmodules=1
@@ -445,6 +450,16 @@ cmd_update()
 
 			say "Submodule path '$path': checked out '$sha1'${track:+ ($track)}"
 		fi
+		if test -n "$recursive" -a -f "$path/.gitmodules"
+		then
+			PARAMS="${quiet:+-q} ${nofetch:+--no-fetch} ${recursive:+-r} ${usegitmodules:+-u}"
+			say "Entering submodule path '$path'"
+			(unset GIT_DIR; cd "$path" &&
+				  git-submodule init &&
+				  git-submodule update $PARAMS) ||
+			die "Unable to run 'git-submodule update $PARAMS' in submodule path '$path'"
+			say "Leaving submodule path '$path'"
+		fi
 	done
 }
 
-- 
1.5.3.6

Re: [PATCH v4] submodule: allow tracking of the newest revision of a branch in a submodule

[Johannes Schindelin]

Hi,

On Sat, 10 Jan 2009, Fabian Franz wrote:

> Submodules currently only allow tracking a specific revision and each 
> update in a submodule leads to a new commit in the master repository. 
> However some users may want to always track the newest revision of a 
> specific (named) tag or branch or HEAD. For example the user might want 
> to track a staging branch in all submodules.

I wonder how you want to deal with "git bisect".  Or for that matter, with 
"git checkout HEAD^500".

Ciao,
Dscho

Re: [PATCH v4] submodule: add --no-fetch parameter to update command

[Nanako Shiraishi]

Quoting Fabian Franz <git@fabian-franz.de> writes:

> git submodule update --no-fetch makes it possible to use git submodule
> update in complete offline mode by not fetching new revisions.

I may be confused, but does it make any sense to update without fetching?

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH v4] submodule: add --no-fetch parameter to update command

[Nanako Shiraishi]

Quoting Fabian Franz <git@fabian-franz.de> writes:

> When -u|--use-gitmodules is given the update command uses the .gitmodules
> config file instead of the .git/config file to obtain the track parameter.
> This makes it for example possible to change branches for all submodules
> at the same time without having to sync up .git/config first.
>
> Signed-off-by: Fabian Franz <git@fabian-franz.de>

Once you start doing that, doesn't it force you to always bypass .git/config, making the current mechanism even less useful?  If you find that "having to sync up .git/config first" is inconvenient, wouldn't it be more useful for your patch if it made it easier and more convenient the procedure "to sync up .git/config first", instead of bypassing the current setup?

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH v4] submodule: add +<branch> syntax for track to allow automatic pulling.

[Junio C Hamano]

Fabian Franz <git@fabian-franz.de> writes:

> When the track parameter is set to +<branch>, on update command a
> new branch is created tracking the remote branch (if it does not
> yet exist). Then the branch is checked out and git-pull is run.

Usually a "+" in front of a refspec means "allow forcing non-ff update",
but here it means completely different thing.  The syntax is confusing.

But that aside, I do not know if the semantics of this patch makes sense
to begin with.

Should this really be a persistent property of a submodule?  With your
patch, this is always triggered for modules you did "--track +branch" when
you added them, but (1) not for others you did not say "+" when you added,
and (2) you cannot disable the auto-pull for the ones you did even if you
wanted to.  It feels it might be better to make it a property of one
particular invocation of "update" action, and more generally, the entire
series feels like a very specific hack that is meant to cover/impose your
particular workflow (and not others').

Don't get me wrong.  I do not see any problem in supporing it well, if
that particular workflow is a good workflow and a generally applicable
one.

But I do not think it is documented well enough.  "--track creates one
configuration in the .git/config file" and "update always checks out the
tip of the named branch if such configuration is set" may be fine
descriptions of what each piece does.  The readers will be left puzzled
without an explanation of the bigger picture to understand why it is
(sometimes) a good idea to make these pieces do what they do.