Newbie - Handling with git - app.update - app.contribute

Hello Guys,
this is my first project with git - and I am struggling to use it right.

what I understand is…

pull (app.update) works this way superalgos/superalgos → mARTin-B78/superalgos → local machine

push (app.contribute) works this way local machine → mARTin-B78/superalgos → superalgos/superalgos

superalgos/superalgos is the main project

from there you make a fork to your own git account (mARTin-B78/superalgos)

you install superalgos using your own fork and set the upstream to the main project.
git remote add upstream https:/ /

now you pull the upstream which shall set your fork in sync with the main project
git fetch upstream

when you run superalgos you type in
app.update in the Docs Search and Command line to keep it all sync.

and when you are done editing you push with the command app.contribute
which should send the edits from your local machine to your git fork (mARTin-B78/superalgos)
that is then pushed to the main project (superalgos/superalgos)


but then… I have everything in sync (app.update → “The update process run successfully but no changes were made since your installation is up-to-date with the current branch. No further action required.” )
still when I run app.contribute I get the Error

I did
git checkout develop
git reset --hard upstream/develop
git push origin develop --force
that solves the issue but then I loose all the Translations I did before…

1 Like

You are definitely on the right path! Here is a rough guide for understanding Git and how to approach working with it. Let me know what still doesn’t make sense and we will get this refined so we can roll it into the docs and maybe even put a medium article out.

Wrangling Git and GitHub in Superalgos

Too help keep everything straight it is important to know that you basically have three separate git repositories you are working with.

The first two live on

    1. The first is the main repository. i.e. Superalgos/Superalgos
    1. The second is your fork i.e. YOURUSERNAME/Superalgos

The third is the local instance of your repository on you actual computer.

    1. Local repostory

Note: Any additional instances of Superalgos you have installed will all have their own local git repository. The reason for so many copies of the git repository is to help make sure the code base is preserved even if one particular repository is lost, deleted, corrupted, or otherwise compromised.

Let’s walk through the basic flow of how a change you make in your local instance of Superalgos makes it all the way to the main repository.

Lets say you make a change to a file called CoolThings.json. You hit save. And now your local git repository springs into action. It records the changes you made and stores it within the local repository.

Note: this happens for every single file that gets modified in any way. Unless it is specifically declared in a special file called .gitignore.

Now that you have your changes saved locally you really want to submit it to the main repository. So you type in app.contribute and away we go. Under the hood, however, app.contribute is helping to abstract away some of the details of how your local changes get transmitted.

Let’s break the steps down so we can get a better idea of what can go wrong in this process. The first step app.contribute completes for you is to create what is called a commit. A commit is basically a collection of your local changes that is being packaged to be sent to your repository saved on github (this is this your forked repository).

Once the commit is created it is then pushed to your remote repository. After being pushed your local git repository and remote forked repository now have the same changes.

Important: app.contribute will collect all your local changes and mush them into one commit. This means you need to be very careful to work on one thing at a time. If you make a change to your profile and then changes to other files and hit app.contribute. it will all get sent at once. There are ways around this limitation if you want to use a more sophisticated interface with git (such as dealing with git directly in VS Code) but that is well beyond the needs of most contributors.

Note: Keeping your local and remote repositories synced is very important and is a place where git can go off track. You will usually be warned if you need to first “pull” any new changes from your fork before you can “push” your local changes up to your fork.

Once your local and remote repositories are in sync and both have your new changes. Then app.contribute does one final thing. It creates a pull request from your fork and places it at the main Superalgos repository.

Pull requests are therefore the mechanism to submit changes from your personal repositories over to the main public repository. Once the PR is created app.contribute has done its job and is finished.

Now the final steps of getting your changes synced with the main repository begin.

    1. The first is getting your changes reviewed by the appropriate code owner. This is to make sure your changes do not have any unintended changes and that there are no errors or other things that might cause problems for the main repository.
    1. The second is to have the PR officially merged into the main repository.

Once these steps are complete, all three repositories finally contain your new changes.

app.update works in a similar manner. It takes all the new changes that have been added to the main Superalgos repository and merges them into your remote fork. After that it pulls these changes from you fork down to you local repository.

If something happens between getting all three repositories in sync that is where you will see errors begin to pop up. The first thing to figure out when this happens is to determine which of the three are having issues getting in sync with each other.

So for example, the error in the above post is an example of the local and remote fork repositories getting out of sync. In order to fix that particulate issue, you need to first pull new changes down from the fork before you can push new changes up. This would require running the git pull command which can be achieved through an IDE like VS Code or directly on the command line.

1 Like

Thank you for the well written and easy to understand explanation. I am learning so much about git now.

Can the process of keeping superalgos/superalgos with my own fork mARTin-B78/superalgos in sync be automated?

I am trying it with a shell script that runs before superalgos starts

git remote add upstream
git fetch upstream
git checkout develop
git rebase upstream/develop
node platform minMemo noBrowser

Also I have several local copies of Superalgos - I guess that mite causes the issue.
One “master” is for learning the Superalgos System itself (Algotrading), one “develop” is for contributing translations and one is for the governance project
guess thats too much

In my workflow I prefer to use VisualStudio and Github to handle the commits and fork syncing problems.

From Github I can sync my fork with the main project and with VisualStudio I can control my commits and sync my fork with my local copy on my PC. Then I can make a PR to the main project.

