TechDocs/Git/Guide:Workflow

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/Guide:FirstSteps. Also make sure you understand basic Git commands as described in TechDocs/Git/Guide: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:

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: Graphical workflow

This guide is for those who want to use Git with a graphical user interface. We will use Git Cola, but the instructions here should generally translate loosely between different interfaces.

You can find Git Cola as git-cola package in most distributions.

Set up your repository

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.

Open Git Cola and press the "Clone" button. Insert "git@git.fsfe.org:YOURNAME/fsfe-website.git" into the URL bar and proceed. It should download the repository for you.

attachment:clone.png

You are now on the master branch of fsfe-website in your local repository.

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.

Click on "File", then "Edit Remotes...". Add a new repository called upstream with the link "git@git.fsfe.org:fsfe/fsfe-website.git".

attachment:remote.png

Your local repository is now tracking two remote repositories, and you are ready to begin working.

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).

First, make sure that you are on the master branch of your local repository. You do this by right-clicking on "master" in the branches dock and clicking on "Checkout", or by clicking on "Branch" in the menu and clicking on "Checkout...", then selecting the master branch.

Now, you pull from upstream/master. You do this by clicking on "Actions" and clicking on "Pull...". Select upstream and master in the pop-up that appears.

If you want, you can also add all the actions to the main window by clicking on "View" and selecting "Actions". This makes it a little more persistently obvious what actions are available to you.

At this stage, the master branch of your local repository is identical to the master branch of the remote main repository. You can also update your remote repository by clicking on "Push". See picture.

This step is not absolutely necessary, but doesn't hurt.

Start on a new feature

Now that you have your master repository up-to-date, it is time to start working on something. Checkout to the master branch before beginning, then create a new branch for your feature. You do this by clicking on the "Branch" menu item and selecting "Create...".

You are now on your new branch. This is where you can leave Git alone, and just start working. When you are done, you return to Git and see a screen like this:

This is where you can 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. To add files to the staging area, right-click on them and click "Stage Selected".

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. Let's do that now. Just type a title for the change, and optionally an additional description, and click "Commit".

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, push your local commits to your remote repository. Click on "Actions", then "Push...", and configure three things: The remote you want to push to (origin), the local branch that you want to push (NAME-OF-FEATURE), and the remote branch that you want to push to (usually identically named, so NAME-OF-FEATURE).

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.

Guide: Terminal workflow

Setting up your local repository

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

You have now cloned the master branch of fsfe-website.

Also, by typing that command, 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 as follows, and call it upstream:

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

Your local repository is now tracking two remote repositories, and you are ready to begin working.

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). This is fairly simple to do.

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. 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 can leave Git alone and begin working on the files. You only return to Git when you are done. After you are done, you can do something like this:

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".  This is basically a list of files that
# you would like to commit at once.
#
# 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.  By
# committing, you are saying that you are confident in your changes and that
# they are (more-or-less) complete.
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.

Miscellaneous tasks

Sections for misc. tasks go here, so they don't litter the main guide with superfluous information.

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.

TechDocs/Git/Guide:Workflow (last edited 2017-09-12 07:13:10 by carmenbianca)