eac_tools 0.86.1 → 0.86.3

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

@@ -0,0 +1,698 @@
+=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