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
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
Requires-Dist: click (>=7.1.2)
Requires-Dist: pyyaml (>=5.3.1)
Requires-Dist: PyGithub (>=1.53)

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>


