Metadata-Version: 2.1
Name: git-pile
Version: 0.96
Summary: Manage a pile of patches on top of git branches
Home-page: https://github.com/git-pile/git-pile
Maintainer: git-pile contributors
Maintainer-email: lucas.demarchi@intel.com
License: LGPLv2+
Description: # git-pile
        Manage a pile of patches on top of a git branch
        
        <p align="center">
          <img src="/docs/git-pile-cycle.svg" />
        </p>
        
        ## Requirements
        
         - Python >= 3.6
         - git >= 2.19
         - Python modules:
           - argcomplete (optional)
        
        ## Quickstart
        
        ### Running git-pile
        
        git-pile follows the git naming convention for binaries so we can use it as a
        subcommand to git. Either of the following forms work if the git-pile is in the
        search PATH:
        
        ```bash
        $ git pile -h
        $ git-pile -h
        ```
        
        For autocomplete to work you need Python's argcomplete module installed.
        In the first case you also need to source the bash autocomplete file
        `extra/git-pile-complete.sh` so git knows how to complete the subcommand.
        
        You can also install git-pile as a python package, although that's still not
        recommended since it's being updated frequently.
        
        ```bash
        $ ./setup.py install
        ```
        
        OR
        
        ```bash
        $ ./setup.py install --user
        ```
        
        In case a `--user` option is provided to the command above it will install
        under `$HOME` directory and bash completion file will be at
        `$XDG_DATA_HOME/git-pile/bash_completion`.  There isn't a standard user
        directory for bash completion we can install to, so the user is expected to
        source this file.
        
        ### Repository initialization
        
        Initialize a new **empty** pile:
        
        ```bash
        $ git pile init
        ```
        
        Now you have a (orphan) pile branch to keep track of patch files to be managed
        on top of the master branch. Branch names may be changed via options to
        `git pile init`. Like `git init` creates a new repository, `git pile init` will
        create a new pile.
        
        Alternatively, if the pile branch already exists in a remote repository (or
        even locally) and you want to setup your work tree to use it you should use
        the command below:
        
        ```bash
        $ git pile setup internal/pile internal/embargo-branch
        ```
        
        In the example above we have a remote called `internal` which has a branch
        named `pile` that contains the patch files and a branch named `embargo-branch`
        that will be the branch being generated when we apply the patches.
        
        The second argument is optional and if not given the current branch will be
        used.
        
        ### Develop a new commit and send to mailing list
        
        You can use your normal git flow to develop changes in the project and create
        commits. Here is an example that is by no means restricted to git-pile:
        
        ```bash
        $ git checkout -b newfeature internal/embargo-branch
        $ echo "platform 16" >> platforms.txt
        $ git add platforms.txt
        $ git commit "add new platform"
        ```
        
        Continuing from the initialization example, we create a new branch with
        `internal/embargo-branch` as the base. The result can be prepared to send to a
        mailing list in the same vein as how `git format-patch` works:
        
        ```bash
        $ git pile format-patch -o /tmp/patches
        /tmp/patches/0000-cover-letter.patch
        /tmp/patches/0001-add-new-platform.patch
        ```
        
        The cover letter will contain the diff to the pile branch (with patches added
        and so on), while the patch files will also be available in isolation: those
        are diffs to the result branch, and present to ease review.
        
        If the commit you are adding should not be on top, but rather in the middle
        of the long running patch series, you can just move it down in the tree
        with `git rebase -i`. In the example below we will move it 10 commits down:
        
        ```bash
        $ git rebase -i -11
        
          [ editor opens and you move the commit around. You can also reorder
            commits, edit commit message, etc, etc. Anything you do in a
            interactive rebase you can do here ]
        
        $ git pile format-patch -o /tmp/patches
        /tmp/patches/0000-cover-letter.patch
        /tmp/patches/0001-old-platform.patch
        /tmp/patches/0002-old-platform-2.patch
        /tmp/patches/0003-add-new-platform.patch
        ```
        
        Any patch that needs to be changed in order to accommodate the patch in the
        middle of the series will be prepared by `git pile format-patch`.
        
        ### Generate the pile from the changed tree
        
        Instead of sending to the mailing list, you can simply transform
        the changes from the branch to the physical patches maintained
        in the pile branch.
        
        ```bash
        $ git pile genpatches master..newfeature
        $ cd patches
        $ git add -A
        $ git commit -m "add platform"
        $ git pile genbranch
        ```
        
        This generates the patches, saving the final state in the patch series, and
        then recreates `embargo-branch` locally. Patches may be reordered, added in the
        middle, reworded etc. By going through the genpatches + genbranch cycle we can
        always re-generate the branch and keep the history of what was done, i.e.
        maintain the history of how the patches were changed/added/removed.
        
        ### Apply a patch series to the pile
        
        The cover-letter in a git-pile generated patch series (i.e. the one generated
        by `git pile format-patch`) always contain the diff of the original state of the
        tree to the current state. It may be used to apply the entire series by
        targeting the patches directory instead of the normal working directory.
        
        ```bash
        $ # machine 2
        $ cd pile
        $ git am /tmp/patches/0000-cover-letter.patch
        $ git genbranch
        ```
        
        This will apply the entire series that was received (even if it was a 10 patches
        series, only the specially-formatted cover-letter needs to be applied).
        
        ### Destroying the pile
        
        If anything goes wrong and you'd like to start over, you can call the `destroy`
        command. This will remove all configuration saved by git-pile, the pile branch
        itself and the worktree directory it was using. If you have a backup of the
        patches (either manual or if the pile branch is in a remote repository), this
        is pretty safe to do and allow you to redo the configuration.
        
Platform: any
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Requires-Python: >=3.6
Description-Content-Type: text/markdown
