• Events

• LocalGroups

• Activities

• Teams

• KnowHow

• RecentChanges

Common information

The workflow in Git is quite different from what you may be used to. This is because Git is decentralised. Every repository in Git is equal, but some repositories are more equal than others.

Before you start, make sure you have everything set up as described in TechDocs/Git/FirstSteps. Also make sure you understand basic Git commands as described in TechDocs/Git/FirstCommit

The Three Repositories

As a beginner, you only really need to know about three repositories that are relevant to you, and that you will interact with. For this guide, we will assume that we are working on fsfe-website. The three repositories are:

• The main remote repository or upstream: https://git.fsfe.org/fsfe/fsfe-website. This is the most important repository, because everyone has agreed that this is the "official" repository.

• Your remote repository or origin: https://git.fsfe.org/YOURNAME/fsfe-website. This repository is created when you click on the "Fork" button on the main repository's web page. At the time of pressing that button, it is basically identical to the main remote repository. But when changes are made to the main remote repository, those changes are not made to your remote repository, unless you manually push the same changes. This repository contains all the commits that you have made. You have complete control over this repository, and you can do with it as you like!

• Your local repository. This is the directory on your local computer. You also have complete control over this repository. Nothing you do in this repository affects any other repository until you push.

These three terms will consistently be used in this guide.

A note on branches

In Git, you will often be using branches. When you first visit a project's web page or first clone a project, you will see the master branch of that repository. This is the main branch in any repository.

Consider a branch like an independent alternate timeline of commits, where the master branch is the main timeline. So if you create a new branch from master, you are entering an alternate timeline that, from that point onward, is not affected by changes in master. You can merge that timeline back into master, though this is often done by the maintainer of the repository.

Similarly, when a new commit is added to the master branch of the main remote repository, that commit does not immediately appear on the master branch of your remote repository. You have to manually update this. This makes sense, because your repository is independently your own, and nobody else's.

You usually do not edit the master branch directly. Ideally, the master branch is identical between the main remote repository, your remote repository and your local repository, so that all repositories agree on the official series of commits. If you edit your own master branch, you are basically disagreeing with the main remote repository and creating your own "official" timeline. Which would be fine, if you were writing an alternate history novel, but you probably want to stick to the official master branch.

Guide

This guide is way to create a new pull request, i.e. a proposal for an addition or change of yours to the upstream repository, mostly via the terminal. This solution is preferred over using graphical applications, because it is easier to ask someone to type a certain command, than it is to ask them to push some buttons.

Set up your repository

Please, keep in mind that for setting up git and cloning repository you will need from 2 to 3 hours of time! So it's better to do this when you come to the office in the morning.

Assuming you have set up your remote repository by clicking the "Fork" button on the main project page, you can now set up your local repository.

• mkdir -p ~/FSFE  # Create a directory to hold your local repositories
  cd ~/FSFE
  
  # Create your local repository by downloading your remote repository.
  git clone git@git.fsfe.org:YOURNAME/fsfe-website.git
  cd fsfe-website

Also, by cloning, you have implicitly configured a "remote" for your local repository. This remote is called origin, and is equal to "git@git.fsfe.org:YOURNAME/fsfe-website.git". You might want to add an extra remote, however, pointing to the main remote repository. Let's do this now, and call it upstream.

• git remote add upstream git@git.fsfe.org:fsfe/fsfe-website.git

Syncing all repositories

Before you start, you may want to synchronise all repositories so that you are working on the latest version of the main remote repository (upstream).

• git checkout master       # Switch to the main branch.  This is a branch in your
                            # local repository.
  git pull upstream master  # Pull the latest version of upstream into your local
                            # branch.
  # Your local repository is now up-to-date!
  
  git push origin master    # Let's also push the changes to your remote repository.
                            # This is not strictly necessary.

Start on a new feature

Let's begin changing something, e.g. adding a new translation. Assuming that your local repository is up-to-date, you can create a new branch from master. We never make any changes directly to the master branch.

• git checkout master              # Make sure we are starting from master.
  git checkout -b NAME-OF-FEATURE  # Create a new branch from master, and change
                                   # to it.

At this point, you leave Git alone and begin working on your changes. You only return to Git after you are done.

When you are done, you add files to the staging area. This is basically a list of files that you would like to commit all at once. Everything outside of the staging area is not committed. When the staging area is properly populated, you can commit. By committing, you are basically declaring that you are confident in your changes, that they form a single cohesive whole, and that they are more-or-less complete.

• git status  # Let's have a look at what branch we are on, and what files have
              # been changed.
  git diff    # Let's see what exactly was changed.  Press 'q' to exit.
  
  # Let's add files to the staging area.
  #
  # Use `git add FILE` to add to the staging area.
  # Use `git reset FILE` to remove from the staging area.
  git add path/to/file/that/changed
  
  # When you are done setting up your staging area, you can commit.
  git commit -m "MESSAGE DESCRIBING YOUR COMMITS"

Sharing your changes

If you did the above, you have now added a commit to a branch in your local repository. But you want to eventually get that commit into the master branch of the main remote repository. To do that, you have to follow a few steps.

First, you upload the branch with commits to your remote repository (origin).

• git checkout NAME-OF-FEATURE     # Make sure we're on the correct branch!
  git status                       # Double check whether everything is good.
  git push origin NAME-OF-FEATURE  # Upload your branch

When you go to https://git.fsfe.org/YOURNAME/fsfe-website, your commit should now be visible in its own branch! This is good, because it means that your change is available online, and that others can view it. This also means that the maintainer of the main remote repository can view your changes.

To ask the maintainer to pull your branch into the master branch of the main remote repository, you create a pull request. You do this by navigating to the main webpage the main remote repository and clicking on "Pull Requests". There, you can create a new pull request and specify that you would like the maintainer to update master (main) with NAME-OF-FEATURE (compare). Add a title and a description, and your work is done :-). The maintainer will review your changes and accept them when everything is okay.

Questions

This guide is, and will probably always be, incomplete. Git is a very advanced piece of software. If you run into a problem that this guide does not explain, please ask a technically inclined person to add a section to the guide that sufficiently explains how to deal with that problem.

There are also very many guides on how to use Git on the internet. Atlassian and GitHub have some very detailed tutorials that may help you.