Anyway, what you must have in mind is this words:


So we have:

Now it’s just a matter of keeping in sync these 3 distinct copies.

If you work on you PC you are modifying your LOCAL copy.
Then you push to ORIGIN (your fork)
Then you open a PR from your fork to incorporate the changes in Superalgos/Superalgos (Upstream)

Then we have some cool commands in CLI.

One of the best is this command that will reset your fork on Github and sync it with the upstream in case you mess up things on github/fork/local copy ecc …

git reset --hard upstream/develop (or master depending on the branch)

Be careful, it will reset all your work to match the upstream.

In git hub you can easily stay in sync using this command, seescreenshot below

yeah I Fetched and merged…
but I do not know how to solve this

I would like to “automate” the process
something like this here

It looks like you have 18 commits that should be merged in Superalgos.
To do so, click Contribute and then click Open Pull Request.

Thanks you are right

One thing that I try is to keep the update and contributions automatically in sync.

GITHUB-Superalgos/Superalgos <—> GITHUB-mARTin-B78/Superalgos <—> LOCAL-Superalgos

some kind of if this then that else that linux command in an sh shell file.
something like this here but have not managed to get it working yet.

Hi all,
i am new to github and i have the below problem if someone could help.

I try to keep a simple routine to avoid mistakes which is the below:

I open superalgos , run the app.update , translate some pages and run the and app.contribute commands.

Today when i run the app.update i had this error:

[ERROR] Error updating develop
Error: From
 * branch                develop    -> FETCH_HEAD
error: Your local changes to the following files would be overwritten by merge:
Please commit your changes or stash them before you merge.

Can someone assist with this please? What seems to me relevant is here but i do not know which one to do and how to do it.

Thank you for your time reading this.


Hi Nik.
You have done some changes to your Local copy on your PC.
Now Github is telling you that you can’t update SA because you will loose your changes.

So you have 2 options:

  1. You commit your changes to SA by doing a PR or app.contribute in the app and then wait for your changes to be merged;
  2. You delete your local changes so SA can be updated correctly

It depends on what you want to achieve

I’m not sure about what you would like to accomplish.
Do you want to have a cron job then that periodically checks for changes?
Or just a file to manually lauch?
In this case the simplier way is to use Github + VScode

Thank you for your answer.
I will do an app.contribute then and see how it goes.

After the app.contribute may i continue translating or should i wait for the merge?
And how i would know the merge has been done?

Sorry 4 my noobish questions btw.


You must wait for the contribution to be merged!
Otherwise you will encounter a lot of issues

Ask whatever you need, we are all here to learn :+1:

I did an app.contribute and got an error : App Error - Github Credentials Missing
I had this error before and i went on and made my credentials with info i found from github and was resoved. So, why is this happening again?

You did not store you credentials/token so now SA don’t know what to do.

You can try to solve this by manually pushing your changes via terminal.
Contributing to projects - GitHub Docs

Or if you want to stay in SA just do again the tutorial about setting up your github credentials.

1 Like

I have stored my credentials using the Add Github API previously.
Yet the app.contribute is giving me the error of missing Credentials.
I tried to create another token but the Add Github Api does not react when i click on it.

As mate 9808us suggested me above, i tried to push my changes manually through github desktop app.
It seems that i managed to do it. Now i will wait to see if they will be merged (before i proceed translating more stuff).
Yet, evenif this way succeeds , how can i resolve the problem to add.contribute from within the Superalgos UI ?

Try to do again the tutorial about setting up Github.

Paste this in SA
docs.goto Foundations->Topic->App Error - Github Credentials Missing

1 Like

Hi, could you tell me a good way to work efficiently with github and visual Studio?
I have installed Github desktop after the commands in the terminal were so confusing.
I suppose it is much easier to handle with VS??

After you have cloned your fork to your PC with git clone
add Superalgos folder to VScode.
The first time you git clone SA usually you are under master branch.
Use SA to switch branch to develop so you can contribute.
In VScode you can check if you are on the correct branch:

As you can see above I’m under develop and in sync with my fork.

Now if I go to github under my fork develop branch I can see my fork is behind Superalgos:develop

So I click Fetch Upstrem → Fetch and merge
Now my fork in github is in synck with the upstream:

Now go to VScode under Source control:

See it? Click on that number (that is the same I had on github telling my fork was behind XX commits!)

VScode will download the commits and sync your LOCAL copy.

That’s it!

Now if you make changes to your local copy (on your PC) VScode will know it, you will see the list of files with changes ecc.

The process now is the same but in reverse order.

From VScode Source Control now I can commit my changes to my fork in github.
Once commited to my fork, I go to github and I will see that there are changes to push to SA.

I click on Contribute and then Open Pull Request

(In the screenshot above I don’t have anything to push, it’s just to show you where to look)

It’s really easy to control your fork on github and your local copy on your pc.

My advice is to do some practice.

Create your own project.
Create some branches under it.
Then play with VScode and your won fork.
You will learn a lot about forks/branches/PR ecc… without the fear of messing things up.

If you have never done the welcome tutorial about forks in github then do it!
Create your own project in github and play a bit with branches/forks, everyting will be more clear.

Here is the link to Hello World in github:
Hello World - GitHub Docs

that is superhelpful, thank you very much! Lets see if I can upload my Profile once again.