Howto/pages/04.Contribute/01.howto/01.git/2.working/docs.en.md

title	published	visible	updated	taxonomy	page-toc
Working with Git	true	true	last_modified app app_version October 2021 Git 2.33.0	category tags docs contribute git	active true

Starting to work

Now you can start Atom.

Go to the File tab, select Open Folder and choose the directory you've just cloned (howto).

The interface of Atom is clean and easy to understand. The left sidebar is your project's navigation tree, the middle window is where you edit files and bottom bar indicates number of changed files, current branch, quick pull/push to git.

You can open and work on multiple files in tabs or as split screen side by side. Unsaved files with local modifications are marked with a blue dot (depending on the theme you use of course). To save the file changes use the File menu or the Ctrl+s keyboard shortcut.

Before you start working on the files, you'll need to create your own branch.

Creating branches

Branches are basically your own private workspaces.

Each git project has it's own master branch. Master branch is the main, production copy of the project. This branch is automatically synced with the website, so any change made to that branch are instantly visible on the website. That is also why adding any changes to the master branch is restricted only to the owners of the project.

In order to start working, create your own branch. This will basically make a clone of the master branch.

On the bottom-right corner of Atom, click on master (or any other branch name) and choose New Branch. Choose a name for your branch, something easy for other to know what you're working on, what your branch is about. For example if your planning to work on a nextcloud howto, call it "nextcloud_howto" or something similar.

Press Enter on your keybord when you're done.

Now, you need to publish your new branch so that it is created on the server. Atom will ask your credential. Use the one created for our git instance.

Switching between branches can also be done from that menu. Current working branch is visible on the bottom bar. Click on it: other local branches will appear.

Once the branch is created and published, and you have change the current work on this new branch, you can create new files, modify existing ones, etc.

Committing changes

Now you're working on your computer creating new tutorials or translating existing ones. Apart from saving changes to your laptop, you can/should also commit your changes.

Committing changes syncs the work you've done on your branch to the git server. So a commit is a set of files created or modified. If the branch doesn't exist on repository, it will be created and all your modifications and new files will be uploaded to the server. In that case you can work on your files on multiple machines, or other people can take over, help working on your branch.

To commit your changes need to:

• Make sure all files are saved
• Stage all the files you've modified and want to commit to the server
• Write a commit message (a short and very specific summary of what has been changed)
• Hit commit button

Once the files are committed, it's time to push (send) them to the server:

• Open Push/Pull popup window
• Press Push

Merge request

Once you think your work is finished and ready to be published on the website, it's time to merge it to the master branch.

NOTE!!!

While you are working on your branch, other users possibly commit and merge their own changes, esp. if you are working on existing files. If those changes from the other users have already been merged to the master branch, the version of the files you changed may no longer be the actual ones and therefore the changes from other users may not be included in your files. In that state, if you want to let your changes be merged to the master branch, this process may be very chaotic.

Luckily git is able to compare versions and to insert your changes into the updated file versions. To trigger this, you need to update your branch before you Create a Merge Request. By doing this you will spare the admins and yourself a lot of needless work:

• First of all is to make sure all the changes are committed
• Open Terminal (Linux)
• Switch to Master Branch: git checkout master
• Update Master Branch: git pull
• Switch to working branch: git checkout <Branch_Name>
• Update your working branch from Master Branch: git rebase master
• Verify the changes and commit the changes to the Server

Now you can start with the final steps of merging your files to the Master Branch:

• First of all is to make sure all the changes are committed.
• Login to https://git.disroot.org
• If you pushed any changes to the server on your branch, in the top right you'll see a "Create Merge Request" button that will open the merge request form.
• Add a title
• Add a descripton
• Make sure the source branch is the one you want to merge from (the one you've been working on)
• Make sure the target branch is the one you want to merge to (usually Master branch
• Checkin the box Delete source branch when merge request is accepted. is also a good thing to do if you're completely done working on your branch.

Once you've created a merge request, it will be reviewed by Disroot admins and, if it's all right, they can approve your commit then. This means your changes will be merged with the master branch and therefore visible on the website.

If there's any issue, admins could request you to correct something. Once all the corrections are made and the documentation meets the Disroot guidelines, your merge request will be pulled to the master.

Pulling changes from the server

If you want to keep the local master branch and your local branch up to date, you'll need to pull changes from the server.

Each time someones gets his merge request pulled in to the master, everyone should also pull the changes to their local branches. Then you can easily see what's new and what has changed recently. On the master branch we keep a file called CHANGELOG where we note all significant changes to Howtos.

Pulling should be done on regular basis (specially before you start working on new branch).

• Open Push/Pull popup window
• Press Pull

Template to use for how-to's

You can copy the content here and create your how-to file.