eac_tools 0.101.0 → 0.101.1

data/sub/eac_git/vendor/git-subrepo/ReadMe.pod

@@ -1,698 +0,0 @@
-=pod
-
-=for comment
-DO NOT EDIT. This Pod was generated by Swim v0.1.48.
-See http://github.com/ingydotnet/swim-pm#readme
-
-=encoding utf8
-
-=head1 Name
-
-git-subrepo - Git Submodule Alternative
-
-=for html
-<a href="https://travis-ci.org/ingydotnet/git-subrepo"><img src="https://travis-ci.org/ingydotnet/git-subrepo.png" alt="git-subrepo"></a>
-
-=head1 Synopsis
-
-    git subrepo -h    # Help Overview
-
-    git subrepo clone <remote-url> [<subdir>]
-    git subrepo init <subdir>
-    git subrepo pull <subdir>
-    git subrepo push <subdir>
-
-    git subrepo fetch <subdir>
-    git subrepo branch <subdir>
-    git subrepo commit <subdir>
-    git subrepo config <subdir>
-
-    git subrepo status [<subdir>]
-    git subrepo clean <subdir>
-
-    git subrepo help [<command> | --all]
-    git subrepo version
-    git subrepo upgrade
-
-=head1 Description
-
-This git command "clones" an external git repo into a subdirectory of your
-repo. Later on, upstream changes can be pulled in, and local changes can be
-pushed back. Simple.
-
-=head1 Benefits
-
-This command is an improvement from C<git-submodule> and C<git-subtree>; two
-other git commands with similar goals, but various problems.
-
-It assumes there are 3 main roles of people interacting with a repo, and
-attempts to serve them all well:
-
-=over
-
-=item * B<owner> - The person who authors/owns/maintains a repo.
-
-=item * B<users> - People who are just using/installing the repo.
-
-=item * B<collaborators> - People who commit code to the repo and subrepos.
-
-=back
-
-The C<git-subrepo> command benefits these roles in the following ways:
-
-=over
-
-=item * Simple and intuitive commandline usage (with tab completion).
-
-=item * Users get your repo and all your subrepos just by cloning your repo.
-
-=item * Users do not need to install C<git-subrepo>, ever.
-
-=item * Collaborators do not need to install unless they want to push/pull.
-
-=item * Collaborators know when a subdir is a subrepo (it has a C<.gitrepo> file).
-
-=item * The C<.gitrepo> file never gets pushed back to the subrepo upstream.
-
-=item * Well named branches and remotes are generated for manual operations.
-
-=item * Owners do not deal with the complications of keeping submodules in sync.
-
-=item * Subrepo repositories can contain subrepos themselves.
-
-=item * Branching with subrepos JustWorks™.
-
-=item * Different branches can have different subrepos in different states, etc.
-
-=item * Moving/renaming/deleting a subrepo subdir JustWorks™.
-
-=item * You can C<init> an existing subdirectory into a subrepo.
-
-=item * Your git history is kept squeaky clean.
-
-=item * Upstream history (clone/pull) is condensed into a single commit.
-
-=item * Pulls can use a C<merge>, C<rebase> or C<force> strategies.
-
-=item * You can see the subrepo history with C<< git log subrepo/<subdir>/fetch >>.
-
-=item * Commits pushed back upstream are B<not> condensed (by default).
-
-=item * Trivial to try any subrepo operations and then reset back.
-
-=item * No configuration required.
-
-=item * Does not introduce history that messes up other git commands.
-
-=item * Fixes known rebase failures with C<git-subtree>.
-
-=back
-
-=head1 Installation
-
-The best short answer is:
-
-    git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
-    echo 'source /path/to/git-subrepo/.rc' >> ~/.bashrc
-
-The complete "Installation Instructions" can be found below.
-
-Note: git-subrepo needs a git version (> 2.7) that supports worktree:s.
-
-=head1 Commands
-
-All the B<subrepo> commands use names of actual Git commands and try to do
-operations that are similar to their Git counterparts. They also attempt to
-give similar output in an attempt to make the subrepo usage intuitive to
-experienced Git users.
-
-Please note that the commands are I<not> exact equivalents, and do not take
-all the same arguments. Keep reading…
-
-=over
-
-=item C<< git subrepo clone <repository> [<subdir>] [-b <branch>] [-f] [-m <msg>] [-e] [--method <merge|rebase>] >>
-
-Add a repository as a subrepo in a subdir of your repository.
-
-This is similar in feel to C<git clone>. You just specify the remote repo url,
-and optionally a sub-directory and/or branch name. The repo will be fetched
-and merged into the subdir.
-
-The subrepo history is I<squashed> into a single commit that contains the
-reference information. This information is also stored in a special file
-called C<< <subdir>/.gitrepo >>. The presence of this file indicates that the
-directory is a subrepo.
-
-All subsequent commands refer to the subrepo by the name of the
-I<subdir>. From the subdir, all the current information about the subrepo
-can be obtained.
-
-The C<--force> option will "reclone" (completely replace) an existing subdir.
-
-The C<--method> option will decide how the join process between branches are
-performed. The default option is merge.
-
-The C<clone> command accepts the C<--branch=> C<--edit>, C<--force> and C<--
-message=> options.
-
-=item C<< git subrepo init <subdir> [-r <remote>] [-b <branch>] [--method <merge|rebase>] >>
-
-Turn an existing subdirectory into a subrepo.
-
-If you want to expose a subdirectory of your project as a published subrepo,
-this command will do that. It will split out the content of a normal
-subdirectory into a branch and start tracking it as a subrepo. Afterwards your
-original repo will look exactly the same except that there will be a C<<
-<subdir>/.gitrepo >> file.
-
-If you specify the C<--remote> (and optionally the C<--branch>) option, the
-values will be added to the C<< <subdir>/.gitrepo >> file. The C<--remote>
-option is the upstream URL, and the C<--branch> option is the upstream branch
-to push to. These values will be needed to do a C<git subrepo push> command,
-but they can be provided later on the C<push> command (and saved to C<<
-<subdir>/.gitrepo >> if you also specify the C<--update> option).
-
-Note: You will need to create the empty upstream repo and push to it on your
-      own, using C<< git subrepo push <subdir> >>.
-
-The C<--method> option will decide how the join process between branches are
-performed. The default option is merge.
-
-The C<init> command accepts the C<--branch=> and C<--remote=> options.
-
-=item C<< git subrepo pull <subdir>|--all [-M|-R|-f] [-m <msg>] [-e] [-b <branch>] [-r <remote>] [-u] >>
-
-Update the subrepo subdir with the latest upstream changes.
-
-The C<pull> command fetches the latest content from the remote branch pointed
-to by the subrepo's C<.gitrepo> file, and then tries to merge the changes into
-the corresponding subdir. It does this by making a branch of the local commits
-to the subdir and then merging or rebasing (see below) it with the fetched
-upstream content. After the merge, the content of the new branch replaces your
-subdir, the C<.gitrepo> file is updated and a single 'pull' commit is added to
-your mainline history.
-
-The C<pull> command will attempt to do the following commands in one go:
-
-    git subrepo fetch <subdir>
-    git subrepo branch <subdir>
-    git merge/rebase subrepo/<subdir>/fetch subrepo/<subdir>
-    git subrepo commit <subdir>
-    # Only needed for a consequential push:
-    git update-ref refs/subrepo/<subdir>/pull subrepo/<subdir>
-
-In other words, you could do all the above commands yourself, for the same
-effect. If any of the commands fail, subrepo will stop and tell you to finish
-this by hand. Generally a failure would be in the merge or rebase part, where
-conflicts can happen. Since Git has lots of ways to resolve conflicts to your
-personal tastes, the subrepo command defers to letting you do this by hand.
-
-When pulling new data, the method selected in clone/init is used. This has no
-effect on the final result of the pull, since it becomes a single commit. But
-it does affect the resulting C<< subrepo/<subdir> >> branch, which is often
-used for a subrepo C<push> command. See 'push' below for more information. If
-you want to change the method you can use the C<config> command for this.
-
-When you pull you can assume a fast-forward strategy (default) or you can
-specify a C<--rebase>, C<--merge> or C<--force> strategy. The latter is the
-same as a C<clone --force> operation, using the current remote and branch.
-
-Like the C<clone> command, C<pull> will squash all the changes (since the last
-pull or clone) into one commit. This keeps your mainline history nice and
-clean. You can easily see the subrepo's history with the C<git log> command:
-
-    git log refs/subrepo/<subdir>/fetch
-
-The set of commands used above are described in detail below.
-
-The C<pull> command accepts the C<--all>, C<--branch=>, C<--edit>, C<--force>,
-C<--message=>, C<--remote=> and C<--update> options.
-
-=item C<< git subrepo push <subdir>|--all [<branch>] [-r <remote>] [-b <branch>] [-M|-R] [-u] [-f] [-s] [-N] >>
-
-Push a properly merged subrepo branch back upstream.
-
-This command takes the subrepo branch from a successful pull command and
-pushes the history back to its designated remote and branch. You can also use
-the C<branch> command and merge things yourself before pushing if you want to
-(although that is probably a rare use case).
-
-The C<push> command requires a branch that has been properly merged/rebased
-with the upstream HEAD (unless the upstream HEAD is empty, which is common
-when doing a first C<push> after an C<init>). That means the upstream HEAD is
-one of the commits in the branch.
-
-By default the branch ref C<< refs/subrepo/<subdir>/pull >> will be pushed,
-but you can specify a (properly merged) branch to push.
-
-After that, the C<push> command just checks that the branch contains the
-upstream HEAD and then pushes it upstream.
-
-The C<--force> option will do a force push. Force pushes are typically
-discouraged. Only use this option if you fully understand it. (The C<--force>
-option will NOT check for a proper merge. ANY branch will be force pushed!)
-
-The C<push> command accepts the C<--all>, C<--branch=>, C<--dry-run>, C<--
-force>, C<--merge>, C<--rebase>, C<--remote=>, C<--squash> and C<--
-update> options.
-
-=item C<< git subrepo fetch <subdir>|--all [-r <remote>] [-b <branch>] >>
-
-Fetch the remote/upstream content for a subrepo.
-
-It will create a Git reference called C<< subrepo/<subdir>/fetch >> that
-points at the same commit as C<FETCH_HEAD>. It will also create a remote
-called C<< subrepo/<subdir> >>. These are temporary and you can easily remove
-them with the subrepo C<clean> command.
-
-The C<fetch> command accepts the C<--all>, C<--branch=> and C<--
-remote=> options.
-
-=item C<< git subrepo branch <subdir>|--all [-f] [-F] >>
-
-Create a branch with local subrepo commits.
-
-Scan the history of the mainline for all the commits that affect the C<subdir>
-and create a new branch from them called C<< subrepo/<subdir> >>.
-
-This is useful for doing C<pull> and C<push> commands by hand.
-
-Use the C<--force> option to write over an existing C<< subrepo/<subdir>
->> branch.
-
-The C<branch> command accepts the C<--all>, C<--fetch> and C<--force> options.
-
-=item C<< git subrepo commit <subdir> [<subrepo-ref>] [-m <msg>] [-e] [-f] [-F] >>
-
-Add subrepo branch to current history as a single commit.
-
-This command is generally used after a hand-merge. You have done a C<subrepo
-branch> and merged (rebased) it with the upstream. This command takes the HEAD
-of that branch, puts its content into the subrepo subdir and adds a new commit
-for it to the top of your mainline history.
-
-This command requires that the upstream HEAD be in the C<< subrepo/<subdir> >>
-branch history. That way the same branch can push upstream. Use the C<--force>
-option to commit anyway.
-
-The C<commit> command accepts the C<--edit>, C<--fetch>, C<--force> and C<--
-message=> options.
-
-=item C<< git subrepo status [<subdir>|--all|--ALL] [-F] [-q|-v] >>
-
-Get the status of a subrepo. Uses the C<--all> option by default. If the C<--
-quiet> flag is used, just print the subrepo names, one per line.
-
-The C<--verbose> option will show all the recent local and upstream commits.
-
-Use C<--ALL> to show the subrepos of the subrepos (ie the
-"subsubrepos"), if any.
-
-The C<status> command accepts the C<--all>, C<--ALL>, C<--fetch>, C<--quiet>
-and C<--verbose> options.
-
-=item C<< git subrepo clean <subdir>|--all|--ALL [-f] >>
-
-Remove artifacts created by C<fetch> and C<branch> commands.
-
-The C<fetch> and C<branch> operations (and other commands that call them)
-create temporary things like refs, branches and remotes. This command removes
-all those things.
-
-Use C<--force> to remove refs. Refs are not removed by default because they
-are sometimes needed between commands.
-
-Use C<--all> to clean up after all the current subrepos. Sometimes you might
-change to a branch where a subrepo doesn't exist, and then C<--all> won't find
-it. Use C<--ALL> to remove any artifacts that were ever created by subrepo.
-
-To remove ALL subrepo artifacts:
-
-    git subrepo clean --ALL --force
-
-The C<clean> command accepts the C<--all>, C<--ALL>, and C<--force> options.
-
-=item C<< git subrepo config <subdir> <option> [<value>] [-f] >>
-
-Read or update configuration values in the subdir/.gitrepo file.
-
-Because most of the values stored in the .gitrepo file are generated you
-will need to use C<--force> if you want to change anything else then the
-C<method> option.
-
-Example to update the C<method> option for a subrepo:
-
-    git subrepo config foo method rebase
-
-=item C<< git subrepo help [<command>|--all] >>
-
-Same as C<git help subrepo>. Will launch the manpage. For the shorter usage,
-use C<git subrepo -h>.
-
-Use C<< git subrepo help <command> >> to get help for a specific command. Use
-C<--all> to get a summary of all commands.
-
-The C<help> command accepts the C<--all> option.
-
-=item C<git subrepo version [-q|-v]>
-
-This command will display version information about git-subrepo and its
-environment. For just the version number, use C<git subrepo --version>. Use
-C<--verbose> for more version info, and C<--quiet> for less.
-
-The C<version> command accepts the C<--quiet> and C<--verbose> options.
-
-=item C<git subrepo upgrade>
-
-Upgrade the C<git-subrepo> software itself. This simply does a C<git pull>
-on the git repository that the code is running from. It only works if you
-are on the C<master> branch. It won't work if you installed C<git-subrepo>
-using C<make install>; in that case you'll need to C<make install> from the
-latest code.
-
-=back
-
-=head1 Command Options
-
-=over
-
-=item C<-h>
-
-Show a brief view of the commands and options.
-
-=item C<--help>
-
-Gives an overview of the help options available for the subrepo command.
-
-=item C<--version>
-
-Print the git-subrepo version. Just the version number. Try the C<version>
-command for more version info.
-
-=item C<--all> (C<-a>)
-
-If you have multiple subrepos, issue the command to all of them (if
-applicable).
-
-=item C<--ALL> (C<-A>)
-
-If you have subrepos that also have subrepos themselves, issue the command to
-ALL of them. Note that the C<--ALL> option only works for a subset of the
-commands that C<--all> works for.
-
-=item C<< --branch=<branch-name> >> (C<< -b <branch-name> >>)
-
-Use a different upstream branch-name than the remote HEAD or the one saved in
-C<.gitrepo> locally.
-
-=item C<--dry-run> (C<-N>)
-
-For the push command, do everything up until the push and then print out the
-actual C<git push> command needed to finish the operation.
-
-=item C<--edit> (C<-e>)
-
-Edit the commit message before committing.
-
-=item C<--fetch> (C<-F>)
-
-Use this option to fetch the upstream commits, before running the command.
-
-=item C<--force> (C<-f>)
-
-Use this option to force certain commands that fail in the general case.
-
-NOTE: The C<--force> option means different things for different commands.
-      Read the command specific doc for the exact meaning.
-
-=item C<--merge> (C<-M>)
-
-Use a C<merge> strategy to include upstream subrepo commits on a pull (or
-setup for push).
-
-=item C<< --message=<message> >> (C<< -m <message> >>)
-
-Specify your own commit message on the command line.
-
-=item C<--rebase> (C<-R>)
-
-Use a C<rebase> strategy to include upstream subrepo commits on a pull (or
-setup for push).
-
-=item C<< --remote=<remote-url> >> (C<< -r <remote-url> >>)
-
-Use a different remote-url than the one saved in C<.gitrepo> locally.
-
-=item C<--squash> (C<-s>)
-
-Squash all commits on a push into one new commit.
-
-=item C<--update> (C<-u>)
-
-If C<--branch> or C<--remote> are used, and the command updates the
-C<.gitrepo> file, include these values to the update.
-
-=back
-
-=head1 Output Options
-
-=over
-
-=item C<--quiet> (C<-q>)
-
-Print as little info as possible. Applicable to most commands.
-
-=item C<--verbose> (C<-v>)
-
-Print more information about the command execution and results. Applicable to
-most commands.
-
-=item C<--debug> (C<-d>)
-
-Show the actual git (and other) commands being executed under the hood.
-Applicable to most commands.
-
-=item C<--DEBUG> (C<-x>)
-
-Use the Bash C<set -x> option which prints every command before it is
-run. VERY noisy, but extremely useful in deep debugging. Applicable to
-all commands.
-
-=back
-
-=head1 Environment Variables
-
-The C<git-subrepo> command exports and honors some environment variables:
-
-=over
-
-=item C<GIT_SUBREPO_ROOT>
-
-This is set by the C<.rc> file, if you use that method to install / enable C<git-
-subrepo>. It contains the path of the C<git-subrepo> repository.
-
-=item C<GIT_SUBREPO_RUNNING>
-
-This variable is exported when C<git-subrepo> is running. It is set to the pid
-of the C<git-subrepo> process that is running. Other processes, like git hooks
-for instance, can use this information to adjust accordingly.
-
-=item C<GIT_SUBREPO_COMMAND>
-
-This variable is exported when C<git-subrepo> is running. It is set to the
-name of the C<git-subrepo> subcommand that is running.
-
-=item C<GIT_SUBREPO_PAGER>
-
-Use this to specify the pager to use for long output commands. Defaults to
-C<$PAGER> or C<less>.
-
-=item C<GIT_SUBREPO_QUIET>
-
-Set this for quiet (C<-q>) output.
-
-=item C<GIT_SUBREPO_VERBOSE>
-
-Set this for verbose (C<-v>) output.
-
-=item C<GIT_SUBREPO_DEBUG>
-
-Set this for debugging (C<-d>) output.
-
-=back
-
-=head1 Installation Instructions
-
-There are currently 3 ways to install C<git-subrepo>. For all of them you need
-to get the source code from GitHub:
-
-    git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
-
-The first installation method is preferred: C<source> the C<.rc> file. Just
-add a line like this one to your shell startup script:
-
-    source /path/to/git-subrepo/.rc
-
-That will modify your C<PATH> and C<MANPATH>, and also enable command
-completion.
-
-The second method is to do these things by hand. This might afford you more
-control of your shell environment. Simply add the C<lib> and C<man>
-directories to your C<PATH> and C<MANPATH>:
-
-    export GIT_SUBREPO_ROOT="/path/to/git-subrepo"
-    export PATH="/path/to/git-subrepo/lib:$PATH"
-    export MANPATH="/path/to/git-subrepo/man:$MANPATH"
-
-See below for info on how to turn on Command Completion.
-
-The third method is a standard system install, which puts C<git-subrepo> next
-to your other git commands:
-
-    make install        # Possibly with 'sudo'
-
-This method does not account for upgrading and command completion yet.
-
-=head2 Windows
-
-This command is known to work in these Windows environments:
-
-=over
-
-=item * Git for Windows -- L<https://git-for-windows.github.io/>
-
-=item * Babun -- L<http://babun.github.io/>
-
-=item * Cygwin -- L<https://www.cygwin.com/>
-
-=back
-
-Let us know if there are others that it works (or doesn't work) in.
-
-=head1 Testing
-
-The C<git-subrepo> repository comes with a extensive test suite. You can
-run it with:
-
-    make test
-
-or if you don't have C<make> on your system:
-
-    prove -v test
-
-=head1 Upgrading
-
-If you used the C<.rc> or C<PATH> method of installation, just run this to
-upgrade C<git-subrepo>:
-
-    git subrepo upgrade
-
-Or (same thing):
-
-    cd /path/to/git-subrepo
-    git pull
-
-If you used C<make install> method, then run this again (after C<git pull>):
-
-    make install        # Possibly with 'sudo'
-
-=head1 Command Completion
-
-The C<git subrepo> command supports C<< <TAB> >>-based command completion. If
-you don't use the C<.rc> script (see Installation, above), you'll need to
-enable this manually to use it.
-
-=head2 In Bash
-
-If your Bash setup does not already provide command completion for Git, you'll
-need to enable that first:
-
-    source <Git completion script>
-
-On your system, the Git completion script might be found at any of the
-following locations (or somewhere else that we don't know about):
-
-=over
-
-=item * C</etc/bash_completion.d/git>
-
-=item * C</usr/share/bash-completion/git>
-
-=item * C</usr/share/bash-completion/completions/git>
-
-=item * C</opt/local/share/bash-completion/completions/git>
-
-=item * C</usr/local/etc/bash_completion.d/git>
-
-=item * C<~/.homebrew/etc/bash_completion.d/git>
-
-=back
-
-In case you can't find any of these, this repository contains a copy of the
-Git completion script:
-
-    source /path/to/git-subrepo/share/git-completion.bash
-
-Once Git completion is enabled (whether you needed to do that manually or
-not), you can turn on C<git-subrepo> completion with a command like this:
-
-    source /path/to/git-subrepo/share/completion.bash
-
-=head2 In zsh
-
-In the Z shell (zsh), you can manually enable C<git-subrepo> completion by
-adding the following line to your C<~/.zshrc>, B<before> the C<compinit>
-function is called:
-
-    fpath=('/path/to/git-subrepo/share/zsh-completion' $fpath)
-
-=head1 Status
-
-The git-subrepo command has been in use for well over a year and seems to get
-the job done. Development is still ongoing but mostly just for fixing bugs.
-
-Trying subrepo out is simple and painless (this is not C<git submodule>).
-Nothing is permanent (if you do not push to shared remotes). ie You can always
-play around and reset back to the beginning without pain.
-
-This command has a test suite (run C<make test>), but surely has many bugs. If
-you have expertise with Git and subcommands, please review the code, and file
-issues on anything that seems wrong.
-
-If you want to chat about the C<git-subrepo> command, join C<#gitcommands> on
-C<irc.freenode.net>.
-
-=head1 Notes
-
-=over
-
-=item * Works on POSIX systems: Linux, BSD, OSX, etc.
-
-=item * Works on various Windows environments. See "Windows" section above.
-
-=item * The C<git-subrepo> repo itself has 2 subrepos under the C<ext/> subdirectory.
-
-=item * Written in (very modern) Bash, with full test suite. Take a look.
-
-=item * A C<.gitrepo> file never is in the top level dir (next to a C<.git/> dir).
-
-=back
-
-=head1 Authors
-
-=over
-
-=item * Ingy döt Net <ingy@ingy.net>
-
-=item * Magnus Carlsson <grimmymail@gmail.com>
-
-=back
-
-=head1 License and Copyright
-
-The MIT License (MIT)
-
-Copyright (c) 2013-2020 Ingy döt Net
-
-=cut