From 127e1334e4b61ec6a551d526ba78909cbb0b9db4 Mon Sep 17 00:00:00 2001 From: abeforgit Date: Sun, 18 Aug 2024 18:09:04 +0200 Subject: [PATCH 1/6] Add information about usage with nested subrepos --- ReadMe.pod | 71 ++++++++++++++++++++++++++++++++++++++++ doc/git-subrepo.swim | 68 +++++++++++++++++++++++++++++++++++++++ man/man1/git-subrepo.1 | 73 ++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 210 insertions(+), 2 deletions(-) diff --git a/ReadMe.pod b/ReadMe.pod index a3e6daba..34d8d786 100644 --- a/ReadMe.pod +++ b/ReadMe.pod @@ -672,6 +672,77 @@ C. =back +=head1 Working with nested subrepos + +C supports adding subrepos which themselves make use of subrepos. +In fact, subrepo itself is built this way. Take a look in the C folder, +it houses 2 dependencies as subrepos, C and C. + +C itself depends on 2 more subrepos: C again, and +C. + +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: B<< +C is 100% agnostic about your dependencies! >> + +There is B special handling for nested subrepos. When you clone a subrepo, +B C does is download the code and set up the subrepo file. +It couldn't care less about the actual contents of your code. This means that +all the subrepo commands simply act on the subrepo as a whole, treating nested +subrepos like it treats 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 + +Now, if C is a library you don't maintain, your responsibility would +end here. C's maintainer would see your changes and decide what to do +with them. + +If you do maintain C, you might now want to upstream the changes all +the way into C. You could be tempted to try running something like: + +C + +but you'll soon find out that doesn't work. Why not? Simple: C +doesn't know anything about the link between C and C. + +What you should do is treat the changes to C as if they would come +from another contributor, aka: + +=over + +=item * go to your local copy of C + +=item * pull down the changes with a simple C + +=item * you notice the changes include some work on your subrepo, time to upstream them: C + +=back + +And you're done! One final step you'll likely want to do is to go back to C and run C, because the push you just did added a +new commit. + =head1 Authors =over diff --git a/doc/git-subrepo.swim b/doc/git-subrepo.swim index a2f50764..58768e2c 100644 --- a/doc/git-subrepo.swim +++ b/doc/git-subrepo.swim @@ -599,6 +599,74 @@ 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: +*`git-subrepo` is 100% agnostic about your dependencies!* + +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. It couldn't care less about the actual contents of your code. +This means that all the subrepo commands simply act on the subrepo as a whole, +treating nested subrepos like it treats 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. Why not? Simple: `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 your local copy of `barlib` +* pull down the changes with a simple `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 diff --git a/man/man1/git-subrepo.1 b/man/man1/git-subrepo.1 index 434fde98..d2fd2c2e 100644 --- a/man/man1/git-subrepo.1 +++ b/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-18 "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: \fR\f(CB\*(C`git\-subrepo\*(C'\fR\fB is 100% agnostic about your dependencies!\fR +.PP +There is \fBno\fR special handling for nested subrepos. 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. +It couldn't care less about the actual contents of your code. This means that +all the subrepo commands simply act on the subrepo as a whole, treating nested +subrepos like it treats 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. Why not? Simple: \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 your local copy of \f(CW\*(C`barlib\*(C'\fR +.IP \(bu 4 +pull down the changes with a simple \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 From 4258e36a7082d34e79915966cbbff4cadbfea311 Mon Sep 17 00:00:00 2001 From: abeforgit Date: Sat, 31 Aug 2024 18:46:56 +0200 Subject: [PATCH 2/6] Remove overly aggressive note --- ReadMe.pod | 5 ++--- doc/git-subrepo.swim | 5 ++--- man/man1/git-subrepo.1 | 7 +++---- 3 files changed, 7 insertions(+), 10 deletions(-) diff --git a/ReadMe.pod b/ReadMe.pod index 34d8d786..568b0b66 100644 --- a/ReadMe.pod +++ b/ReadMe.pod @@ -694,9 +694,8 @@ C is 100% agnostic about your dependencies! >> There is B special handling for nested subrepos. When you clone a subrepo, B C does is download the code and set up the subrepo file. -It couldn't care less about the actual contents of your code. This means that -all the subrepo commands simply act on the subrepo as a whole, treating nested -subrepos like it treats any other part of the source code. +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: diff --git a/doc/git-subrepo.swim b/doc/git-subrepo.swim index 58768e2c..d0a31558 100644 --- a/doc/git-subrepo.swim +++ b/doc/git-subrepo.swim @@ -622,9 +622,8 @@ 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. It couldn't care less about the actual contents of your code. -This means that all the subrepo commands simply act on the subrepo as a whole, -treating nested subrepos like it treats any other part of the source code. +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: diff --git a/man/man1/git-subrepo.1 b/man/man1/git-subrepo.1 index d2fd2c2e..ada18044 100644 --- a/man/man1/git-subrepo.1 +++ b/man/man1/git-subrepo.1 @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "STDIN 1" -.TH STDIN 1 2024-08-18 "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 @@ -735,9 +735,8 @@ However, it's important to understand how this works. Here's the key idea: \fR\f .PP There is \fBno\fR special handling for nested subrepos. 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. -It couldn't care less about the actual contents of your code. This means that -all the subrepo commands simply act on the subrepo as a whole, treating nested -subrepos like it treats any other part of the source code. +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: From dbd8e4589db2db8063ef3f638c075353951e2eec Mon Sep 17 00:00:00 2001 From: abeforgit Date: Sat, 31 Aug 2024 18:49:31 +0200 Subject: [PATCH 3/6] Remove redundant remark about agnosticism --- ReadMe.pod | 12 ++++++------ doc/git-subrepo.swim | 8 ++++---- man/man1/git-subrepo.1 | 11 ++++++----- 3 files changed, 16 insertions(+), 15 deletions(-) diff --git a/ReadMe.pod b/ReadMe.pod index 568b0b66..f1ddf4fd 100644 --- a/ReadMe.pod +++ b/ReadMe.pod @@ -689,13 +689,13 @@ The structure is therefore as follows: |- bashplus |- test-tap-bash -However, it's important to understand how this works. Here's the key idea: B<< -C is 100% agnostic about your dependencies! >> +However, it's important to understand how this works. Here's the key idea: +there is B special handling for nested subrepos. -There is B special handling for nested subrepos. When you clone a subrepo, -B C 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. +When you clone a subrepo, B C 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: diff --git a/doc/git-subrepo.swim b/doc/git-subrepo.swim index d0a31558..df15111b 100644 --- a/doc/git-subrepo.swim +++ b/doc/git-subrepo.swim @@ -618,11 +618,11 @@ The structure is therefore as follows: |- test-tap-bash However, it's important to understand how this works. Here's the key idea: -*`git-subrepo` is 100% agnostic about your dependencies!* +there is *no* special handling for nested subrepos. -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, +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: diff --git a/man/man1/git-subrepo.1 b/man/man1/git-subrepo.1 index ada18044..0cc428a0 100644 --- a/man/man1/git-subrepo.1 +++ b/man/man1/git-subrepo.1 @@ -731,12 +731,13 @@ The structure is therefore as follows: \& |\- test\-tap\-bash .Ve .PP -However, it's important to understand how this works. Here's the key idea: \fR\f(CB\*(C`git\-subrepo\*(C'\fR\fB is 100% agnostic about your dependencies!\fR +However, it's important to understand how this works. Here's the key idea: +there is \fBno\fR special handling for nested subrepos. .PP -There is \fBno\fR special handling for nested subrepos. 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. +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: From 2e4a608bb7025fc7e0c98c267528ae591e7c6c20 Mon Sep 17 00:00:00 2001 From: abeforgit Date: Sat, 31 Aug 2024 18:51:28 +0200 Subject: [PATCH 4/6] Remove unnecessary "simple" --- ReadMe.pod | 4 ++-- doc/git-subrepo.swim | 4 ++-- man/man1/git-subrepo.1 | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/ReadMe.pod b/ReadMe.pod index f1ddf4fd..8e938fc0 100644 --- a/ReadMe.pod +++ b/ReadMe.pod @@ -723,8 +723,8 @@ the way into C. You could be tempted to try running something like: C -but you'll soon find out that doesn't work. Why not? Simple: C -doesn't know anything about the link between C and C. +but you'll soon find out that doesn't work. C doesn't know anything +about the link between C and C. What you should do is treat the changes to C as if they would come from another contributor, aka: diff --git a/doc/git-subrepo.swim b/doc/git-subrepo.swim index df15111b..3a2dbfc7 100644 --- a/doc/git-subrepo.swim +++ b/doc/git-subrepo.swim @@ -649,8 +649,8 @@ 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. Why not? Simple: `app-foo` doesn't -know anything about the link between `barlib` and `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: diff --git a/man/man1/git-subrepo.1 b/man/man1/git-subrepo.1 index 0cc428a0..a1567a5d 100644 --- a/man/man1/git-subrepo.1 +++ b/man/man1/git-subrepo.1 @@ -767,8 +767,8 @@ the way into \f(CW\*(C`bazlib\*(C'\fR. You could be tempted to try running somet .PP \&\f(CW\*(C`git subrepo push barlib/bazlib\*(C'\fR .PP -but you'll soon find out that doesn't work. Why not? Simple: \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. +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: From 89bb7ea23fe58b824a6165d63f33f25fb486f9ef Mon Sep 17 00:00:00 2001 From: abeforgit Date: Sat, 31 Aug 2024 18:52:31 +0200 Subject: [PATCH 5/6] Remove another "simple" --- ReadMe.pod | 2 +- doc/git-subrepo.swim | 2 +- man/man1/git-subrepo.1 | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ReadMe.pod b/ReadMe.pod index 8e938fc0..463b69b6 100644 --- a/ReadMe.pod +++ b/ReadMe.pod @@ -733,7 +733,7 @@ from another contributor, aka: =item * go to your local copy of C -=item * pull down the changes with a simple C +=item * pull down the changes with a C =item * you notice the changes include some work on your subrepo, time to upstream them: C diff --git a/doc/git-subrepo.swim b/doc/git-subrepo.swim index 3a2dbfc7..164a8b26 100644 --- a/doc/git-subrepo.swim +++ b/doc/git-subrepo.swim @@ -656,7 +656,7 @@ What you should do is treat the changes to `barlib` as if they would come from another contributor, aka: * go to your local copy of `barlib` -* pull down the changes with a simple `git pull` +* 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` diff --git a/man/man1/git-subrepo.1 b/man/man1/git-subrepo.1 index a1567a5d..d71b26a4 100644 --- a/man/man1/git-subrepo.1 +++ b/man/man1/git-subrepo.1 @@ -775,7 +775,7 @@ from another contributor, aka: .IP \(bu 4 go to your local copy of \f(CW\*(C`barlib\*(C'\fR .IP \(bu 4 -pull down the changes with a simple \f(CW\*(C`git pull\*(C'\fR +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 From 46dc4324fc8e5f5d9adfade632b2268a676a96d2 Mon Sep 17 00:00:00 2001 From: abeforgit Date: Sat, 31 Aug 2024 18:53:03 +0200 Subject: [PATCH 6/6] Change "your" to "a" --- ReadMe.pod | 2 +- doc/git-subrepo.swim | 2 +- man/man1/git-subrepo.1 | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ReadMe.pod b/ReadMe.pod index 463b69b6..769be605 100644 --- a/ReadMe.pod +++ b/ReadMe.pod @@ -731,7 +731,7 @@ from another contributor, aka: =over -=item * go to your local copy of C +=item * go to a local copy of C =item * pull down the changes with a C diff --git a/doc/git-subrepo.swim b/doc/git-subrepo.swim index 164a8b26..2adb085c 100644 --- a/doc/git-subrepo.swim +++ b/doc/git-subrepo.swim @@ -655,7 +655,7 @@ but you'll soon find out that doesn't work. What you should do is treat the changes to `barlib` as if they would come from another contributor, aka: -* go to your local copy of `barlib` +* 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: diff --git a/man/man1/git-subrepo.1 b/man/man1/git-subrepo.1 index d71b26a4..46e489a5 100644 --- a/man/man1/git-subrepo.1 +++ b/man/man1/git-subrepo.1 @@ -773,7 +773,7 @@ about the link between \f(CW\*(C`barlib\*(C'\fR and \f(CW\*(C`bazlib\*(C'\fR. 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 your local copy of \f(CW\*(C`barlib\*(C'\fR +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