1STDIN(1)                   Git Submodule Alternative                  STDIN(1)
2
3
4

Name

6       git-subrepo - Git Submodule Alternative
7

Synopsis

9           git subrepo -h    # Help Overview
10
11           git subrepo clone <remote-url> [<subdir>]
12           git subrepo init <subdir>
13           git subrepo pull <subdir>
14           git subrepo push <subdir>
15
16           git subrepo fetch <subdir>
17           git subrepo branch <subdir>
18           git subrepo commit <subdir>
19           git subrepo config <subdir>
20
21           git subrepo status [<subdir>]
22           git subrepo clean <subdir>
23
24           git subrepo help [<command> | --all]
25           git subrepo version
26           git subrepo upgrade
27

Description

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

Benefits

34       This command is an improvement from "git-submodule" and "git-subtree";
35       two other git commands with similar goals, but various problems.
36
37       It assumes there are 3 main roles of people interacting with a repo,
38       and attempts to serve them all well:
39
40       ·   owner - The person who authors/owns/maintains a repo.
41
42       ·   users - People who are just using/installing the repo.
43
44       ·   collaborators - People who commit code to the repo and subrepos.
45
46       The "git-subrepo" command benefits these roles in the following ways:
47
48       ·   Simple and intuitive commandline usage (with tab completion).
49
50       ·   Users get your repo and all your subrepos just by cloning your
51           repo.
52
53       ·   Users do not need to install "git-subrepo", ever.
54
55       ·   Collaborators do not need to install unless they want to push/pull.
56
57       ·   Collaborators know when a subdir is a subrepo (it has a ".gitrepo"
58           file).
59
60       ·   The ".gitrepo" file never gets pushed back to the subrepo upstream.
61
62       ·   Well named branches and remotes are generated for manual
63           operations.
64
65       ·   Owners do not deal with the complications of keeping submodules in
66           sync.
67
68       ·   Subrepo repositories can contain subrepos themselves.
69
70       ·   Branching with subrepos JustWorks™.
71
72       ·   Different branches can have different subrepos in different states,
73           etc.
74
75       ·   Moving/renaming/deleting a subrepo subdir JustWorks™.
76
77       ·   You can "init" an existing subdirectory into a subrepo.
78
79       ·   Your git history is kept squeaky clean.
80
81       ·   Upstream history (clone/pull) is condensed into a single commit.
82
83       ·   Pulls can use a "merge", "rebase" or "force" strategies.
84
85       ·   You can see the subrepo history with "git log
86           subrepo/<subdir>/fetch".
87
88       ·   Commits pushed back upstream are not condensed (by default).
89
90       ·   Trivial to try any subrepo operations and then reset back.
91
92       ·   No configuration required.
93
94       ·   Does not introduce history that messes up other git commands.
95
96       ·   Fixes known rebase failures with "git-subtree".
97

Installation

99       The best short answer is:
100
101           git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
102           echo 'source /path/to/git-subrepo/.rc' >> ~/.bashrc
103
104       The complete "Installation Instructions" can be found below.
105
106       Note: git-subrepo needs a git version (> 2.7) that supports worktree:s.
107

