# How to contribute code to MCCE

## MCCE Development Through Github

### Part 1. One-time set up

On your workstation / coding computers, set up the git environment.

#### Identity:

```
$ git config --global user.name "<Your Name>"  
$ git config --global user.email <your email>
```

#### Save credential for 6 hours:

```
$ git config --global credential.helper 'cache --timeout=21600'
```

#### Save credential permanently:

```
$ git config --global credential.helper store
```

#### Alias of showing git history:

Add this to ~/.gitconfig

```
[alias]
lg = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all
```

#### Github access token

Github adopts personal access token to replace password authentication. In short, you need to use a personal access token as password to push commits to github. See documentation [https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)

Be aware, once the token is created, you will not be able to see the token content any more. So save the token in a safe place. If you have successully pushed a commit to github and used above method to save credential permenently, the token is stored in ~/.git-credentials.

### Part 2. Work with your own fork of MCCE project

MCCE project at [https://github.com/GunnerLab/Stable-MCCE](https://github.com/GunnerLab/Stable-MCCE) hosts the current stable code of MCCE. If you need to edit or add code, the recommended work flow is like this:

1. Log in github and go to [https://github.com/GunnerLab/Stable-MCCE](https://github.com/GunnerLab/Stable-MCCE), create a fork the repository so you have your own Stable-MCCE repository. This is a one-time set up.
2. All the local code developing should be performed in a develope branch and pushed to the forked Stable-MCCE repo on github.
3. Once the code is done and tested, create a pull request from the forked Stable-MCCE repo on github.
4. After receiving confirmation that your pull request had been merged to the master repo, you can pull from the master repo to update your code and safely delete the develope branches.

### Part 3. Examples of Git commands

#### Clone a remote repo:

Clone a remote repo to local computer:

`git clone <url>`

#### Convert a local directory:

Convert an existing local directory to local git repository:

`git init`

#### Add all files to track:

`git add .`

#### Add a single file to track:

`git add <file name>`

#### Check status:

<div class="highlight" id="bkmrk-git-status">`git status`</div>#### Commit:

`git commit -a -m "<commit message>"`

#### Show commit history:

`git lg`

<div class="highlight" id="bkmrk-it-requires-you-set-"><span style="color: rgb(224, 62, 45);">*[It requires you set up the “lg” alias in ~/.gitconfig](https://gunnerlab.github.io/Stable-MCCE/develop/#alias-of-showing-git-history)*</span></div>### Part 4. More on git branches

#### Create a new branch and revert to a past commit:

`git checkout -b <new branch> <commit hash>`

&lt;new branch&gt; is a branch name you make.

&lt;commit hash&gt; is the string as reported by `git log`

If you want to make this branch as the new master branch, do a swap as following:

1. make sure your are in the new branch
    
    ```
    $ git checkout <new branch>
    ```
2. force master to merge with current branch and use current branch as favored:
    
    ```
    $ git merge -s ours master
    ```
3. go to the master branch and reconcile again:
    
    ```
    $ git checkout master
    $ git merge <new branch>
    ```
4. after merge, delete the branch.
    
    ```
    $ git branch -d <new branch>
    ```

#### Show branches:

`git branch`

#### Show remote branches:

`git branch -r`

#### Switch between branches:

`git checkout <branch name>`

#### Create and switch branch:

`git checkout -b <branch name>`

#### Merge branches:

`git merge <another branch>`

<div class="highlight" id="bkmrk-this-will-merge-a-br">This will merge a branch to current branch:</div>#### Merge with current favored:

`git merge -s ours <another branch>`

#### Delete branches:

`git branch -d <branch name>`

#### Force delete:

`git branch -D <branch name>`

### Part 5. Sync remote and local repository

#### Check remote repo:

`git remote -v`

<div class="highlight" id="bkmrk-%E2%80%9Corigin%E2%80%9D-is-the-defa">“origin” is the default name of your first remote.</div>#### Add more remotes:

`git remote add <remote> <url>`

<div class="highlight" id="bkmrk-"></div>#### Pull from remote repo:

`git pull`

Or

`git pull <remote> <branch>`

#### Push to remote:

`git push`

#### Push new local branch to remote:

`git push -u <remote> <branch>`

#### Delete remote branch:

`git push <remote> --delete <branch>`

#### Delete remote tracking branch:

`git remote prune <remote>`

Often used on remote repo origin:

`git remote prune origin`

This command is useful to clean up the remote repository.

### Part 6. Merge branches

#### Common scenario of merge:

- Start a new feature:
    
    ```
    $ git checkout -b new-feature
    ```
- Edit some files, then commit the change:
    
    ```
    $ git commit -a -m "Start a feature"  
    ```
- Edit some files, then commit more changes:
    
    ```
    $ git commit -a -m "Finish a feature"  
    ```
- Merge in the new-feature branch:
    
    ```
    $ git checkout master 
    $ git merge new-feature 
    $ git branch -d new-feature
    ```

#### Conflict in merge:

When conflicts occur, the conflicting files will have visual marks like:

```
<<<<<<< master
conflicting text in receiving branch
=======
conflicting text in merging branch
>>>>>>> branch
```

You need to edit text and remove &lt;&lt;&lt;&lt;&lt;&lt;, ======, &gt;&gt;&gt;&gt;&gt;&gt; lines.

Then run a commit:

```
<button class="md-clipboard md-icon" data-clipboard-target="#__code_37 > code" style="box-sizing: inherit; -webkit-tap-highlight-color: transparent; margin: 0px; padding: 0px; font-size: inherit; background: transparent; border: 0px; position: absolute; top: 0.5em; right: 0.5em; z-index: 1; width: 1.5em; height: 1.5em; color: var(--md-default-fg-color--lightest); border-radius: 0.1rem; cursor: pointer; transition: color 250ms ease 0s;" title="Copy to clipboard"></button>```
$ git commit -a -m "<commit message>"
```
```