Add information about usage with nested subrepos

ReadMe.pod

@@ -672,6 +672,76 @@ C<irc.freenode.net>.
 
 =back
 
+=head1 Working with nested subrepos
+
+C<git-subrepo> supports adding subrepos which themselves make use of subrepos.
+In fact, subrepo itself is built this way. Take a look in the C<ext/> folder,
+it houses 2 dependencies as subrepos, C<test-more-bash> and C<bashplus>.
+
+C<test-more-bash> itself depends on 2 more subrepos: C<bashplus> again, and
+C<test-tap-bash>.
+
+The structure is therefore as follows:
+
+    git-subrepo
+      |- bashplus
+      |- test-more-bash
+        |- bashplus
+        |- test-tap-bash
+
+However, it's important to understand how this works. Here's the key idea:
+there is B<no> special handling for nested subrepos.
+
+When you clone a subrepo, B<all> C<git-subrepo> does is download the code and
+set up the subrepo file. This means that all the subrepo commands simply act
+on the subrepo as a whole, treating nested subrepos like any other part of the
+source code.
+
+Let's look at what this means in practice. Say you have a structure as
+follows:
+
+    app-foo
+      |- barlib
+         |- bazlib
+
+You're working on app-foo, and make some changes to bazlib. How should you
+upstream these changes?
+
+Well, first you must realize that from the perspective of app-foo,
+you've simply made some changes to barlib. Whether or not those changes
+were themselves in a subrepo is irrelevant. So, just like any other
+changes, you run
+
+C<git subrepo push barlib>
+
+Now, if C<barlib> is a library you don't maintain, your responsibility would
+end here. C<barlib>'s maintainer would see your changes and decide what to do
+with them.
+
+If you do maintain C<barlib>, you might now want to upstream the changes all
+the way into C<bazlib>. You could be tempted to try running something like:
+
+C<git subrepo push barlib/bazlib>
+
+but you'll soon find out that doesn't work. C<app-foo> doesn't know anything
+about the link between C<barlib> and C<bazlib>.
+
+What you should do is treat the changes to C<barlib> as if they would come
+from another contributor, aka:
+
+=over
+
+=item * go to a local copy of C<barlib>
+
+=item * pull down the changes with a C<git pull>
+
+=item * you notice the changes include some work on your subrepo, time to upstream them: C<git subrepo push bazlib>
+
+=back
+
+And you're done! One final step you'll likely want to do is to go back to C<app-foo> and run C<git subrepo pull barlib>, because the push you just did added a
+new commit.
+
 =head1 Authors
 
 =over

doc/git-subrepo.swim

@@ -599,6 +599,73 @@ If you want to chat about the `git-subrepo` command, join `#gitcommands` on
 * Written in (very modern) Bash, with full test suite. Take a look.
 * A `.gitrepo` file never is in the top level dir (next to a `.git/` dir).
 
+= Working with nested subrepos
+
+`git-subrepo` supports adding subrepos which themselves make use of
+subrepos. In fact, subrepo itself is built this way. Take a look in the
+`ext/` folder, it houses 2 dependencies as subrepos, `test-more-bash` and
+`bashplus`. 
+
+`test-more-bash` itself depends on 2 more subrepos: `bashplus` again, and
+`test-tap-bash`.
+
+The structure is therefore as follows:
+
+  git-subrepo
+    |- bashplus
+    |- test-more-bash
+      |- bashplus
+      |- test-tap-bash
+
+However, it's important to understand how this works. Here's the key idea:
+there is *no* special handling for nested subrepos. 
+
+When you clone a subrepo, *all* `git-subrepo` does is download the code 
+and set up the subrepo file. 
+This means that all the subrepo commands simply act on the subrepo as a whole,
+treating nested subrepos like any other part of the source code. 
+
+Let's look at what this means in practice. Say you have a structure as follows:
+
+  app-foo
+    |- barlib
+       |- bazlib
+
+You're working on app-foo, and make some changes to bazlib. How should you
+upstream these changes?
+
+Well, first you must realize that from the perspective of app-foo, you've simply
+made some changes to barlib. Whether or not those changes were themselves in a
+subrepo is irrelevant. So, just like any other changes, you run
+
+`git subrepo push barlib`
+
+Now, if `barlib` is a library you don't maintain, your responsibility would end
+here. `barlib`'s maintainer would see your changes and decide what to do with
+them. 
+
+If you do maintain `barlib`, you might now want to upstream the changes all the
+way into `bazlib`. You could be tempted to try running something like:
+
+`git subrepo push barlib/bazlib`
+
+but you'll soon find out that doesn't work. 
+`app-foo` doesn't know anything about the link between `barlib` and `bazlib`.
+
+What you should do is treat the changes to `barlib` as if they would come from
+another contributor, aka:
+
+* go to a local copy of `barlib`
+* pull down the changes with a `git pull`
+* you notice the changes include some work on your subrepo, time to upstream
+  them:
+  `git subrepo push bazlib`
+
+And you're done! One final step you'll likely want to do is to go back to
+`app-foo` and run `git subrepo pull barlib`, because the push you just did added
+a new commit.
+
+
 = Authors
 
 * Ingy döt Net <[email protected]>