Commands

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
114       Please note that the commands are not exact equivalents, and do not
115       take all the same arguments. Keep reading…
116
117       "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
121           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
125           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
130           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
134           The "--force" option will "reclone" (completely replace) an
135           existing subdir.
136
137           The "--method" option will decide how the join process between
138           branches are performed. The default option is merge.
139
140           The "clone" command accepts the "--branch=" "--edit", "--force" and
141           "-- message=" options.
142
143       "git subrepo init <subdir> [-r <remote>] [-b <branch>] [--method
144       <merge|rebase>]"
145           Turn an existing subdirectory into a subrepo.
146
147           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
153           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
161           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
165           The "--method" option will decide how the join process between
166           branches are performed. The default option is merge.
167
168           The "init" command accepts the "--branch=" and "--remote=" options.
169
170       "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
174           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
183           The "pull" command will attempt to do the following commands in one
184           go:
185
186               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
193           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
200           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
207           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
212           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
217               git log refs/subrepo/<subdir>/fetch
218
219           The set of commands used above are described in detail below.
220
221           The "pull" command accepts the "--all", "--branch=", "--edit",
222           "--force", "--message=", "--remote=" and "--update" options.
223
224       "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
228           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
234           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
239           By default the branch ref "refs/subrepo/<subdir>/pull" will be
240           pushed, but you can specify a (properly merged) branch to push.
241
242           After that, the "push" command just checks that the branch contains
243           the upstream HEAD and then pushes it upstream.
244
245           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
250           The "push" command accepts the "--all", "--branch=", "--dry-run",
251           "-- force", "--merge", "--rebase", "--remote=", "--squash" and "--
252           update" options.
253
254       "git subrepo fetch <subdir>|--all [-r <remote>] [-b <branch>]"
255           Fetch the remote/upstream content for a subrepo.
256
257           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
262           The "fetch" command accepts the "--all", "--branch=" and "--
263           remote=" options.
264
265       "git subrepo branch <subdir>|--all [-f] [-F]"
266           Create a branch with local subrepo commits.
267
268           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
272           This is useful for doing "pull" and "push" commands by hand.
273
274           Use the "--force" option to write over an existing
275           "subrepo/<subdir>" branch.
276
277           The "branch" command accepts the "--all", "--fetch" and "--force"
278           options.
279
280       "git subrepo commit <subdir> [<subrepo-ref>] [-m <msg>] [-e] [-f] [-F]"
281           Add subrepo branch to current history as a single commit.
282
283           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
289           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
293           The "commit" command accepts the "--edit", "--fetch", "--force" and
294           "-- message=" options.
295
296       "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
301           The "--verbose" option will show all the recent local and upstream
302           commits.
303
304           Use "--ALL" to show the subrepos of the subrepos (ie the
305           "subsubrepos"), if any.
306
307           The "status" command accepts the "--all", "--ALL", "--fetch",
308           "--quiet" and "--verbose" options.
309
310       "git subrepo clean <subdir>|--all|--ALL [-f]"
311           Remove artifacts created by "fetch" and "branch" commands.
312
313           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
317           Use "--force" to remove refs. Refs are not removed by default
318           because they are sometimes needed between commands.
319
320           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
325           To remove ALL subrepo artifacts:
326
327               git subrepo clean --ALL --force
328
329           The "clean" command accepts the "--all", "--ALL", and "--force"
330           options.
331
332       "git subrepo config <subdir> <option> [<value>] [-f]"
333           Read or update configuration values in the subdir/.gitrepo file.
334
335           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
339           Example to update the "method" option for a subrepo:
340
341               git subrepo config foo method rebase
342
343       "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
347           Use "git subrepo help <command>" to get help for a specific
348           command. Use "--all" to get a summary of all commands.
349
350           The "help" command accepts the "--all" option.
351
352       "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
358           The "version" command accepts the "--quiet" and "--verbose"
359           options.
360
361       "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

Command Options

369       "-h"
370           Show a brief view of the commands and options.
371
372       "--help"
373           Gives an overview of the help options available for the subrepo
374           command.
375
376       "--version"
377           Print the git-subrepo version. Just the version number. Try the
378           "version" command for more version info.
379
380       "--all" ("-a")
381           If you have multiple subrepos, issue the command to all of them (if
382           applicable).
383
384       "--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
389       "--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
393       "--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
398       "--edit" ("-e")
399           Edit the commit message before committing.
400
401       "--fetch" ("-F")
402           Use this option to fetch the upstream commits, before running the
403           command.
404
405       "--force" ("-f")
406           Use this option to force certain commands that fail in the general
407           case.
408
409           NOTE: The "--force" option means different things for different
410           commands.
411                 Read the command specific doc for the exact meaning.
412
413       "--merge" ("-M")
414           Use a "merge" strategy to include upstream subrepo commits on a
415           pull (or setup for push).
416
417       "--message=<message>" ("-m <message>")
418           Specify your own commit message on the command line.
419
420       "--rebase" ("-R")
421           Use a "rebase" strategy to include upstream subrepo commits on a
422           pull (or setup for push).
423
424       "--remote=<remote-url>" ("-r <remote-url>")
425           Use a different remote-url than the one saved in ".gitrepo"
426           locally.
427
428       "--squash" ("-s")
429           Squash all commits on a push into one new commit.
430
431       "--update" ("-u")
432           If "--branch" or "--remote" are used, and the command updates the
433           ".gitrepo" file, include these values to the update.
434

Output Options

