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>] [-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", "--force" and
141 "-- 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>] [-e] [-b
171 <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 "--force", "--message=", "--remote=" and "--update" options.
223 "git subrepo push <subdir>|--all [<branch>] [-r <remote>] [-b <branch>]
225 [-M|-R] [-u] [-f] [-s] [-N]"
226 Push a properly merged subrepo branch back upstream.
227 This command takes the subrepo branch from a successful pull
229 command and pushes the history back to its designated remote and
230 branch. You can also use the "branch" command and merge things
231 yourself before pushing if you want to (although that is probably a
232 rare use case).
233 The "push" command requires a branch that has been properly
235 merged/rebased with the upstream HEAD (unless the upstream HEAD is
236 empty, which is common when doing a first "push" after an "init").
237 That means the upstream HEAD is one of the commits in the branch.
238 By default the branch ref "refs/subrepo/<subdir>/pull" will be
240 pushed, but you can specify a (properly merged) branch to push.
241 After that, the "push" command just checks that the branch contains
243 the upstream HEAD and then pushes it upstream.
244 The "--force" option will do a force push. Force pushes are
246 typically discouraged. Only use this option if you fully understand
247 it. (The "--force" option will NOT check for a proper merge. ANY
248 branch will be force pushed!)
249 The "push" command accepts the "--all", "--branch=", "--dry-run",
251 "-- force", "--merge", "--rebase", "--remote=", "--squash" and "--
252 update" options.
253 "git subrepo fetch <subdir>|--all [-r <remote>] [-b <branch>]"
255 Fetch the remote/upstream content for a subrepo.
256 It will create a Git reference called "subrepo/<subdir>/fetch" that
258 points at the same commit as "FETCH_HEAD". It will also create a
259 remote called "subrepo/<subdir>". These are temporary and you can
260 easily remove them with the subrepo "clean" command.
261 The "fetch" command accepts the "--all", "--branch=" and "--
263 remote=" options.
264 "git subrepo branch <subdir>|--all [-f] [-F]"
266 Create a branch with local subrepo commits.
267 Scan the history of the mainline for all the commits that affect
269 the "subdir" and create a new branch from them called
270 "subrepo/<subdir>".
271 This is useful for doing "pull" and "push" commands by hand.
273 Use the "--force" option to write over an existing
275 "subrepo/<subdir>" branch.
276 The "branch" command accepts the "--all", "--fetch" and "--force"
278 options.
279 "git subrepo commit <subdir> [<subrepo-ref>] [-m <msg>] [-e] [-f] [-F]"
281 Add subrepo branch to current history as a single commit.
282 This command is generally used after a hand-merge. You have done a
284 "subrepo branch" and merged (rebased) it with the upstream. This
285 command takes the HEAD of that branch, puts its content into the
286 subrepo subdir and adds a new commit for it to the top of your
287 mainline history.
288 This command requires that the upstream HEAD be in the
290 "subrepo/<subdir>" branch history. That way the same branch can
291 push upstream. Use the "--force" option to commit anyway.
292 The "commit" command accepts the "--edit", "--fetch", "--force" and
294 "-- message=" options.
295 "git subrepo status [<subdir>|--all|--ALL] [-F] [-q|-v]"
297 Get the status of a subrepo. Uses the "--all" option by default. If
298 the "-- quiet" flag is used, just print the subrepo names, one per
299 line.
300 The "--verbose" option will show all the recent local and upstream
302 commits.
303 Use "--ALL" to show the subrepos of the subrepos (ie the
305 "subsubrepos"), if any.
306 The "status" command accepts the "--all", "--ALL", "--fetch",
308 "--quiet" and "--verbose" options.
309 "git subrepo clean <subdir>|--all|--ALL [-f]"
311 Remove artifacts created by "fetch" and "branch" commands.
312 The "fetch" and "branch" operations (and other commands that call
314 them) create temporary things like refs, branches and remotes. This
315 command removes all those things.
316 Use "--force" to remove refs. Refs are not removed by default
318 because they are sometimes needed between commands.
319 Use "--all" to clean up after all the current subrepos. Sometimes
321 you might change to a branch where a subrepo doesn't exist, and
322 then "--all" won't find it. Use "--ALL" to remove any artifacts
323 that were ever created by subrepo.
324 To remove ALL subrepo artifacts:
326 git subrepo clean --ALL --force
328 The "clean" command accepts the "--all", "--ALL", and "--force"
330 options.
331 "git subrepo config <subdir> <option> [<value>] [-f]"
333 Read or update configuration values in the subdir/.gitrepo file.
334 Because most of the values stored in the .gitrepo file are
336 generated you will need to use "--force" if you want to change
337 anything else then the "method" option.
338 Example to update the "method" option for a subrepo:
340 git subrepo config foo method rebase
342 "git subrepo help [<command>|--all]"
344 Same as "git help subrepo". Will launch the manpage. For the
345 shorter usage, use "git subrepo -h".
346 Use "git subrepo help <command>" to get help for a specific
348 command. Use "--all" to get a summary of all commands.
349 The "help" command accepts the "--all" option.
351 "git subrepo version [-q|-v]"
353 This command will display version information about git-subrepo and
354 its environment. For just the version number, use "git subrepo
355 --version". Use "--verbose" for more version info, and "--quiet"
356 for less.
357 The "version" command accepts the "--quiet" and "--verbose"
359 options.
360 "git subrepo upgrade"
362 Upgrade the "git-subrepo" software itself. This simply does a "git
363 pull" on the git repository that the code is running from. It only
364 works if you are on the "master" branch. It won't work if you
365 installed "git-subrepo" using "make install"; in that case you'll
366 need to "make install" from the latest code.
367
369 "-h"
370 Show a brief view of the commands and options.
371 "--help"
373 Gives an overview of the help options available for the subrepo
374 command.
375 "--version"
377 Print the git-subrepo version. Just the version number. Try the
378 "version" command for more version info.
379 "--all" ("-a")
381 If you have multiple subrepos, issue the command to all of them (if
382 applicable).
383 "--ALL" ("-A")
385 If you have subrepos that also have subrepos themselves, issue the
386 command to ALL of them. Note that the "--ALL" option only works for
387 a subset of the commands that "--all" works for.
388 "--branch=<branch-name>" ("-b <branch-name>")
390 Use a different upstream branch-name than the remote HEAD or the
391 one saved in ".gitrepo" locally.
392 "--dry-run" ("-N")
394 For the push command, do everything up until the push and then
395 print out the actual "git push" command needed to finish the
396 operation.
397 "--edit" ("-e")
399 Edit the commit message before committing.
400 "--fetch" ("-F")
402 Use this option to fetch the upstream commits, before running the
403 command.
404 "--force" ("-f")
406 Use this option to force certain commands that fail in the general
407 case.
408 NOTE: The "--force" option means different things for different
410 commands.
411 Read the command specific doc for the exact meaning.
412 "--merge" ("-M")
414 Use a "merge" strategy to include upstream subrepo commits on a
415 pull (or setup for push).
416 "--message=<message>" ("-m <message>")
418 Specify your own commit message on the command line.
419 "--rebase" ("-R")
421 Use a "rebase" strategy to include upstream subrepo commits on a
422 pull (or setup for push).
423 "--remote=<remote-url>" ("-r <remote-url>")
425 Use a different remote-url than the one saved in ".gitrepo"
426 locally.
427 "--squash" ("-s")
429 Squash all commits on a push into one new commit.
430 "--update" ("-u")
432 If "--branch" or "--remote" are used, and the command updates the
433 ".gitrepo" file, include these values to the update.
434
436 "--quiet" ("-q")
437 Print as little info as possible. Applicable to most commands.
438 "--verbose" ("-v")
440 Print more information about the command execution and results.
441 Applicable to most commands.
442 "--debug" ("-d")
444 Show the actual git (and other) commands being executed under the
445 hood. Applicable to most commands.
446 "--DEBUG" ("-x")
448 Use the Bash "set -x" option which prints every command before it
449 is run. VERY noisy, but extremely useful in deep debugging.
450 Applicable to all commands.
451
453 The "git-subrepo" command exports and honors some environment
454 variables:
455 "GIT_SUBREPO_ROOT"
457 This is set by the ".rc" file, if you use that method to install /
458 enable "git- subrepo". It contains the path of the "git-subrepo"
459 repository.
460 "GIT_SUBREPO_RUNNING"
462 This variable is exported when "git-subrepo" is running. It is set
463 to the pid of the "git-subrepo" process that is running. Other
464 processes, like git hooks for instance, can use this information to
465 adjust accordingly.
466 "GIT_SUBREPO_COMMAND"
468 This variable is exported when "git-subrepo" is running. It is set
469 to the name of the "git-subrepo" subcommand that is running.
470 "GIT_SUBREPO_PAGER"
472 Use this to specify the pager to use for long output commands.
473 Defaults to $PAGER or "less".
474 "GIT_SUBREPO_QUIET"
476 Set this for quiet ("-q") output.
477 "GIT_SUBREPO_VERBOSE"
479 Set this for verbose ("-v") output.
480 "GIT_SUBREPO_DEBUG"
482 Set this for debugging ("-d") output.
483
485 There are currently 3 ways to install "git-subrepo". For all of them
486 you need to get the source code from GitHub:
487 git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
489 The first installation method is preferred: "source" the ".rc" file.
491 Just add a line like this one to your shell startup script:
492 source /path/to/git-subrepo/.rc
494 That will modify your "PATH" and "MANPATH", and also enable command
496 completion.
497 The second method is to do these things by hand. This might afford you
499 more control of your shell environment. Simply add the "lib" and "man"
500 directories to your "PATH" and "MANPATH":
501 export GIT_SUBREPO_ROOT="/path/to/git-subrepo"
503 export PATH="/path/to/git-subrepo/lib:$PATH"
504 export MANPATH="/path/to/git-subrepo/man:$MANPATH"
505 See below for info on how to turn on Command Completion.
507 The third method is a standard system install, which puts "git-subrepo"
509 next to your other git commands:
510 make install # Possibly with 'sudo'
512 This method does not account for upgrading and command completion yet.
514 Windows
516 This command is known to work in these Windows environments:
517 · Git for Windows -- <https://git-for-windows.github.io/>
519 · Babun -- <http://babun.github.io/>
521 · Cygwin -- <https://www.cygwin.com/>
523 Let us know if there are others that it works (or doesn't work) in.
525
527 The "git-subrepo" repository comes with a extensive test suite. You can
528 run it with:
529 make test
531 or if you don't have "make" on your system:
533 prove -v test
535
537 If you used the ".rc" or "PATH" method of installation, just run this
538 to upgrade "git-subrepo":
539 git subrepo upgrade
541 Or (same thing):
543 cd /path/to/git-subrepo
545 git pull
546 If you used "make install" method, then run this again (after "git
548 pull"):
549 make install # Possibly with 'sudo'
551
553 The "git subrepo" command supports "<TAB>"-based command completion. If
554 you don't use the ".rc" script (see Installation, above), you'll need
555 to enable this manually to use it.
556 In Bash
558 If your Bash setup does not already provide command completion for Git,
559 you'll need to enable that first:
560 source <Git completion script>
562 On your system, the Git completion script might be found at any of the
564 following locations (or somewhere else that we don't know about):
565 · "/etc/bash_completion.d/git"
567 · "/usr/share/bash-completion/git"
569 · "/usr/share/bash-completion/completions/git"
571 · "/opt/local/share/bash-completion/completions/git"
573 · "/usr/local/etc/bash_completion.d/git"
575 · "~/.homebrew/etc/bash_completion.d/git"
577 In case you can't find any of these, this repository contains a copy of
579 the Git completion script:
580 source /path/to/git-subrepo/share/git-completion.bash
582 Once Git completion is enabled (whether you needed to do that manually
584 or not), you can turn on "git-subrepo" completion with a command like
585 this:
586 source /path/to/git-subrepo/share/completion.bash
588 In zsh
590 In the Z shell (zsh), you can manually enable "git-subrepo" completion
591 by adding the following line to your "~/.zshrc", before the "compinit"
592 function is called:
593 fpath=('/path/to/git-subrepo/share/zsh-completion' $fpath)
595
597 The git-subrepo command has been in use for well over a year and seems
598 to get the job done. Development is still ongoing but mostly just for
599 fixing bugs.
600 Trying subrepo out is simple and painless (this is not "git
602 submodule"). Nothing is permanent (if you do not push to shared
603 remotes). ie You can always play around and reset back to the beginning
604 without pain.
605 This command has a test suite (run "make test"), but surely has many
607 bugs. If you have expertise with Git and subcommands, please review the
608 code, and file issues on anything that seems wrong.
609 If you want to chat about the "git-subrepo" command, join
611 "#gitcommands" on "irc.freenode.net".
612
614 · Works on POSIX systems: Linux, BSD, OSX, etc.
615 · Works on various Windows environments. See "Windows" section above.
617 · The "git-subrepo" repo itself has 2 subrepos under the "ext/"
619 subdirectory.
620 · Written in (very modern) Bash, with full test suite. Take a look.
622 · A ".gitrepo" file never is in the top level dir (next to a ".git/"
624 dir).
625
627 · Ingy döt Net <ingy@ingy.net>
628 · Magnus Carlsson <grimmymail@gmail.com>
630 · Austin Morgan <admorgan@morgancomputers.net>
632
634 The MIT License (MIT)
635 Copyright (c) 2013-2020 Ingy döt Net
637Generated by Swim v0.1.48 November 2020 STDIN(1)