{"id":13453974,"url":"https://github.com/ingydotnet/git-subrepo","last_synced_at":"2025-05-13T16:11:27.879Z","repository":{"id":12231405,"uuid":"14841814","full_name":"ingydotnet/git-subrepo","owner":"ingydotnet","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-19T05:26:21.000Z","size":1184,"stargazers_count":3357,"open_issues_count":200,"forks_count":277,"subscribers_count":67,"default_branch":"master","last_synced_at":"2025-04-23T20:57:54.712Z","etag":null,"topics":["bash","git"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ingydotnet.png","metadata":{"files":{"readme":"ReadMe.pod","changelog":"Changes","contributing":null,"funding":null,"license":"License","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-12-01T16:21:37.000Z","updated_at":"2025-04-22T08:15:55.000Z","dependencies_parsed_at":"2024-01-13T22:22:43.405Z","dependency_job_id":"1fe37e94-8d04-49a4-bcda-ec775a0c3589","html_url":"https://github.com/ingydotnet/git-subrepo","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingydotnet%2Fgit-subrepo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingydotnet%2Fgit-subrepo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingydotnet%2Fgit-subrepo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingydotnet%2Fgit-subrepo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ingydotnet","download_url":"https://codeload.github.com/ingydotnet/git-subrepo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250514767,"owners_count":21443208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","git"],"created_at":"2024-07-31T08:00:49.950Z","updated_at":"2025-04-23T20:58:09.133Z","avatar_url":"https://github.com/ingydotnet.png","language":"Shell","funding_links":[],"categories":["Shell","Development","bash"],"sub_categories":["Time Series"],"readme":"=pod\n\n=for comment\nDO NOT EDIT. This Pod was generated by Swim v0.1.48.\nSee http://github.com/ingydotnet/swim-pm#readme\n\n=encoding utf8\n\n=head1 Name\n\ngit-subrepo - Git Submodule Alternative\n\n=head1 Synopsis\n\n    git subrepo -h    # Help Overview\n\n    git subrepo clone \u003cremote-url\u003e [\u003csubdir\u003e]\n    git subrepo init \u003csubdir\u003e\n    git subrepo pull \u003csubdir\u003e\n    git subrepo push \u003csubdir\u003e\n\n    git subrepo fetch \u003csubdir\u003e\n    git subrepo branch \u003csubdir\u003e\n    git subrepo commit \u003csubdir\u003e\n    git subrepo config \u003csubdir\u003e\n\n    git subrepo status [\u003csubdir\u003e]\n    git subrepo clean \u003csubdir\u003e\n\n    git subrepo help [\u003ccommand\u003e | --all]\n    git subrepo version\n    git subrepo upgrade\n\n=head1 Description\n\nThis git command \"clones\" an external git repo into a subdirectory of your\nrepo. Later on, upstream changes can be pulled in, and local changes can be\npushed back. Simple.\n\n=head1 Benefits\n\nThis command is an improvement from C\u003cgit-submodule\u003e and C\u003cgit-subtree\u003e; two\nother git commands with similar goals, but various problems.\n\nIt assumes there are 3 main roles of people interacting with a repo, and\nattempts to serve them all well:\n\n=over\n\n=item * B\u003cowner\u003e - The person who authors/owns/maintains a repo.\n\n=item * B\u003cusers\u003e - People who are just using/installing the repo.\n\n=item * B\u003ccollaborators\u003e - People who commit code to the repo and subrepos.\n\n=back\n\nThe C\u003cgit-subrepo\u003e command benefits these roles in the following ways:\n\n=over\n\n=item * Simple and intuitive commandline usage (with tab completion).\n\n=item * Users get your repo and all your subrepos just by cloning your repo.\n\n=item * Users do not need to install C\u003cgit-subrepo\u003e, ever.\n\n=item * Collaborators do not need to install unless they want to push/pull.\n\n=item * Collaborators know when a subdir is a subrepo (it has a C\u003c.gitrepo\u003e file).\n\n=item * The C\u003c.gitrepo\u003e file never gets pushed back to the subrepo upstream.\n\n=item * Well named branches and remotes are generated for manual operations.\n\n=item * Owners do not deal with the complications of keeping submodules in sync.\n\n=item * Subrepo repositories can contain subrepos themselves.\n\n=item * Branching with subrepos JustWorks™.\n\n=item * Different branches can have different subrepos in different states, etc.\n\n=item * Moving/renaming/deleting a subrepo subdir JustWorks™.\n\n=item * You can C\u003cinit\u003e an existing subdirectory into a subrepo.\n\n=item * Your git history is kept squeaky clean.\n\n=item * Upstream history (clone/pull) is condensed into a single commit.\n\n=item * Pulls can use a C\u003cmerge\u003e, C\u003crebase\u003e or C\u003cforce\u003e strategies.\n\n=item * You can see the subrepo history with C\u003c\u003c git log subrepo/\u003csubdir\u003e/fetch \u003e\u003e.\n\n=item * Commits pushed back upstream are B\u003cnot\u003e condensed (by default).\n\n=item * Trivial to try any subrepo operations and then reset back.\n\n=item * No configuration required.\n\n=item * Does not introduce history that messes up other git commands.\n\n=item * Fixes known rebase failures with C\u003cgit-subtree\u003e.\n\n=back\n\n=head1 Installation\n\nThe best short answer is:\n\n    git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo\n    echo 'source /path/to/git-subrepo/.rc' \u003e\u003e ~/.bashrc\n\nThe complete \"Installation Instructions\" can be found below.\n\nNote: git-subrepo needs a git version (\u003e 2.7) that supports worktree:s.\n\n=head1 Commands\n\nAll the B\u003csubrepo\u003e commands use names of actual Git commands and try to do\noperations that are similar to their Git counterparts. They also attempt to\ngive similar output in an attempt to make the subrepo usage intuitive to\nexperienced Git users.\n\nPlease note that the commands are I\u003cnot\u003e exact equivalents, and do not take\nall the same arguments. Keep reading…\n\n=over\n\n=item C\u003c\u003c git subrepo clone \u003crepository\u003e [\u003csubdir\u003e] [-b \u003cbranch\u003e] [-f] [-m \u003cmsg\u003e] [--file=\u003cmsg file\u003e] [-e] [--method \u003cmerge|rebase\u003e] \u003e\u003e\n\nAdd a repository as a subrepo in a subdir of your repository.\n\nThis is similar in feel to C\u003cgit clone\u003e. You just specify the remote repo url,\nand optionally a sub-directory and/or branch name. The repo will be fetched\nand merged into the subdir.\n\nThe subrepo history is I\u003csquashed\u003e into a single commit that contains the\nreference information. This information is also stored in a special file\ncalled C\u003c\u003c \u003csubdir\u003e/.gitrepo \u003e\u003e. The presence of this file indicates that the\ndirectory is a subrepo.\n\nAll subsequent commands refer to the subrepo by the name of the\nI\u003csubdir\u003e. From the subdir, all the current information about the subrepo\ncan be obtained.\n\nThe C\u003c--force\u003e option will \"reclone\" (completely replace) an existing subdir.\n\nThe C\u003c--method\u003e option will decide how the join process between branches are\nperformed. The default option is merge.\n\nThe C\u003cclone\u003e command accepts the C\u003c--branch=\u003e C\u003c--edit\u003e, C\u003c--file\u003e, C\u003c--force\u003e\nand C\u003c--message=\u003e options.\n\n=item C\u003c\u003c git subrepo init \u003csubdir\u003e [-r \u003cremote\u003e] [-b \u003cbranch\u003e] [--method \u003cmerge|rebase\u003e] \u003e\u003e\n\nTurn an existing subdirectory into a subrepo.\n\nIf you want to expose a subdirectory of your project as a published subrepo,\nthis command will do that. It will split out the content of a normal\nsubdirectory into a branch and start tracking it as a subrepo. Afterwards your\noriginal repo will look exactly the same except that there will be a C\u003c\u003c\u003csubdir\u003e/.gitrepo \u003e\u003e file.\n\nIf you specify the C\u003c--remote\u003e (and optionally the C\u003c--branch\u003e) option, the\nvalues will be added to the C\u003c\u003c \u003csubdir\u003e/.gitrepo \u003e\u003e file. The C\u003c--remote\u003e\noption is the upstream URL, and the C\u003c--branch\u003e option is the upstream branch\nto push to. These values will be needed to do a C\u003cgit subrepo push\u003e command,\nbut they can be provided later on the C\u003cpush\u003e command (and saved to C\u003c\u003c\u003csubdir\u003e/.gitrepo \u003e\u003e if you also specify the C\u003c--update\u003e option).\n\nNote: You will need to create the empty upstream repo and push to it on your\n      own, using C\u003c\u003c git subrepo push \u003csubdir\u003e \u003e\u003e.\n\nThe C\u003c--method\u003e option will decide how the join process between branches are\nperformed. The default option is merge.\n\nThe C\u003cinit\u003e command accepts the C\u003c--branch=\u003e and C\u003c--remote=\u003e options.\n\n=item C\u003c\u003c git subrepo pull \u003csubdir\u003e|--all [-M|-R|-f] [-m \u003cmsg\u003e] [--file=\u003cmsg file\u003e] [-e] [-b \u003cbranch\u003e] [-r \u003cremote\u003e] [-u] \u003e\u003e\n\nUpdate the subrepo subdir with the latest upstream changes.\n\nThe C\u003cpull\u003e command fetches the latest content from the remote branch pointed\nto by the subrepo's C\u003c.gitrepo\u003e file, and then tries to merge the changes into\nthe corresponding subdir. It does this by making a branch of the local commits\nto the subdir and then merging or rebasing (see below) it with the fetched\nupstream content. After the merge, the content of the new branch replaces your\nsubdir, the C\u003c.gitrepo\u003e file is updated and a single 'pull' commit is added to\nyour mainline history.\n\nThe C\u003cpull\u003e command will attempt to do the following commands in one go:\n\n    git subrepo fetch \u003csubdir\u003e\n    git subrepo branch \u003csubdir\u003e\n    git merge/rebase subrepo/\u003csubdir\u003e/fetch subrepo/\u003csubdir\u003e\n    git subrepo commit \u003csubdir\u003e\n    # Only needed for a consequential push:\n    git update-ref refs/subrepo/\u003csubdir\u003e/pull subrepo/\u003csubdir\u003e\n\nIn other words, you could do all the above commands yourself, for the same\neffect. If any of the commands fail, subrepo will stop and tell you to finish\nthis by hand. Generally a failure would be in the merge or rebase part, where\nconflicts can happen. Since Git has lots of ways to resolve conflicts to your\npersonal tastes, the subrepo command defers to letting you do this by hand.\n\nWhen pulling new data, the method selected in clone/init is used. This has no\neffect on the final result of the pull, since it becomes a single commit. But\nit does affect the resulting C\u003c\u003c subrepo/\u003csubdir\u003e \u003e\u003e branch, which is often\nused for a subrepo C\u003cpush\u003e command. See 'push' below for more information. If\nyou want to change the method you can use the C\u003cconfig\u003e command for this.\n\nWhen you pull you can assume a fast-forward strategy (default) or you can\nspecify a C\u003c--rebase\u003e, C\u003c--merge\u003e or C\u003c--force\u003e strategy. The latter is the\nsame as a C\u003cclone --force\u003e operation, using the current remote and branch.\n\nLike the C\u003cclone\u003e command, C\u003cpull\u003e will squash all the changes (since the last\npull or clone) into one commit. This keeps your mainline history nice and\nclean. You can easily see the subrepo's history with the C\u003cgit log\u003e command:\n\n    git log refs/subrepo/\u003csubdir\u003e/fetch\n\nThe set of commands used above are described in detail below.\n\nThe C\u003cpull\u003e command accepts the C\u003c--all\u003e, C\u003c--branch=\u003e, C\u003c--edit\u003e, C\u003c--file\u003e,\nC\u003c--force\u003e, C\u003c--message=\u003e, C\u003c--remote=\u003e and C\u003c--update\u003e options.\n\n=item C\u003c\u003c git subrepo push \u003csubdir\u003e|--all [\u003cbranch\u003e] [-m msg] [--file=\u003cmsg file\u003e] [-r \u003cremote\u003e] [-b \u003cbranch\u003e] [-M|-R] [-u] [-f] [-s] [-N] \u003e\u003e\n\nPush a properly merged subrepo branch back upstream.\n\nThis command takes the subrepo branch from a successful pull command and\npushes the history back to its designated remote and branch. You can also use\nthe C\u003cbranch\u003e command and merge things yourself before pushing if you want to\n(although that is probably a rare use case).\n\nThe C\u003cpush\u003e command requires a branch that has been properly merged/rebased\nwith the upstream HEAD (unless the upstream HEAD is empty, which is common\nwhen doing a first C\u003cpush\u003e after an C\u003cinit\u003e). That means the upstream HEAD is\none of the commits in the branch.\n\nBy default the branch ref C\u003c\u003c refs/subrepo/\u003csubdir\u003e/pull \u003e\u003e will be pushed,\nbut you can specify a (properly merged) branch to push.\n\nAfter that, the C\u003cpush\u003e command just checks that the branch contains the\nupstream HEAD and then pushes it upstream.\n\nThe C\u003c--force\u003e option will do a force push. Force pushes are typically\ndiscouraged. Only use this option if you fully understand it. (The C\u003c--force\u003e\noption will NOT check for a proper merge. ANY branch will be force pushed!)\n\nThe C\u003cpush\u003e command accepts the C\u003c--all\u003e, C\u003c--branch=\u003e, C\u003c--dry-run\u003e, C\u003c--file\u003e, C\u003c--force\u003e, C\u003c--merge\u003e, C\u003c--message\u003e, C\u003c--rebase\u003e, C\u003c--remote=\u003e, C\u003c--squash\u003e and C\u003c--update\u003e options.\n\n=item C\u003c\u003c git subrepo fetch \u003csubdir\u003e|--force --all [-r \u003cremote\u003e] [-b \u003cbranch\u003e] \u003e\u003e\n\nFetch the remote/upstream content for a subrepo.\n\nIt will create a Git reference called C\u003c\u003c subrepo/\u003csubdir\u003e/fetch \u003e\u003e that\npoints at the same commit as C\u003cFETCH_HEAD\u003e. It will also create a remote\ncalled C\u003c\u003c subrepo/\u003csubdir\u003e \u003e\u003e. These are temporary and you can easily remove\nthem with the subrepo C\u003cclean\u003e command.\n\nThe C\u003cfetch\u003e command accepts the C\u003c--force\u003e, C\u003c--all\u003e, C\u003c--branch=\u003e and C\u003c--remote=\u003e options.\n\n=item C\u003c\u003c git subrepo branch \u003csubdir\u003e|--all [-f] [-F] \u003e\u003e\n\nCreate a branch with local subrepo commits.\n\nScan the history of the mainline for all the commits that affect the C\u003csubdir\u003e\nand create a new branch from them called C\u003c\u003c subrepo/\u003csubdir\u003e \u003e\u003e.\n\nThis is useful for doing C\u003cpull\u003e and C\u003cpush\u003e commands by hand.\n\nUse the C\u003c--force\u003e option to write over an existing C\u003c\u003c subrepo/\u003csubdir\u003e\n\u003e\u003e branch.\n\nThe C\u003cbranch\u003e command accepts the C\u003c--all\u003e, C\u003c--fetch\u003e and C\u003c--force\u003e options.\n\n=item C\u003c\u003c git subrepo commit \u003csubdir\u003e [\u003csubrepo-ref\u003e] [-m \u003cmsg\u003e] [--file=\u003cmsg file\u003e] [-e] [-f] [-F] \u003e\u003e\n\nAdd subrepo branch to current history as a single commit.\n\nThis command is generally used after a hand-merge. You have done a C\u003csubrepobranch\u003e and merged (rebased) it with the upstream. This command takes the HEAD\nof that branch, puts its content into the subrepo subdir and adds a new commit\nfor it to the top of your mainline history.\n\nThis command requires that the upstream HEAD be in the C\u003c\u003c subrepo/\u003csubdir\u003e \u003e\u003e\nbranch history. That way the same branch can push upstream. Use the C\u003c--force\u003e\noption to commit anyway.\n\nThe C\u003ccommit\u003e command accepts the C\u003c--edit\u003e, C\u003c--fetch\u003e, C\u003c--file\u003e, C\u003c--force\u003e\nand C\u003c--message=\u003e options.\n\n=item C\u003c\u003c git subrepo status [\u003csubdir\u003e|--all|--ALL] [-F] [-q|-v] \u003e\u003e\n\nGet the status of a subrepo. Uses the C\u003c--all\u003e option by default. If the C\u003c--quiet\u003e flag is used, just print the subrepo names, one per line.\n\nThe C\u003c--verbose\u003e option will show all the recent local and upstream commits.\n\nUse C\u003c--ALL\u003e to show the subrepos of the subrepos (ie the\n\"subsubrepos\"), if any.\n\nThe C\u003cstatus\u003e command accepts the C\u003c--all\u003e, C\u003c--ALL\u003e, C\u003c--fetch\u003e, C\u003c--quiet\u003e\nand C\u003c--verbose\u003e options.\n\n=item C\u003c\u003c git subrepo clean \u003csubdir\u003e|--all|--ALL [-f] \u003e\u003e\n\nRemove artifacts created by C\u003cfetch\u003e and C\u003cbranch\u003e commands.\n\nThe C\u003cfetch\u003e and C\u003cbranch\u003e operations (and other commands that call them)\ncreate temporary things like refs, branches and remotes. This command removes\nall those things.\n\nUse C\u003c--force\u003e to remove refs. Refs are not removed by default because they\nare sometimes needed between commands.\n\nUse C\u003c--all\u003e to clean up after all the current subrepos. Sometimes you might\nchange to a branch where a subrepo doesn't exist, and then C\u003c--all\u003e won't find\nit. Use C\u003c--ALL\u003e to remove any artifacts that were ever created by subrepo.\n\nTo remove ALL subrepo artifacts:\n\n    git subrepo clean --ALL --force\n\nThe C\u003cclean\u003e command accepts the C\u003c--all\u003e, C\u003c--ALL\u003e, and C\u003c--force\u003e options.\n\n=item C\u003c\u003c git subrepo config \u003csubdir\u003e \u003coption\u003e [\u003cvalue\u003e] [-f] \u003e\u003e\n\nRead or update configuration values in the subdir/.gitrepo file.\n\nBecause most of the values stored in the .gitrepo file are generated you\nwill need to use C\u003c--force\u003e if you want to change anything else then the\nC\u003cmethod\u003e option.\n\nExample to update the C\u003cmethod\u003e option for a subrepo:\n\n    git subrepo config foo method rebase\n\n=item C\u003c\u003c git subrepo help [\u003ccommand\u003e|--all] \u003e\u003e\n\nSame as C\u003cgit help subrepo\u003e. Will launch the manpage. For the shorter usage,\nuse C\u003cgit subrepo -h\u003e.\n\nUse C\u003c\u003c git subrepo help \u003ccommand\u003e \u003e\u003e to get help for a specific command. Use\nC\u003c--all\u003e to get a summary of all commands.\n\nThe C\u003chelp\u003e command accepts the C\u003c--all\u003e option.\n\n=item C\u003cgit subrepo version [-q|-v]\u003e\n\nThis command will display version information about git-subrepo and its\nenvironment. For just the version number, use C\u003cgit subrepo --version\u003e. Use\nC\u003c--verbose\u003e for more version info, and C\u003c--quiet\u003e for less.\n\nThe C\u003cversion\u003e command accepts the C\u003c--quiet\u003e and C\u003c--verbose\u003e options.\n\n=item C\u003cgit subrepo upgrade\u003e\n\nUpgrade the C\u003cgit-subrepo\u003e software itself. This simply does a C\u003cgit pull\u003e\non the git repository that the code is running from. It only works if you\nare on the C\u003cmaster\u003e branch. It won't work if you installed C\u003cgit-subrepo\u003e\nusing C\u003cmake install\u003e; in that case you'll need to C\u003cmake install\u003e from the\nlatest code.\n\n=back\n\n=head1 Command Options\n\n=over\n\n=item C\u003c-h\u003e\n\nShow a brief view of the commands and options.\n\n=item C\u003c--help\u003e\n\nGives an overview of the help options available for the subrepo command.\n\n=item C\u003c--version\u003e\n\nPrint the git-subrepo version. Just the version number. Try the C\u003cversion\u003e\ncommand for more version info.\n\n=item C\u003c--all\u003e (C\u003c-a\u003e)\n\nIf you have multiple subrepos, issue the command to all of them (if\napplicable).\n\n=item C\u003c--ALL\u003e (C\u003c-A\u003e)\n\nIf you have subrepos that also have subrepos themselves, issue the command to\nALL of them. Note that the C\u003c--ALL\u003e option only works for a subset of the\ncommands that C\u003c--all\u003e works for.\n\n=item C\u003c\u003c --branch=\u003cbranch-name\u003e \u003e\u003e (C\u003c\u003c -b \u003cbranch-name\u003e \u003e\u003e)\n\nUse a different upstream branch-name than the remote HEAD or the one saved in\nC\u003c.gitrepo\u003e locally.\n\n=item C\u003c--dry-run\u003e (C\u003c-N\u003e)\n\nFor the push command, do everything up until the push and then print out the\nactual C\u003cgit push\u003e command needed to finish the operation.\n\n=item C\u003c--edit\u003e (C\u003c-e\u003e)\n\nEdit the commit message before committing.\n\n=item C\u003c--fetch\u003e (C\u003c-F\u003e)\n\nUse this option to fetch the upstream commits, before running the command.\n\n=item C\u003c\u003c --file=\u003ccommit msg file\u003e \u003e\u003e\n\nSupply your own commit message from a file\n\n=item C\u003c--force\u003e (C\u003c-f\u003e)\n\nUse this option to force certain commands that fail in the general case.\n\nNOTE: The C\u003c--force\u003e option means different things for different commands.\n      Read the command specific doc for the exact meaning.\n\n=item C\u003c--merge\u003e (C\u003c-M\u003e)\n\nUse a C\u003cmerge\u003e strategy to include upstream subrepo commits on a pull (or\nsetup for push).\n\n=item C\u003c\u003c --message=\u003cmessage\u003e \u003e\u003e (C\u003c\u003c -m \u003cmessage\u003e \u003e\u003e)\n\nSpecify your own commit message on the command line.\n\n=item C\u003c--rebase\u003e (C\u003c-R\u003e)\n\nUse a C\u003crebase\u003e strategy to include upstream subrepo commits on a pull (or\nsetup for push).\n\n=item C\u003c\u003c --remote=\u003cremote-url\u003e \u003e\u003e (C\u003c\u003c -r \u003cremote-url\u003e \u003e\u003e)\n\nUse a different remote-url than the one saved in C\u003c.gitrepo\u003e locally.\n\n=item C\u003c--squash\u003e (C\u003c-s\u003e)\n\nSquash all commits on a push into one new commit.\n\n=item C\u003c--update\u003e (C\u003c-u\u003e)\n\nIf C\u003c--branch\u003e or C\u003c--remote\u003e are used, and the command updates the\nC\u003c.gitrepo\u003e file, include these values to the update.\n\n=back\n\n=head1 Output Options\n\n=over\n\n=item C\u003c--quiet\u003e (C\u003c-q\u003e)\n\nPrint as little info as possible. Applicable to most commands.\n\n=item C\u003c--verbose\u003e (C\u003c-v\u003e)\n\nPrint more information about the command execution and results. Applicable to\nmost commands.\n\n=item C\u003c--debug\u003e (C\u003c-d\u003e)\n\nShow the actual git (and other) commands being executed under the hood.\nApplicable to most commands.\n\n=item C\u003c--DEBUG\u003e (C\u003c-x\u003e)\n\nUse the Bash C\u003cset -x\u003e option which prints every command before it is\nrun. VERY noisy, but extremely useful in deep debugging. Applicable to\nall commands.\n\n=back\n\n=head1 Environment Variables\n\nThe C\u003cgit-subrepo\u003e command exports and honors some environment variables:\n\n=over\n\n=item C\u003cGIT_SUBREPO_ROOT\u003e\n\nThis is set by the C\u003c.rc\u003e file, if you use that method to install / enable C\u003cgit-subrepo\u003e. It contains the path of the C\u003cgit-subrepo\u003e repository.\n\n=item C\u003cGIT_SUBREPO_RUNNING\u003e\n\nThis variable is exported when C\u003cgit-subrepo\u003e is running. It is set to the pid\nof the C\u003cgit-subrepo\u003e process that is running. Other processes, like git hooks\nfor instance, can use this information to adjust accordingly.\n\n=item C\u003cGIT_SUBREPO_COMMAND\u003e\n\nThis variable is exported when C\u003cgit-subrepo\u003e is running. It is set to the\nname of the C\u003cgit-subrepo\u003e subcommand that is running.\n\n=item C\u003cGIT_SUBREPO_PAGER\u003e\n\nUse this to specify the pager to use for long output commands. Defaults to\nC\u003c$PAGER\u003e or C\u003cless\u003e.\n\n=item C\u003cGIT_SUBREPO_QUIET\u003e\n\nSet this for quiet (C\u003c-q\u003e) output.\n\n=item C\u003cGIT_SUBREPO_VERBOSE\u003e\n\nSet this for verbose (C\u003c-v\u003e) output.\n\n=item C\u003cGIT_SUBREPO_DEBUG\u003e\n\nSet this for debugging (C\u003c-d\u003e) output.\n\n=back\n\n=head1 Installation Instructions\n\nThere are currently 3 ways to install C\u003cgit-subrepo\u003e. For all of them you need\nto get the source code from GitHub:\n\n    git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo\n\nThe first installation method is preferred: C\u003csource\u003e the C\u003c.rc\u003e file. Just\nadd a line like this one to your shell startup script:\n\n    source /path/to/git-subrepo/.rc\n\nThat will modify your C\u003cPATH\u003e and C\u003cMANPATH\u003e, and also enable command\ncompletion.\n\nThe second method is to do these things by hand. This might afford you more\ncontrol of your shell environment. Simply add the C\u003clib\u003e and C\u003cman\u003e\ndirectories to your C\u003cPATH\u003e and C\u003cMANPATH\u003e:\n\n    export GIT_SUBREPO_ROOT=\"/path/to/git-subrepo\"\n    export PATH=\"/path/to/git-subrepo/lib:$PATH\"\n    export MANPATH=\"/path/to/git-subrepo/man:$MANPATH\"\n\nSee below for info on how to turn on Command Completion.\n\nThe third method is a standard system install, which puts C\u003cgit-subrepo\u003e next\nto your other git commands:\n\n    make install        # Possibly with 'sudo'\n\nThis method does not account for upgrading and command completion yet.\n\n=head2 Windows\n\nThis command is known to work in these Windows environments:\n\n=over\n\n=item * Git for Windows -- L\u003chttps://git-for-windows.github.io/\u003e\n\n=item * Babun -- L\u003chttp://babun.github.io/\u003e\n\n=item * Cygwin -- L\u003chttps://www.cygwin.com/\u003e\n\n=back\n\nLet us know if there are others that it works (or doesn't work) in.\n\n=head1 Testing\n\nThe C\u003cgit-subrepo\u003e repository comes with a extensive test suite. You can\nrun it with:\n\n    make test\n\nor if you don't have C\u003cmake\u003e on your system:\n\n    prove -v test\n\n=head1 Upgrading\n\nIf you used the C\u003c.rc\u003e or C\u003cPATH\u003e method of installation, just run this to\nupgrade C\u003cgit-subrepo\u003e:\n\n    git subrepo upgrade\n\nOr (same thing):\n\n    cd /path/to/git-subrepo\n    git pull\n\nIf you used C\u003cmake install\u003e method, then run this again (after C\u003cgit pull\u003e):\n\n    make install        # Possibly with 'sudo'\n\n=head1 Command Completion\n\nThe C\u003cgit subrepo\u003e command supports C\u003c\u003c \u003cTAB\u003e \u003e\u003e-based command completion. If\nyou don't use the C\u003c.rc\u003e script (see Installation, above), you'll need to\nenable this manually to use it.\n\n=head2 In Bash\n\nIf your Bash setup does not already provide command completion for Git, you'll\nneed to enable that first:\n\n    source \u003cGit completion script\u003e\n\nOn your system, the Git completion script might be found at any of the\nfollowing locations (or somewhere else that we don't know about):\n\n=over\n\n=item * C\u003c/etc/bash_completion.d/git\u003e\n\n=item * C\u003c/usr/share/bash-completion/git\u003e\n\n=item * C\u003c/usr/share/bash-completion/completions/git\u003e\n\n=item * C\u003c/opt/local/share/bash-completion/completions/git\u003e\n\n=item * C\u003c/usr/local/etc/bash_completion.d/git\u003e\n\n=item * C\u003c~/.homebrew/etc/bash_completion.d/git\u003e\n\n=back\n\nIn case you can't find any of these, this repository contains a copy of the\nGit completion script:\n\n    source /path/to/git-subrepo/share/git-completion.bash\n\nOnce Git completion is enabled (whether you needed to do that manually or\nnot), you can turn on C\u003cgit-subrepo\u003e completion with a command like this:\n\n    source /path/to/git-subrepo/share/completion.bash\n\n=head2 In zsh\n\nIn the Z shell (zsh), you can manually enable C\u003cgit-subrepo\u003e completion by\nadding the following line to your C\u003c~/.zshrc\u003e, B\u003cbefore\u003e the C\u003ccompinit\u003e\nfunction is called:\n\n    fpath=('/path/to/git-subrepo/share/zsh-completion' $fpath)\n\n=head1 Status\n\nThe git-subrepo command has been used in production and seems to get the job\ndone. Development is still ongoing but mostly just for fixing bugs.\n\nTrying subrepo out is simple and painless (this is not C\u003cgit submodule\u003e).\nNothing is permanent (if you do not push to shared remotes). ie You can always\nplay around and reset back to the beginning without pain.\n\nThis command has a test suite (run C\u003cmake test\u003e), but surely has many bugs. If\nyou have expertise with Git and subcommands, please review the code, and file\nissues on anything that seems wrong.\n\nIf you want to chat about the C\u003cgit-subrepo\u003e command, join C\u003c#gitcommands\u003e on\nC\u003circ.freenode.net\u003e.\n\n=head1 Notes\n\n=over\n\n=item * Works on POSIX systems: Linux, BSD, OSX, etc.\n\n=item * Works on various Windows environments. See \"Windows\" section above.\n\n=item * The C\u003cgit-subrepo\u003e repo itself has 2 subrepos under the C\u003cext/\u003e subdirectory.\n\n=item * Written in (very modern) Bash, with full test suite. Take a look.\n\n=item * A C\u003c.gitrepo\u003e file never is in the top level dir (next to a C\u003c.git/\u003e dir).\n\n=back\n\n=head1 Working with nested subrepos\n\nC\u003cgit-subrepo\u003e supports adding subrepos which themselves make use of subrepos.\nIn fact, subrepo itself is built this way. Take a look in the C\u003cext/\u003e folder,\nit houses 2 dependencies as subrepos, C\u003ctest-more-bash\u003e and C\u003cbashplus\u003e.\n\nC\u003ctest-more-bash\u003e itself depends on 2 more subrepos: C\u003cbashplus\u003e again, and\nC\u003ctest-tap-bash\u003e.\n\nThe structure is therefore as follows:\n\n    git-subrepo\n      |- bashplus\n      |- test-more-bash\n        |- bashplus\n        |- test-tap-bash\n\nHowever, it's important to understand how this works. Here's the key idea:\nThere is B\u003cno\u003e special handling for nested subrepos.\n\nWhen you clone a subrepo, B\u003call\u003e C\u003cgit-subrepo\u003e does is download the code and\nset up the subrepo file. This means that all the subrepo commands simply act\non the subrepo as a whole, treating nested subrepos like any other part of the\nsource code.\n\nLet's look at what this means in practice. Say you have a structure as\nfollows:\n\n    app-foo\n      |- barlib\n         |- bazlib\n\nYou're working on app-foo, and make some changes to bazlib. How should you\nupstream these changes?\n\nFrom the perspective of app-foo, you've simply made some changes to barlib.\nWhether or not those changes were themselves in a subrepo is irrelevant. So,\njust like any other changes, you run\n\nC\u003cgit subrepo push barlib\u003e\n\nNow, if C\u003cbarlib\u003e is a library you don't maintain, your responsibility would\nend here. C\u003cbarlib\u003e's maintainer would see your changes and decide what to do\nwith them.\n\nIf you do maintain C\u003cbarlib\u003e, you might now want to upstream the changes all\nthe way into C\u003cbazlib\u003e. You could be tempted to try running something like:\n\nC\u003cgit subrepo push barlib/bazlib\u003e\n\nbut you'll soon find out that doesn't work. C\u003capp-foo\u003e doesn't know anything\nabout the link between C\u003cbarlib\u003e and C\u003cbazlib\u003e.\n\nWhat you should do is treat the changes to C\u003cbarlib\u003e as if they would come\nfrom another contributor, aka:\n\n=over\n\n=item * go to a local copy of C\u003cbarlib\u003e\n\n=item * pull down the changes with C\u003cgit pull\u003e\n\n=item * you notice the changes include some work on your subrepo, time to upstream them: C\u003cgit subrepo push bazlib\u003e\n\n=back\n\nAnd you're done! One final step you'll likely want to do is to go back to C\u003capp-foo\u003e and run C\u003cgit subrepo pull barlib\u003e, because the push you just did added a\nnew commit.\n\n=head1 Authors\n\n=over\n\n=item * Ingy döt Net \u003cingy@ingy.net\u003e\n\n=item * Magnus Carlsson \u003cgrimmymail@gmail.com\u003e\n\n=item * Austin Morgan \u003cadmorgan@morgancomputers.net\u003e\n\n=back\n\n=head1 License and Copyright\n\nThe MIT License (MIT)\n\nCopyright (c) 2013-2024 Ingy döt Net\n\n=cut\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingydotnet%2Fgit-subrepo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fingydotnet%2Fgit-subrepo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingydotnet%2Fgit-subrepo/lists"}