436       "--quiet" ("-q")
437           Print as little info as possible. Applicable to most commands.
438
439       "--verbose" ("-v")
440           Print more information about the command execution and results.
441           Applicable to most commands.
442
443       "--debug" ("-d")
444           Show the actual git (and other) commands being executed under the
445           hood.  Applicable to most commands.
446
447       "--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

Environment Variables

453       The "git-subrepo" command exports and honors some environment
454       variables:
455
456       "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
461       "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
467       "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
471       "GIT_SUBREPO_PAGER"
472           Use this to specify the pager to use for long output commands.
473           Defaults to $PAGER or "less".
474
475       "GIT_SUBREPO_QUIET"
476           Set this for quiet ("-q") output.
477
478       "GIT_SUBREPO_VERBOSE"
479           Set this for verbose ("-v") output.
480
481       "GIT_SUBREPO_DEBUG"
482           Set this for debugging ("-d") output.
483

Installation Instructions

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
488           git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
489
490       The first installation method is preferred: "source" the ".rc" file.
491       Just add a line like this one to your shell startup script:
492
493           source /path/to/git-subrepo/.rc
494
495       That will modify your "PATH" and "MANPATH", and also enable command
496       completion.
497
498       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
502           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
506       See below for info on how to turn on Command Completion.
507
508       The third method is a standard system install, which puts "git-subrepo"
509       next to your other git commands:
510
511           make install        # Possibly with 'sudo'
512
513       This method does not account for upgrading and command completion yet.
514
515   Windows
516       This command is known to work in these Windows environments:
517
518       ·   Git for Windows -- <https://git-for-windows.github.io/>
519
520       ·   Babun -- <http://babun.github.io/>
521
522       ·   Cygwin -- <https://www.cygwin.com/>
523
524       Let us know if there are others that it works (or doesn't work) in.
525

Testing

527       The "git-subrepo" repository comes with a extensive test suite. You can
528       run it with:
529
530           make test
531
532       or if you don't have "make" on your system:
533
534           prove -v test
535

Upgrading

537       If you used the ".rc" or "PATH" method of installation, just run this
538       to upgrade "git-subrepo":
539
540           git subrepo upgrade
541
542       Or (same thing):
543
544           cd /path/to/git-subrepo
545           git pull
546
547       If you used "make install" method, then run this again (after "git
548       pull"):
549
550           make install        # Possibly with 'sudo'
551

Command Completion

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
557   In Bash
558       If your Bash setup does not already provide command completion for Git,
559       you'll need to enable that first:
560
561           source <Git completion script>
562
563       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
566       ·   "/etc/bash_completion.d/git"
567
568       ·   "/usr/share/bash-completion/git"
569
570       ·   "/usr/share/bash-completion/completions/git"
571
572       ·   "/opt/local/share/bash-completion/completions/git"
573
574       ·   "/usr/local/etc/bash_completion.d/git"
575
576       ·   "~/.homebrew/etc/bash_completion.d/git"
577
578       In case you can't find any of these, this repository contains a copy of
579       the Git completion script:
580
581           source /path/to/git-subrepo/share/git-completion.bash
582
583       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
587           source /path/to/git-subrepo/share/completion.bash
588
589   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
594           fpath=('/path/to/git-subrepo/share/zsh-completion' $fpath)
595

Status

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
601       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
606       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
610       If you want to chat about the "git-subrepo" command, join
611       "#gitcommands" on "irc.freenode.net".
612

Notes

614       ·   Works on POSIX systems: Linux, BSD, OSX, etc.
615
616       ·   Works on various Windows environments. See "Windows" section above.
617
618       ·   The "git-subrepo" repo itself has 2 subrepos under the "ext/"
619           subdirectory.
620
621       ·   Written in (very modern) Bash, with full test suite. Take a look.
622
623       ·   A ".gitrepo" file never is in the top level dir (next to a ".git/"
624           dir).
625

Authors

627       ·   Ingy döt Net <ingy@ingy.net>
628
629       ·   Magnus Carlsson <grimmymail@gmail.com>
630
631       ·   Austin Morgan <admorgan@morgancomputers.net>
632
634       The MIT License (MIT)
635
636       Copyright (c) 2013-2020 Ingy döt Net
637
638
639
640Generated by Swim v0.1.48        November 2020                        STDIN(1)
Impressum