Git

It has to be said that if you want to contribute to an Open Source project then you will need to deal with git. So have a look at Git - Reference or Git Reference if you need help.

You should also visit Git Immersion - Brought to you by Neo to learn about Git. Another good place to work through is Git Tutorial - Try Git which is from GitHub but should still help.

There are also some very useful links in Development/Git For LibreOffice Developers - The Document Foundation Wiki which will help.

Git Tips

Write your commit comments in the past tense, when others view them, it will be in the past and when you commit, it will be work you did prior to committing and should be a summary. Some people use a "CATEGORY: message" format, so for example:

BUGFIX: Resolved file error
DOC: Fixed README.md
ENHANCE: Added more cowbell
BUGFIX: fixed crash on http read
CLEANUP: removed old tests

This works well for documentation but limiting the categories obviously helps. In addition it is worth reading How to Write a Git Commit Message.

Git Hosting

Probably the best known is GitHub, however Code, test, and deploy together with GitLab open source git repo management software | GitLab is also a strong contender and has some distinct advantages over GitHub.

Changing Directory Structure

if you need to change your directory structure then do the following:

  • Confirm everything is committed into Git and pushed up to the origin
  • Move your directories and files around
  • git status will reveal what you changed
  • git add --all adds the new directories
  • git commit -m "suitable descriptive message" to commit locally
  • git push to send to code up to the central server
  • All done, check the server's commit and you will see stuff has "moved"

Squashing or Merging

Sometimes when working with GitHub or other git repositories you want to merge your changes into one commit instead of several. Let me explain, in the context of GitHub.
I created a fork of a project, made my changes and submitted a pull request for the repository owner to merge my changes in. However I needed to do a bit more work on the change, so after some comments back and forth with a couple of people I ended up with a number of commits in my fork, which would then, I believe, all appear in the main repository, the owner asked if I could merge/squash these into one commit. So this is what I did:

  • In base/root of my copy execute git log -5, where I had made less than 5 commits
  • Look for the commit before mine and grab its id, c3c8f8ce568114d7aae1ae263e03390617c7c878
  • Then execute git reset c3c8f8ce568114d7aae1ae263e03390617c7c878
  • Now you can update your local repository with git add filename.ext and then git commit
  • Once you have everything checked in locally, execute git log -2 and check it is as expected
  • Next you need to force your changes up with git push --force
This of course makes the assumption there were not other conflicting commits in the mean time.

There is more information on git reset and other similar command at Git checkout | Atlassian Git Tutorial.

Branches

If you do work on the Git server, like creating a Pull Request, merging it and then deleting the source branch you will find your local Git has an orphan branch. The first step is to switch your local Git off this orphan branch and then it is best to delete it, see Pruning obsolete Git branches for details.

Useful Commands

git checkout ./dir/filename.ext - this is a handy way to undo local changes on a specific file, provided the changes have not been committed
git reset --hard - this undoes all local uncommitted changes, removing any extra files
git bisect - used when you need to find when a bug or change was introduced
git config --global http.proxy http://hostname:port - essential when you are behind a proxy server, note that this works when your Git repo is on https
git remote -v - shows the remote repositories

GUI Git Tools

The basic, default Git for Windows client does include a GUI.

I have used SourceTree | Free Git and Hg Client for Mac and Windows a little, it seems to need an Atlassian account to install but after that was fine. In my experience it does not play well behind a proxy server. You might find How to Wipe SourceTree Preferences - Atlassian Documentation handy if you want to reset it.

A reasonable code editor and Git client is Visual Studio Code which I have found actually works quite well.

I have looked at Git Cola: The highly caffeinated Git GUI but it is more difficult to install on Windows as it needs Git for Windows, Python and PyQt. I got as far as needing qmake to install PyQt and gave up!

I am planning to investigate Git GUI Client for Windows Mac and Linux | Axosoft GitKraken but it is only free for non-commercial use on Windows, Mac & Linux.

For a very basic "diff with Git" then take a look at Meld.

Bitbucket

A number of companies use Bitbucket - the Git solution for professional teams | Atlassian from Atlassian, which was previously known as Stash. It is a Git server, with a nice browser interface that integrates very well with other Atlassian products like Jira and Confluence.

One issue I found was converting the Bitbucket URL to something command line Git could understand. So for example, let's suppose you have a browser open and are looking at your repository and the URL is this https://stash.example.com/projects/PRJ/repos/REPO/browse, where PRJ is your project key and REPO the name of the repository in it. This translates to the following Git command: git clone https://stash.example.com/git/PRJ/REPO.git.

Helpful Links