Metadata-Version: 2.1
Name: marche
Version: 0.1.2
Summary: MaRChE
Home-page: https://github.com/OpenCode/marche
Author: Francesco Apruzzese
Author-email: cescoap@gmail.com
License: GPLv3
Description: MaRChE
        ======
        
        **MA**ssive **R**epository **CH**anges for **E**veryone
        -------------------------------------------------------
        
        [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
        
        MaRChE is an addons based software created to apply recursive changes on a lot of repositories with only one (reusable) script and one (reusable) configuration file.
        
        # Installation
        
        ## From source
        
        Use virtualenv to separate MaRChE environment from system one.
        
        ```
        $ git clone git@github.com:openforceit/marche.git
        $ cd marche
        $ virtualenv -p python3 venv
        $ source venv/bin/activate
        (venv)$ python3 -m pip install -r requirements.txt
        ```
        
        ## From pypi
        
        ```
        $ pip3 install marche
        ```
        
        # Usage
        
        ## Get scripts list
        
        ```
        $ cd YOUR_ADDONS_PATH
        $ marche available-scripts
        ```
        
        A list of scripts (folders in `scripts` path) will be showed.
        
        Every folder is callable as a script.
        
        ## Call script
        
        ```
        (venv)$ python3 marche.py script
            -t TOKEN
            [--bar/--no-bar]
            [--collect-pr/--no-collect-pr]
            SCRIPT_NAME
            [--] [<script_options>]
        ```
        
        `SCRIPT_NAME` is the script name that user can get from `available-scripts`
        
        `TOKEN` is a Github developer token that can be generated here: https://github.com/settings/tokens.
        
        `--bar/--no-bar` Show or hide progress bar. Default value show the bar.
        
        `--collect-pr/--no-collect-pr` Show or hide all the Pull Requests created by MaRChE. Default value show the collected pr.
        
        `script_options` is a list of POSIX-style, whitespace-separated arguments that are passed to the script. These arguments may or may not be required depending on the script itself. Check the script documentation for more details.
        
        # How to dev an addon
        
        MaRChE addons must be created in `scripts` path.
        
        A MaRChE addons is composed by 2 mandatory files and 1 folder (not mandatory):
        
        ```
        addon_name
        | - marche.py
        | - marche.yaml
        | - resources
        ```
        
        ## Resources
        
        Is the folder where MaRChE search for all external files. If you need to read a txt file or an image, put them in this folder and use `read_local_file` function of `repo`.
        
        ## Marche.yaml
        
        It's a YAML file. Every marche.yaml must contains keys called version and repo. Others keys are not required.
        
        ### **`version`** [required]
        
        Version of marche.yaml structure. It's used for retrocompatibility.
        
        ### **`repo`** [required]
        
        List of repositories information:
        
        #### **`name`**
        
        The repo name composed by *ORGANIZATION/REPO_NAME*
        
        #### **`source_branch`**
        
        The branch used as source
        
        #### **`target_branch`**
        
        The branch used as target. If it doesn't exist, will be created.
        
        ### **`comments`**
        
        Comments relative to script
        
        ## Marche.py
        
        It's a python script. Every marche.py must contains a function called `marche`.
        
        ```
        def marche(repo, *args, **kwargs):
            ....
        ```
        
        `repo` is a required argument used to access to repo object.
        
        ### Repo object
        
        #### **Attributes**
        
        ##### **`repo`**
        
        Reference to repo object from Github module (https://pygithub.readthedocs.io/en/latest/github_objects/Repository.html).
        
        All the methods available for this object can be found here: https://pygithub.readthedocs.io/en/latest/index.html
        
        ##### **`name`**
        
        Repository name get from configuration file.
        
        ##### **`source_branch`**
        
        Name of the branch used as base to generate PR.
        
        ##### **`target_branch`**
        
        Name of the branch used as target to generate PR. If it doens't exist, will be created.
        
        ##### **`collect_pr`**
        
        Property to manage a collection of new pull requests of every repo
        
        #### **Functions**
        
        ##### **`branch_exists(name)`**
        
        Return branch object, relative to branch name, if it exists or return False.
        
        ```
            if repo.branch_exists('test'):
                print('Test is here!')
            else:
                print('Create test branch')
        ```
        
        ##### **`create_file(file_name, file_content, commit_message)`**
        
        Create a new file on target branch. A new commit will be generated.
        Return a commit object.
        
        ```
            commit = repo.create_file(
                'marche.txt', 'Sample file', '[ADD] Marche txt')
            print(commit)
        ```
        
        ##### **`update_file(file_name, file_content, commit_message)`**
        
        Update an existing file on target branch. A new commit will be generated.
        Return a commit object.
        
        ```
            commit = repo.update_file(
                'marche.txt', 'Sample file with MaRChE', '[ADD] Marche txt')
            print(commit)
        ```
        
        ##### **`delete_file(file_name, commit_message)`**
        
        Delete an existing file on target branch. A new commit will be generated.
        Return a commit object.
        
        ```
            commit = repo.delete_file(
                'marche.txt', '[REM] Marche txt')
            print(commit)
        ```
        
        ##### **`read_file(file_name)`**
        
        Read an existing file content from source branch. Return a bytes object.
        
        ```
            content = repo.read_file('.gitignore')
            print(content)
            print(content.replace(b'DS_Store', b'XXXXXXXXXXXX'))
        ```
        
        ##### **`read_local_file(file_name)`**
        
        Read an existing file content from `resources` local path. Return a bytes object.
        
        ```
            content = repo.read_local_file('gitignore_template')
            print(content)
        ```
        
        ##### **`create_pr(title, body, reviewers)`**
        
        Create a new PR from target branch to source branch. Return a pr object. `reviewers` is an optional list of github handles to add as reviewers of the PR.
        
        ```
            pr = repo.create_pr('Test PR', 'MaRChE Rulez!')
            print(pr)
        ```
        
        ##### **`collected_pr()`**
        
        Show list of new pull requests created by MaRChE
        
        ```
            pr = repo.create_pr('Test PR', 'MaRChE Rulez!')
            print(repo.collected_pr())
        ```
        
        ##### **`log_info(message)`**
        
        Show an info message on log default system
        
        ```
            repo.log_info('Hello World!')
        ```
        
        ##### **`log_warning(message)`**
        
        Show a warning message (red text) on log default system
        
        ```
            repo.log_warning('OPS: Server is on fire!')
        ```
        
        ##### **`log_debug(message)`**
        
        Show a debug message (orange text) on log default system
        
        ```
            repo.log_debug('This is the bug!')
        ```
        
        ##### **`log_ok(message)`**
        
        Show a success message (green text) on log default system
        
        ```
            repo.log_ok('MaRChE is cool!')
        ```
        
        # Support
        
        <a href="https://www.buymeacoffee.com/scapigliato" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/arial-black.png" alt="Buy Me A Coffee" style="height: 51px !important;width: 217px !important;" ></a>
        
Keywords: github massive repository branch git vcs
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
