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.5) 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 When you pull you can assume a fast-forward strategy (default) or
213 you can specify a "--rebase", "--merge" or "--force" strategy. The
214 latter is the same as a "clone --force" operation, using the
215 current remote and branch.
216 Like the "clone" command, "pull" will squash all the changes (since
218 the last pull or clone) into one commit. This keeps your mainline
219 history nice and clean. You can easily see the subrepo's history
220 with the "git log" command:
221 git log refs/subrepo/<subdir>/fetch
223 The set of commands used above are described in detail below.
225 The "pull" command accepts the "--all", "--branch=", "--edit",
227 "--force", "--message=", "--remote=" and "--update" options.
228 "git subrepo push <subdir>|--all [<branch>] [-r <remote>] [-b <branch>]
230 [-M|-R] [-u] [-f] [-s] [-N]"
231 Push a properly merged subrepo branch back upstream.
232 This command takes the subrepo branch from a successful pull
234 command and pushes the history back to its designated remote and
235 branch. You can also use the "branch" command and merge things
236 yourself before pushing if you want to (although that is probably a
237 rare use case).
238 The "push" command requires a branch that has been properly
240 merged/rebased with the upstream HEAD (unless the upstream HEAD is
241 empty, which is common when doing a first "push" after an "init").
242 That means the upstream HEAD is one of the commits in the branch.
243 By default the branch ref "refs/subrepo/<subdir>/pull" will be
245 pushed, but you can specify a (properly merged) branch to push.
246 After that, the "push" command just checks that the branch contains
248 the upstream HEAD and then pushes it upstream.
249 The "--force" option will do a force push. Force pushes are
251 typically discouraged. Only use this option if you fully understand
252 it. (The "--force" option will NOT check for a proper merge. ANY
253 branch will be force pushed!)
254 The "push" command accepts the "--all", "--branch=", "--dry-run",
256 "-- force", "--merge", "--rebase", "--remote=", "--squash" and "--
257 update" options.
258 "git subrepo fetch <subdir>|--all [-r <remote>] [-b <branch>]"
260 Fetch the remote/upstream content for a subrepo.
261 It will create a Git reference called "subrepo/<subdir>/fetch" that
263 points at the same commit as "FETCH_HEAD". It will also create a
264 remote called "subrepo/<subdir>". These are temporary and you can
265 easily remove them with the subrepo "clean" command.
266 The "fetch" command accepts the "--all", "--branch=" and "--
268 remote=" options.
269 "git subrepo branch <subdir>|--all [-f] [-F]"
271 Create a branch with local subrepo commits.
272 Scan the history of the mainline for all the commits that affect
274 the "subdir" and create a new branch from them called
275 "subrepo/<subdir>".
276 This is useful for doing "pull" and "push" commands by hand.
278 Use the "--force" option to write over an existing
280 "subrepo/<subdir>" branch.
281 The "branch" command accepts the "--all", "--fetch" and "--force"
283 options.
284 "git subrepo commit <subdir> [<subrepo-ref>] [-m <msg>] [-e] [-f] [-F]"
286 Add subrepo branch to current history as a single commit.
287 This command is generally used after a hand-merge. You have done a
289 "subrepo branch" and merged (rebased) it with the upstream. This
290 command takes the HEAD of that branch, puts its content into the
291 subrepo subdir and adds a new commit for it to the top of your
292 mainline history.
293 This command requires that the upstream HEAD be in the
295 "subrepo/<subdir>" branch history. That way the same branch can
296 push upstream. Use the "--force" option to commit anyway.
297 The "commit" command accepts the "--edit", "--fetch", "--force" and
299 "-- message=" options.
300 "git subrepo status [<subdir>|--all|--ALL] [-F] [-q|-v]"
302 Get the status of a subrepo. Uses the "--all" option by default. If
303 the "-- quiet" flag is used, just print the subrepo names, one per
304 line.
305 The "--verbose" option will show all the recent local and upstream
307 commits.
308 Use "--ALL" to show the subrepos of the subrepos (ie the
310 "subsubrepos"), if any.
311 The "status" command accepts the "--all", "--ALL", "--fetch",
313 "--quiet" and "--verbose" options.
314 "git subrepo clean <subdir>|--all|--ALL [-f]"
316 Remove artifacts created by "fetch" and "branch" commands.
317 The "fetch" and "branch" operations (and other commands that call
319 them) create temporary things like refs, branches and remotes. This
320 command removes all those things.
321 Use "--force" to remove refs. Refs are not removed by default
323 because they are sometimes needed between commands.
324 Use "--all" to clean up after all the current subrepos. Sometimes
326 you might change to a branch where a subrepo doesn't exist, and
327 then "--all" won't find it. Use "--ALL" to remove any artifacts
328 that were ever created by subrepo.
329 To remove ALL subrepo artifacts:
331 git subrepo clean --ALL --force
333 The "clean" command accepts the "--all", "--ALL", and "--force"
335 options.
336 "git subrepo config <subdir> <option> [<value>] [-f]"
338 Read or update configuration values in the subdir/.gitrepo file.
339 Because most of the values stored in the .gitrepo file are
341 generated you will need to use "--force" if you want to change
342 anything else then the "method" option.
343 Example to update the "method" option for a subrepo:
345 git subrepo config foo method rebase
347 "git subrepo help [<command>|--all]"
349 Same as "git help subrepo". Will launch the manpage. For the
350 shorter usage, use "git subrepo -h".
351 Use "git subrepo help <command> to get help for a specific command.
353 Use"-- all` to get a summary of all commands.
354 The "help" command accepts the "--all" option.
356 "git subrepo version [-q|-v]"
358 This command will display version information about git-subrepo and
359 its environment. For just the version number, use "git subrepo
360 --version". Use "--verbose" for more version info, and "--quiet"
361 for less.
362 The "version" command accepts the "--quiet" and "--verbose"
364 options.
365 "git subrepo upgrade"
367 Upgrade the "git-subrepo" software itself. This simply does a "git
368 pull" on the git repository that the code is running from. It only
369 works if you are on the "master" branch. It won't work if you
370 installed "git-subrepo" using "make install"; in that case you'll
371 need to "make install" from the latest code.
372
374 "-h"
375 Show a brief view of the commands and options.
376 "--help"
378 Gives an overview of the help options available for the subrepo
379 command.
380 "--version"
382 Print the git-subrepo version. Just the version number. Try the
383 "version" command for more version info.
384 "--all" ("-a")
386 If you have multiple subrepos, issue the command to all of them (if
387 applicable).
388 "--ALL" ("-A")
390 If you have subrepos that also have subrepos themselves, issue the
391 command to ALL of them. Note that the "--ALL" option only works for
392 a subset of the commands that "--all" works for.
393 "--branch=<branch-name>" ("-b <branch-name>")
395 Use a different upstream branch-name than the remote HEAD or the
396 one saved in ".gitrepo" locally.
397 "--dry-run" ("-N")
399 For the push command, do everything up until the push and then
400 print out the actual "git push" command needed to finish the
401 operation.
402 "--edit" ("-e")
404 Edit the commit message before committing.
405 "--fetch" ("-F")
407 Use this option to fetch the upstream commits, before running the
408 command.
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
637 The MIT License (MIT)
638 Copyright (c) 2013-2018 Ingy döt Net
640Generated by Swim v0.1.46 November 2018 STDIN(1)