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 as well as NDP Software :: Git Cheatsheet which provides an interesting way to 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

Ignoring Files

So, the easy way to ignore a file is to add it to your .gitignore file. Usually this will be in the root directory of the repository and contain a list of files, file extensions and directories to be ignored. You can add comments to the files by starting a line with a #, which is a good idea, and allows you to remember why you are ignoring some files. You can even commit your .gitignore file to Git, that way, everyone is ignoring the same files. This is all explained at Git - gitignore Documentation.

However when working on a Mac you will probably find you need to keep ignoring files like .DS_Store which will apply to every Git repository you use. However you may not want this in your .gitignore as others might not be on a Mac. In which case you can use a computer wide ignore file as follows:

  • Enter this: vi ~/.gitignore
  • Add a couple of lines as follows:
    # Mac Specific
    .DS_Store
  • Enter the following command: git config --global core.excludesfile ~/.gitignore
You might prefer to call the file .gitignore-global but that is just personal preference. Oh and note that all .DS_Store files are ignored in all directories, from a Git perspective. It is worth looking at github/gitignore: A collection of useful .gitignore templates for some good example files.

GUI Git Tools

The basic, default Git for Windows client does include a GUI, however this is not the case on other platforms. See Git for Windows or further info for Windows and a link to their GitHub repository.

I have been using Visual Studio Code for file editing and as a Git client and I have found it actually works very well. From what I can tell, it does everyhting you need it to.

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.

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