1STDIN(1) Git Submodule Alternative STDIN(1)
2
6 git-subrepo - Git Submodule Alternative
7
9 git subrepo -h # Help Overview
10 git subrepo clone <remote-url> [<subdir>]
12 git subrepo init <subdir>
13 git subrepo pull <subdir>
14 git subrepo push <subdir>
15 git subrepo fetch <subdir>
17 git subrepo branch <subdir>
18 git subrepo commit <subdir>
19 git subrepo config <subdir>
20 git subrepo status [<subdir>]
22 git subrepo clean <subdir>
23 git subrepo help [<command> | --all]
25 git subrepo version
26 git subrepo upgrade
27
29 This git command "clones" an external git repo into a subdirectory of
30 your repo. Later on, upstream changes can be pulled in, and local
31 changes can be pushed back. Simple.
32
34 This command is an improvement from "git-submodule" and "git-subtree";
35 two other git commands with similar goals, but various problems.
36 It assumes there are 3 main roles of people interacting with a repo,
38 and attempts to serve them all well:
39 • owner - The person who authors/owns/maintains a repo.
41 • users - People who are just using/installing the repo.
43 • collaborators - People who commit code to the repo and subrepos.
45 The "git-subrepo" command benefits these roles in the following ways:
47 • Simple and intuitive commandline usage (with tab completion).
49 • Users get your repo and all your subrepos just by cloning your
51 repo.
52 • Users do not need to install "git-subrepo", ever.
54 • Collaborators do not need to install unless they want to push/pull.
56 • Collaborators know when a subdir is a subrepo (it has a ".gitrepo"
58 file).
59 • The ".gitrepo" file never gets pushed back to the subrepo upstream.
61 • Well named branches and remotes are generated for manual
63 operations.
64 • Owners do not deal with the complications of keeping submodules in
66 sync.
67 • Subrepo repositories can contain subrepos themselves.
69 • Branching with subrepos JustWorks™.
71 • Different branches can have different subrepos in different states,
73 etc.
74 • Moving/renaming/deleting a subrepo subdir JustWorks™.
76 • You can "init" an existing subdirectory into a subrepo.
78 • Your git history is kept squeaky clean.
80 • Upstream history (clone/pull) is condensed into a single commit.
82 • Pulls can use a "merge", "rebase" or "force" strategies.
84 • You can see the subrepo history with "git log
86 subrepo/<subdir>/fetch".
87 • Commits pushed back upstream are not condensed (by default).
89 • Trivial to try any subrepo operations and then reset back.
91 • No configuration required.
93 • Does not introduce history that messes up other git commands.
95 • Fixes known rebase failures with "git-subtree".
97
99 The best short answer is:
100 git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
102 echo 'source /path/to/git-subrepo/.rc' >> ~/.bashrc
103 The complete "Installation Instructions" can be found below.
105 Note: git-subrepo needs a git version (> 2.7) that supports worktree:s.
107
109 All the subrepo commands use names of actual Git commands and try to do
110 operations that are similar to their Git counterparts. They also
111 attempt to give similar output in an attempt to make the subrepo usage
112 intuitive to experienced Git users.
113 Please note that the commands are not exact equivalents, and do not
115 take all the same arguments. Keep reading…
116 "git subrepo clone <repository> [<subdir>] [-b <branch>] [-f] [-m
118 <msg>] [--file=<msg file>] [-e] [--method <merge|rebase>]"
119 Add a repository as a subrepo in a subdir of your repository.
120 This is similar in feel to "git clone". You just specify the remote
122 repo url, and optionally a sub-directory and/or branch name. The
123 repo will be fetched and merged into the subdir.
124 The subrepo history is squashed into a single commit that contains
126 the reference information. This information is also stored in a
127 special file called "<subdir>/.gitrepo". The presence of this file
128 indicates that the directory is a subrepo.
129 All subsequent commands refer to the subrepo by the name of the
131 subdir. From the subdir, all the current information about the
132 subrepo can be obtained.
133 The "--force" option will "reclone" (completely replace) an
135 existing subdir.
136 The "--method" option will decide how the join process between
138 branches are performed. The default option is merge.
139 The "clone" command accepts the "--branch=" "--edit", "--file",
141 "--force" and "--message=" options.
142 "git subrepo init <subdir> [-r <remote>] [-b <branch>] [--method
144 <merge|rebase>]"
145 Turn an existing subdirectory into a subrepo.
146 If you want to expose a subdirectory of your project as a published
148 subrepo, this command will do that. It will split out the content
149 of a normal subdirectory into a branch and start tracking it as a
150 subrepo. Afterwards your original repo will look exactly the same
151 except that there will be a "<<subdir"/.gitrepo >> file.
152 If you specify the "--remote" (and optionally the "--branch")
154 option, the values will be added to the "<subdir>/.gitrepo" file.
155 The "--remote" option is the upstream URL, and the "--branch"
156 option is the upstream branch to push to. These values will be
157 needed to do a "git subrepo push" command, but they can be provided
158 later on the "push" command (and saved to "<<subdir"/.gitrepo >> if
159 you also specify the "--update" option).
160 Note: You will need to create the empty upstream repo and push to
162 it on your
163 own, using "git subrepo push <subdir>".
164 The "--method" option will decide how the join process between
166 branches are performed. The default option is merge.
167 The "init" command accepts the "--branch=" and "--remote=" options.
169 "git subrepo pull <subdir>|--all [-M|-R|-f] [-m <msg>] [--file=<msg
171 file>] [-e] [-b <branch>] [-r <remote>] [-u]"
172 Update the subrepo subdir with the latest upstream changes.
173 The "pull" command fetches the latest content from the remote
175 branch pointed to by the subrepo's ".gitrepo" file, and then tries
176 to merge the changes into the corresponding subdir. It does this by
177 making a branch of the local commits to the subdir and then merging
178 or rebasing (see below) it with the fetched upstream content. After
179 the merge, the content of the new branch replaces your subdir, the
180 ".gitrepo" file is updated and a single 'pull' commit is added to
181 your mainline history.
182 The "pull" command will attempt to do the following commands in one
184 go:
185 git subrepo fetch <subdir>
187 git subrepo branch <subdir>
188 git merge/rebase subrepo/<subdir>/fetch subrepo/<subdir>
189 git subrepo commit <subdir>
190 # Only needed for a consequential push:
191 git update-ref refs/subrepo/<subdir>/pull subrepo/<subdir>
192 In other words, you could do all the above commands yourself, for
194 the same effect. If any of the commands fail, subrepo will stop and
195 tell you to finish this by hand. Generally a failure would be in
196 the merge or rebase part, where conflicts can happen. Since Git has
197 lots of ways to resolve conflicts to your personal tastes, the
198 subrepo command defers to letting you do this by hand.
199 When pulling new data, the method selected in clone/init is used.
201 This has no effect on the final result of the pull, since it
202 becomes a single commit. But it does affect the resulting
203 "subrepo/<subdir>" branch, which is often used for a subrepo "push"
204 command. See 'push' below for more information. If you want to
205 change the method you can use the "config" command for this.
206 When you pull you can assume a fast-forward strategy (default) or
208 you can specify a "--rebase", "--merge" or "--force" strategy. The
209 latter is the same as a "clone --force" operation, using the
210 current remote and branch.
211 Like the "clone" command, "pull" will squash all the changes (since
213 the last pull or clone) into one commit. This keeps your mainline
214 history nice and clean. You can easily see the subrepo's history
215 with the "git log" command:
216 git log refs/subrepo/<subdir>/fetch
218 The set of commands used above are described in detail below.
220 The "pull" command accepts the "--all", "--branch=", "--edit",
222 "--file", "--force", "--message=", "--remote=" and "--update"
223 options.
224 "git subrepo push <subdir>|--all [<branch>] [-m msg] [--file=<msg
226 file>] [-r <remote>] [-b <branch>] [-M|-R] [-u] [-f] [-s] [-N]"
227 Push a properly merged subrepo branch back upstream.
228 This command takes the subrepo branch from a successful pull
230 command and pushes the history back to its designated remote and
231 branch. You can also use the "branch" command and merge things
232 yourself before pushing if you want to (although that is probably a
233 rare use case).
234 The "push" command requires a branch that has been properly
236 merged/rebased with the upstream HEAD (unless the upstream HEAD is
237 empty, which is common when doing a first "push" after an "init").
238 That means the upstream HEAD is one of the commits in the branch.
239 By default the branch ref "refs/subrepo/<subdir>/pull" will be
241 pushed, but you can specify a (properly merged) branch to push.
242 After that, the "push" command just checks that the branch contains
244 the upstream HEAD and then pushes it upstream.
245 The "--force" option will do a force push. Force pushes are
247 typically discouraged. Only use this option if you fully understand
248 it. (The "--force" option will NOT check for a proper merge. ANY
249 branch will be force pushed!)
250 The "push" command accepts the "--all", "--branch=", "--dry-run",
252 "--file", "--force", "--merge", "--message", "--rebase",
253 "--remote=", "--squash" and "--update" options.
254 "git subrepo fetch <subdir>|--all [-r <remote>] [-b <branch>]"
256 Fetch the remote/upstream content for a subrepo.
257 It will create a Git reference called "subrepo/<subdir>/fetch" that
259 points at the same commit as "FETCH_HEAD". It will also create a
260 remote called "subrepo/<subdir>". These are temporary and you can
261 easily remove them with the subrepo "clean" command.
262 The "fetch" command accepts the "--all", "--branch=" and
264 "--remote=" options.
265 "git subrepo branch <subdir>|--all [-f] [-F]"
267 Create a branch with local subrepo commits.
268 Scan the history of the mainline for all the commits that affect
270 the "subdir" and create a new branch from them called
271 "subrepo/<subdir>".
272 This is useful for doing "pull" and "push" commands by hand.
274 Use the "--force" option to write over an existing
276 "subrepo/<subdir>" branch.
277 The "branch" command accepts the "--all", "--fetch" and "--force"
279 options.
280 "git subrepo commit <subdir> [<subrepo-ref>] [-m <msg>] [--file=<msg
282 file>] [-e] [-f] [-F]"
283 Add subrepo branch to current history as a single commit.
284 This command is generally used after a hand-merge. You have done a
286 "subrepobranch" and merged (rebased) it with the upstream. This
287 command takes the HEAD of that branch, puts its content into the
288 subrepo subdir and adds a new commit for it to the top of your
289 mainline history.
290 This command requires that the upstream HEAD be in the
292 "subrepo/<subdir>" branch history. That way the same branch can
293 push upstream. Use the "--force" option to commit anyway.
294 The "commit" command accepts the "--edit", "--fetch", "--file",
296 "--force" and "--message=" options.
297 "git subrepo status [<subdir>|--all|--ALL] [-F] [-q|-v]"
299 Get the status of a subrepo. Uses the "--all" option by default. If
300 the "--quiet" flag is used, just print the subrepo names, one per
301 line.
302 The "--verbose" option will show all the recent local and upstream
304 commits.
305 Use "--ALL" to show the subrepos of the subrepos (ie the
307 "subsubrepos"), if any.
308 The "status" command accepts the "--all", "--ALL", "--fetch",
310 "--quiet" and "--verbose" options.
311 "git subrepo clean <subdir>|--all|--ALL [-f]"
313 Remove artifacts created by "fetch" and "branch" commands.
314 The "fetch" and "branch" operations (and other commands that call
316 them) create temporary things like refs, branches and remotes. This
317 command removes all those things.
318 Use "--force" to remove refs. Refs are not removed by default
320 because they are sometimes needed between commands.
321 Use "--all" to clean up after all the current subrepos. Sometimes
323 you might change to a branch where a subrepo doesn't exist, and
324 then "--all" won't find it. Use "--ALL" to remove any artifacts
325 that were ever created by subrepo.
326 To remove ALL subrepo artifacts:
328 git subrepo clean --ALL --force
330 The "clean" command accepts the "--all", "--ALL", and "--force"
332 options.
333 "git subrepo config <subdir> <option> [<value>] [-f]"
335 Read or update configuration values in the subdir/.gitrepo file.
336 Because most of the values stored in the .gitrepo file are
338 generated you will need to use "--force" if you want to change
339 anything else then the "method" option.
340 Example to update the "method" option for a subrepo:
342 git subrepo config foo method rebase
344 "git subrepo help [<command>|--all]"
346 Same as "git help subrepo". Will launch the manpage. For the
347 shorter usage, use "git subrepo -h".
348 Use "git subrepo help <command>" to get help for a specific
350 command. Use "--all" to get a summary of all commands.
351 The "help" command accepts the "--all" option.
353 "git subrepo version [-q|-v]"
355 This command will display version information about git-subrepo and
356 its environment. For just the version number, use "git subrepo
357 --version". Use "--verbose" for more version info, and "--quiet"
358 for less.
359 The "version" command accepts the "--quiet" and "--verbose"
361 options.
362 "git subrepo upgrade"
364 Upgrade the "git-subrepo" software itself. This simply does a "git
365 pull" on the git repository that the code is running from. It only
366 works if you are on the "master" branch. It won't work if you
367 installed "git-subrepo" using "make install"; in that case you'll
368 need to "make install" from the latest code.
369
371 "-h"
372 Show a brief view of the commands and options.
373 "--help"
375 Gives an overview of the help options available for the subrepo
376 command.
377 "--version"
379 Print the git-subrepo version. Just the version number. Try the
380 "version" command for more version info.
381 "--all" ("-a")
383 If you have multiple subrepos, issue the command to all of them (if
384 applicable).
385 "--ALL" ("-A")
387 If you have subrepos that also have subrepos themselves, issue the
388 command to ALL of them. Note that the "--ALL" option only works for
389 a subset of the commands that "--all" works for.
390 "--branch=<branch-name>" ("-b <branch-name>")
392 Use a different upstream branch-name than the remote HEAD or the
393 one saved in ".gitrepo" locally.
394 "--dry-run" ("-N")
396 For the push command, do everything up until the push and then
397 print out the actual "git push" command needed to finish the
398 operation.
399 "--edit" ("-e")
401 Edit the commit message before committing.
402 "--fetch" ("-F")
404 Use this option to fetch the upstream commits, before running the
405 command.
406 "--file=<commit msg file>"
408 Supply your own commit message from a file
409 "--force" ("-f")
411 Use this option to force certain commands that fail in the general
412 case.
413 NOTE: The "--force" option means different things for different
415 commands.
416 Read the command specific doc for the exact meaning.
417 "--merge" ("-M")
419 Use a "merge" strategy to include upstream subrepo commits on a
420 pull (or setup for push).
421 "--message=<message>" ("-m <message>")
423 Specify your own commit message on the command line.
424 "--rebase" ("-R")
426 Use a "rebase" strategy to include upstream subrepo commits on a
427 pull (or setup for push).
428 "--remote=<remote-url>" ("-r <remote-url>")
430 Use a different remote-url than the one saved in ".gitrepo"
431 locally.
432 "--squash" ("-s")
434 Squash all commits on a push into one new commit.
435 "--update" ("-u")
437 If "--branch" or "--remote" are used, and the command updates the
438 ".gitrepo" file, include these values to the update.
439
441 "--quiet" ("-q")
442 Print as little info as possible. Applicable to most commands.
443 "--verbose" ("-v")
445 Print more information about the command execution and results.
446 Applicable to most commands.
447 "--debug" ("-d")
449 Show the actual git (and other) commands being executed under the
450 hood. Applicable to most commands.
451 "--DEBUG" ("-x")
453 Use the Bash "set -x" option which prints every command before it
454 is run. VERY noisy, but extremely useful in deep debugging.
455 Applicable to all commands.
456
458 The "git-subrepo" command exports and honors some environment
459 variables:
460 "GIT_SUBREPO_ROOT"
462 This is set by the ".rc" file, if you use that method to install /
463 enable "git-subrepo". It contains the path of the "git-subrepo"
464 repository.
465 "GIT_SUBREPO_RUNNING"
467 This variable is exported when "git-subrepo" is running. It is set
468 to the pid of the "git-subrepo" process that is running. Other
469 processes, like git hooks for instance, can use this information to
470 adjust accordingly.
471 "GIT_SUBREPO_COMMAND"
473 This variable is exported when "git-subrepo" is running. It is set
474 to the name of the "git-subrepo" subcommand that is running.
475 "GIT_SUBREPO_PAGER"
477 Use this to specify the pager to use for long output commands.
478 Defaults to $PAGER or "less".
479 "GIT_SUBREPO_QUIET"
481 Set this for quiet ("-q") output.
482 "GIT_SUBREPO_VERBOSE"
484 Set this for verbose ("-v") output.
485 "GIT_SUBREPO_DEBUG"
487 Set this for debugging ("-d") output.
488
490 There are currently 3 ways to install "git-subrepo". For all of them
491 you need to get the source code from GitHub:
492 git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
494 The first installation method is preferred: "source" the ".rc" file.
496 Just add a line like this one to your shell startup script:
497 source /path/to/git-subrepo/.rc
499 That will modify your "PATH" and "MANPATH", and also enable command
501 completion.
502 The second method is to do these things by hand. This might afford you
504 more control of your shell environment. Simply add the "lib" and "man"
505 directories to your "PATH" and "MANPATH":
506 export GIT_SUBREPO_ROOT="/path/to/git-subrepo"
508 export PATH="/path/to/git-subrepo/lib:$PATH"
509 export MANPATH="/path/to/git-subrepo/man:$MANPATH"
510 See below for info on how to turn on Command Completion.
512 The third method is a standard system install, which puts "git-subrepo"
514 next to your other git commands:
515 make install # Possibly with 'sudo'
517 This method does not account for upgrading and command completion yet.
519 Windows
521 This command is known to work in these Windows environments:
522 • Git for Windows -- <https://git-for-windows.github.io/>
524 • Babun -- <http://babun.github.io/>
526 • Cygwin -- <https://www.cygwin.com/>
528 Let us know if there are others that it works (or doesn't work) in.
530
532 The "git-subrepo" repository comes with a extensive test suite. You can
533 run it with:
534 make test
536 or if you don't have "make" on your system:
538 prove -v test
540
542 If you used the ".rc" or "PATH" method of installation, just run this
543 to upgrade "git-subrepo":
544 git subrepo upgrade
546 Or (same thing):
548 cd /path/to/git-subrepo
550 git pull
551 If you used "make install" method, then run this again (after "git
553 pull"):
554 make install # Possibly with 'sudo'
556
558 The "git subrepo" command supports "<TAB>"-based command completion. If
559 you don't use the ".rc" script (see Installation, above), you'll need
560 to enable this manually to use it.
561 In Bash
563 If your Bash setup does not already provide command completion for Git,
564 you'll need to enable that first:
565 source <Git completion script>
567 On your system, the Git completion script might be found at any of the
569 following locations (or somewhere else that we don't know about):
570 • "/etc/bash_completion.d/git"
572 • "/usr/share/bash-completion/git"
574 • "/usr/share/bash-completion/completions/git"
576 • "/opt/local/share/bash-completion/completions/git"
578 • "/usr/local/etc/bash_completion.d/git"
580 • "~/.homebrew/etc/bash_completion.d/git"
582 In case you can't find any of these, this repository contains a copy of
584 the Git completion script:
585 source /path/to/git-subrepo/share/git-completion.bash
587 Once Git completion is enabled (whether you needed to do that manually
589 or not), you can turn on "git-subrepo" completion with a command like
590 this:
591 source /path/to/git-subrepo/share/completion.bash
593 In zsh
595 In the Z shell (zsh), you can manually enable "git-subrepo" completion
596 by adding the following line to your "~/.zshrc", before the "compinit"
597 function is called:
598 fpath=('/path/to/git-subrepo/share/zsh-completion' $fpath)
600
602 The git-subrepo command has been in use for well over a year and seems
603 to get the job done. Development is still ongoing but mostly just for
604 fixing bugs.
605 Trying subrepo out is simple and painless (this is not "git
607 submodule"). Nothing is permanent (if you do not push to shared
608 remotes). ie You can always play around and reset back to the beginning
609 without pain.
610 This command has a test suite (run "make test"), but surely has many
612 bugs. If you have expertise with Git and subcommands, please review the
613 code, and file issues on anything that seems wrong.
614 If you want to chat about the "git-subrepo" command, join
616 "#gitcommands" on "irc.freenode.net".
617
619 • Works on POSIX systems: Linux, BSD, OSX, etc.
620 • Works on various Windows environments. See "Windows" section above.
622 • The "git-subrepo" repo itself has 2 subrepos under the "ext/"
624 subdirectory.
625 • Written in (very modern) Bash, with full test suite. Take a look.
627 • A ".gitrepo" file never is in the top level dir (next to a ".git/"
629 dir).
630
632 • Ingy döt Net <ingy@ingy.net>
633 • Magnus Carlsson <grimmymail@gmail.com>
635 • Austin Morgan <admorgan@morgancomputers.net>
637
639 The MIT License (MIT)
640 Copyright (c) 2013-2020 Ingy döt Net
642Generated by Swim v0.1.48 August 2022 STDIN(1)