man/man1/git-subrepo.1

@@ -1,5 +1,5 @@
 .\" -*- mode: troff; coding: utf-8 -*-
-.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -55,7 +55,7 @@
 .\" ========================================================================
 .\"
 .IX Title "STDIN 1"
-.TH STDIN 1 2024-07-22 "Generated by Swim v0.1.48" "Git Submodule Alternative"
+.TH STDIN 1 2024-08-31 "Generated by Swim v0.1.48" "Git Submodule Alternative"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -712,6 +712,75 @@ The \f(CW\*(C`git\-subrepo\*(C'\fR repo itself has 2 subrepos under the \f(CW\*(
 Written in (very modern) Bash, with full test suite. Take a look.
 .IP \(bu 4
 A \f(CW\*(C`.gitrepo\*(C'\fR file never is in the top level dir (next to a \f(CW\*(C`.git/\*(C'\fR dir).
+.SH "Working with nested subrepos"
+.IX Header "Working with nested subrepos"
+\&\f(CW\*(C`git\-subrepo\*(C'\fR supports adding subrepos which themselves make use of subrepos.
+In fact, subrepo itself is built this way. Take a look in the \f(CW\*(C`ext/\*(C'\fR folder,
+it houses 2 dependencies as subrepos, \f(CW\*(C`test\-more\-bash\*(C'\fR and \f(CW\*(C`bashplus\*(C'\fR.
+.PP
+\&\f(CW\*(C`test\-more\-bash\*(C'\fR itself depends on 2 more subrepos: \f(CW\*(C`bashplus\*(C'\fR again, and
+\&\f(CW\*(C`test\-tap\-bash\*(C'\fR.
+.PP
+The structure is therefore as follows:
+.PP
+.Vb 5
+\&    git\-subrepo
+\&      |\- bashplus
+\&      |\- test\-more\-bash
+\&        |\- bashplus
+\&        |\- test\-tap\-bash
+.Ve
+.PP
+However, it's important to understand how this works. Here's the key idea:
+there is \fBno\fR special handling for nested subrepos.
+.PP
+When you clone a subrepo, \fBall\fR \f(CW\*(C`git\-subrepo\*(C'\fR does is download the code and
+set up the subrepo file. This means that all the subrepo commands simply act
+on the subrepo as a whole, treating nested subrepos like any other part of the
+source code.
+.PP
+Let's look at what this means in practice. Say you have a structure as
+follows:
+.PP
+.Vb 3
+\&    app\-foo
+\&      |\- barlib
+\&         |\- bazlib
+.Ve
+.PP
+You're working on app-foo, and make some changes to bazlib. How should you
+upstream these changes?
+.PP
+Well, first you must realize that from the perspective of app-foo,
+you've simply made some changes to barlib. Whether or not those changes
+were themselves in a subrepo is irrelevant. So, just like any other
+changes, you run
+.PP
+\&\f(CW\*(C`git subrepo push barlib\*(C'\fR
+.PP
+Now, if \f(CW\*(C`barlib\*(C'\fR is a library you don't maintain, your responsibility would
+end here. \f(CW\*(C`barlib\*(C'\fR's maintainer would see your changes and decide what to do
+with them.
+.PP
+If you do maintain \f(CW\*(C`barlib\*(C'\fR, you might now want to upstream the changes all
+the way into \f(CW\*(C`bazlib\*(C'\fR. You could be tempted to try running something like:
+.PP
+\&\f(CW\*(C`git subrepo push barlib/bazlib\*(C'\fR
+.PP
+but you'll soon find out that doesn't work. \f(CW\*(C`app\-foo\*(C'\fR doesn't know anything
+about the link between \f(CW\*(C`barlib\*(C'\fR and \f(CW\*(C`bazlib\*(C'\fR.
+.PP
+What you should do is treat the changes to \f(CW\*(C`barlib\*(C'\fR as if they would come
+from another contributor, aka:
+.IP \(bu 4
+go to a local copy of \f(CW\*(C`barlib\*(C'\fR
+.IP \(bu 4
+pull down the changes with a \f(CW\*(C`git pull\*(C'\fR
+.IP \(bu 4
+you notice the changes include some work on your subrepo, time to upstream them: \f(CW\*(C`git subrepo push bazlib\*(C'\fR
+.PP
+And you're done! One final step you'll likely want to do is to go back to \f(CW\*(C`app\-foo\*(C'\fR and run \f(CW\*(C`git subrepo pull barlib\*(C'\fR, because the push you just did added a
+new commit.
 .SH Authors
 .IX Header "Authors"
 .IP \(bu 4