.. meta:: :description lang=en: Quick tutorial for git and Bitbucket :description lang=fr: Rapide tutorial pour git and Bitbucket ############################################################### Quick tutorial for `git `_ ############################################################### Introduction ------------ This page is a quick introduction to `git`_ , and its regular use via `Bitbucket `_. This article contains very quick explanations about how to start using and mastering the mighty `git`_ software, its installation, and its use thanks to the awesome `Bitbucket`_. Links are provided to other tutorials and other explanations. I also use that page to join and publish a few configuration files to improve and customize your use of `git`_, some advices, and some aliases to ease the use of `git`_ on the command line (thanks to your ``~/.bash_aliases`` file for the command-line `GNU/Bash `_ environment). .. note:: Licence ? This page, and all related files are freely distributed under the terms of the `GPLv3 licence `_ ! (like everything I publish or distribute). ----------------------------------------------------------------------- About **Git** ^^^^^^^^^^^^^ The official website of `git`_ is `git-scm.com `_. What is Git ? ~~~~~~~~~~~~~ « *Git is a decentralized* `version control `_ *software. This is free software created by Linus Torvalds, Linux kernel copyright and distributed under the terms of the GNU General Public License Version 2.* » « *Git is designed to be efficient in speed and ensure the integrity of data stored, sent or received. Completely free and open-source since 2005, it quickly became the most popular version control system for software development.* » What's the point? ~~~~~~~~~~~~~~~~~ .. sidebar:: Example ? For instance, `this link shows the first version I wrote for this very page `_ ! By using `Bitbucket`_ web interface, you can see `the complete history of changes for this document `_. « *A version control software is a software designed to store a set of files by holding the chronology of all the changes that have been made on it.* » « `git`_ *allows notably to find all the previous versions of a lot of related files. It also allows an effective and secure control of your files (and even of entire projects) and also provide a complete track changes made to each file.* » Needless to say, `I am using git constantly `_, mainly when I work on Linux ((X)Ubuntu™ 15.10) on a daily basis, and from time to time on Windows™. Is it really so popular? ~~~~~~~~~~~~~~~~~~~~~~~~ Yes: * The biggest web companies use git: `Facebook `_, `Google `_, `Twitter `_, `Netflix `_ or `LinkedIn `_ for instance. * The `git`_ project itself has been developed by a small team, and they have been using `git`_ themselves: `GitHub.com/git `_ for quite some time! * In November 2014, `GitHub `_ seemed to have more that **7 millions of users**, `Bitbucket`_ had **almost 2 millions**, and `gitorious `_ more than 400 000! * The `wonderful software toolbox `_ `GitLab `_ claims to be used by more than **100,000 companies and organizations from the world!** See for `instance the Crans gitlab `_ (and `my not-so-used account on it `_). An important distinction ~~~~~~~~~~~~~~~~~~~~~~~~ * `Bitbucket.org `_, `GitHub.com `_, `Gitorious.org `_ (`which hosts the source code for the amazing "Frédo" mathematics books `_), or `the Crans GitLab `_ are just **hosting services** (awesome services, but just this). * `git`_ is the version **management software (free, open-source and free)**, used by all these web services. Documentation about `git`_ ~~~~~~~~~~~~~~~~~~~~~~~~~~ A little loose, but still in the order from the best reference to the blurrier: * `This first tutorial by the team running Bitbucket (Atlassian) `_, * `www.Atlassian.com/git/ `_ covers lots of things. I like the graphic and English styles of these explanations, * `the official reference book on git-scm.com `_, * the `help.GitHub.com `_ website is really well designed, and it can sure help you, * this project on GitHub is a git style guide, to help you learn how to correctly name your branches, commits etc, see `this article by @agis `_, * this last `tutorial on readwrite.com `_ is quite well written (`second part `_). Two documents in PDF to download in order to never panic when you will get lost during your first days with `git`_: * The first one is `given by training.GitHub.com `_, * The second one `is by Atlassian `_. Other resources (less useful, but can help): * `en.wikibooks.org/wiki/Git `_. * `that other unofficial tutorial `_ about the use of both `git`_ and `Bitbucket`_, * `this third tutorial `_ is kinda ugly but might be useful. * This `« Start with Git » by Robusta Code `_. .. note:: And how does it work, *really*, underneath the nice web interface and command line tools? Is it (theoretically) complicated? :red:`Yes.` .. image:: .git.png :scale: 100% :align: center :alt: XKCD of Friday the 30th of October, about Git :target: https://xkcd.com/1597/ --------------------------------------------------------------------- My (amateur) use of `git`_ --------------------------- `My setup <./publis/git/>`_ ^^^^^^^^^^^^^^^^^^^^^^^^^^^ :State: *Actively maintained.* (November 2014) For these two configuration files (on Linux), a global ``.gitconfig`` and ``.gitignore`` can be in your ``HOME`` (``~/``, or ``/home/pseudo``), and a particular file for every repository can also be created. * `.gitconfig <./publis/git/.gitconfig>`_ to configure the complete behavior of `git`_ (inspired by the `one of the Crans developers `_, thanks to them). * `.gitignore <./publis/git/.gitignore>`_ lets say which files should be ignored (ie. not considered) by `git`_ when it indicates the unsupervised files. .. seealso:: About ``.gitconfig`` ``git-config`` is a git command, and it interacts with the file(s) ``.gitconfig``. The page `git-scm.com/docs/git-config `_ gives in-depth explanations on how to use a ``.gitconfig``. More details are also given `here on the book on git-scm.com `_. `These explanations by Atlassian `_ or `this small article by Nick Berardi `_ can also help. Two other examples: `GitHub.com/matagus/gitconfig `_, `GitHub.com/alikins/gitconfig `_. About ``.gitignore`` `These explications on help.GitHub.com `_ why and how to use ``.gitignore``. GitHub even offer a `collection of .gitignore files `_ suitable for different kinds of projects. For instance, `that one is perfectly designed to use with a Python project `_. This other reference page `git-scm.com/docs/gitignore `_ or `that last article on kernel.org `_ can also help. Punk Rock Git `This article `_ by `Ian Miell `_ explains very well some git commands and their core concept. From the Command Line ^^^^^^^^^^^^^^^^^^^^^ You can consult my `bash_aliases `_ (also `here on Bitbucket.org/lbesson/bin `_). I defined the following `Bash aliases `_, which allow you to see the changed, deleted or added files: * ``alias GitChanged='clear ; git status | grep --color=always 'modified' | less -r'`` for the modified files, * ``alias GitDeleted='clear ; git status | grep --color=always 'deleted' | less -r'`` for the deleted files, * ``alias GitAdded='clear ; git status | grep --color=always 'added' | less -r'`` for the added files, * and ``alias GitSize='clear; git count-objects -v -H | grep "size-pack" | sed s/"size-pack: "/"The size of the repository is "/'`` displays the storage size of the current repository (e.g. 10.43 MB currently for `this project web-sphinx `_). .. runblock:: console $ git count-objects -v -H | grep "size-pack" | sed s/"size-pack: "/"The size of the repository is "/ These ones are good shortcuts, which by default also launches local compression of the just filed after each operation (on average it saves time): * ``alias Push='clear; git push && git gc'`` to upload the latest changes on the mother repository, * ``alias Pull='clear; git gc && git pull && git gc'`` to download the latest changes from the mother repository, * ``alias Commit='clear; git commit -m'`` to quickly validate the last changes (ie. doing a *commit*), * ``alias Add='git add'`` to easily add files, * ``alias Aggressive='git gc --aggressive'`` launches an "aggressive" compression, * ``alias s='clear ; git status | less -r'`` is a handy shortcut for the most used `git`_ command: ``git status``. And finally, I have defined an practical alias to synchronize the current project with the deposit mother and its sub-folder on my website. * ``alias Sync='clear; echo -e "Synchronizing (git push, gc, send_zamok, send_dpt)…"; git push; git gc --aggressive; make send_zamok; make send_dpt; alert'`` For instance, `that repository `_ is `here locally on my website (publis/ansi-colors) `_. `That other one `_ is `here locally on my website (publis/Bomberman) `_. `And that last one `_ is also `here locally on my website (python-demos) `_. .. note:: Details about aliases Bash? More information is available `in this book about Bash programming `_, `on the Linux documentation project `_, `that other doc `_, or that `last Wikipédia about aliases on generic scripting programming language `_. .. warning:: Git does * not * store compressed diffs, but entire files, at every release (in compressed form, okay)! Contrary to what I believed for a long time (until 2020!), There is a difference between what *git* displays when we do a ``git diff file`` and what *git* stores when we add this file in a new commit! I thought for a long time that *git* stores the ``diff``, but actually no! This is the biggest "urban legend" or misunderstanding on *git*, and I discovered my mistake thanks to `this blog post on GitHub.blog `_ (and `this one too `_). With `Sublime Text 3 `_ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: A graphical interface for `git`_? The use of any good GUI for `git`_ can save a lot of time. To write webpages and code, I like `Sublime Text 3 (ST3) `_. Regardless of your text editor or IDE, it should be possible to bring this kind of functionality to easily use `git`_ without always going through console commands. For example, Atlassian offers `SourceTree `_, for Windows™ and Mac™ OS X. And GitHub have developed their own application `for Mac™ OS X `_ or `Windows™ `_. The following free plugins allow a smooth and easy use of `git`_ on `Sublime Text 3`_: * The small `GitGutter `_ will help to visualize the difference of *each line* of *each file* regarding the last commited version for the *git* repository in which it is located (visually great to see the changes since the last *commit*). * The wonderful `SublimeGit `_ (installable from `sublime.wbond.net/packages/SublimeGit `_). Allows a full integration of git via the control panel. Free but annoys you regularly to ask you buy an (useless) 10$ commercial licence… But it is really awesome, so you will support this. * `GitSavvy `_ seems to be a good free and open-source alternative. .. seealso:: `sublimetext.en.html`_ Please read the recent page `sublimetext.en.html `_ for more details on the use I make of Sublime Text 3. With Bitbucket.org ^^^^^^^^^^^^^^^^^^ Like the other hosting services, `Bitbucket`_ is **free**, flexible, powerful, `24h/24 and 7/7 functionnal `_, and allow to easily publish your code on Internet. .. note:: GitHub offers pretty much the same (awesome) features, for free too. `Bitbucket`_ offers in addition to the public repositories and unlimited numbers of private repos. Every repos is `limited to 2GB `_ (you really have to want to break the system go beyond!). Signing up is quick, just go to `this page https://Bitbucket.org/ `_ ! (Note that `Bitbucket`_ can also be used with a Google account, Facebook, GitHub or even with `OpenID `_.) Once your profile is created, it will look like mine, but more *empty*: `Bitbucket.org/lbesson `_ (see this one for another example `Bitbucket.org/jilljenn `_). Public deposits are visible to all: `Bitbucket.org/lbesson/profile/repositories `_. For example, here are some of my repositories: - `Bitbucket.org/lbesson/web-sphinx `_ stores the sources of `this website `_, as for instance the reStructuredText (``.rst``) source code for that `(→ and with a direct link to THAT line) `_, - `Bitbucket.org/lbesson/bin `_ hosts dozens of scripts, especially some in Bash and Python - `Bitbucket.org/lbesson/web-sphinx-scripts `_ stores local versions of all `Javascript scripts used by this site `_, - `Bitbucket.org/lbesson/cv `_ stores the \\(\\LaTeX{}\\) sources for my résumés `in English `_ and `in French `_: `cv.en.tex `_ or `cv.fr.tex `_, - `Bitbucket.org/lbesson/munstrap `_ a small repository hosting my French translation of the theme **Munstap**, adaptive and modern theme for `Munin `_. Further reading is available here `en.WikiPedia.org/wiki/Bitbucket `_. Publish web pages with Bitbucket? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your username is Bitbucket **STUFF**, it is possible to create a repository called "STUFF.bitbucket.org", and then all documents will be stored there you will be automatically available on the website `http://STUFF.bitbucket.org `_ ! More details are given on `cette page de doc par Atlassian `_, and `here is their example (tutorials.bitbucket.org) `_ is online at `https://tutorials.bitbucket.org `_) (This service is unfortunately a little less advanced than GitHub (`GitHub.io `_, `see the doc here `_), but works well anyway.) .. note:: `lbesson.Bitbucket.org `_ ? See for example this little page `lbesson.Bitbucket.org/README.html `_ whose source is hosted here `Bitbucket.org/lbesson/lbesson.bitbucket.org/src/master/README.html `_. I mainly use `lbesson.Bitbucket.org`_ for: - `squirt `_ a bookmarklet for Firefox, Chrome or Opéra, allowing to read a webpage *super fast* (hey, by the way, it is available on that website also, go on, try by hitting the "q" on your keyboard! *Cool right?*), - `StrapDown.js `_ is a pretty project to quickly and easily write and publish responsive webpages, in `Markdown `_. Such StrapDown-powered document are *directly* ready to be published *like-this* on any website or server, without any boring compilation step required by you ! (This project currently `is only downloaded about 20 times a month `_, thanks to the zip archive `StrapDown.js.zip `_), - My own copies of the (legendary) **2048** game: `lbo.k.vu/2048 `_ (the original one), `lbo.k.vu/2048-agreg `_ (a version `for mathematicians `_) or the interesting `lbo.k.vu/2048-AI `_ (available with an `Artificial Intelligence `_). - and `this homepage that acts as a nice wrapper for my website `_. And even if the certificate is not valid, it is perfectly possible to use this feature with `HTTPS `_ activated: `https://lbesson.Bitbucket.org/README.html `_ (if your browser rattle and displays an error **is perfectly normal!**). If you are using a relatively new browser, it may grumble and explain why (you will see that the only reason is that the `SSL certificat `_ for `https://bitbucket.org `_ has been signed for only a few sub-domains of the website bitbucket.org, not all of them). But in fact the traffic will be well encrypted and secured by the SSL certificate, no worries :) A French web interface for Bitbucket? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For a little over a year, it is possible to change the interface of the site in French (and many other languages) in `your personal settings `_. .. note:: French translation? In March and April 2013, I initiated and for some time I managed the `translation of the site and the service of the English into French `_. `I translated almost 90% `_ presque 90% du contenu initial, of the original content, left some small typos, but we did a good job. With few other motivated and myself, French was the first language translated to 100%! (Mid March 2013) I have neither the time nor the desire to take care of it, but `the project continues to be maintained by others `_. Some "Buttons"? ~~~~~~~~~~~~~~~ As some GitHub fans offer `ghbtns.com/ `_ or `buttons.GitHub.io/ `_, a Bitbucket fan designed `bb-btns.bitbucket.org/ `_. Here are some examples for `my web-sphinx deposit `_: .. raw:: html

The same, but `hosted on lbesson.bitbucket.io/bbbtns/ `_ (for my `bin <./bin/>`_ repository): .. raw:: html

The same, but `hosted on my website (./bbbtns/) <./bbbtns/>`_ (for the `lbesson.Bitbucket.org`_ repo): .. raw:: html

----------------------------------------------------------------------------- One last tip? ^^^^^^^^^^^^^ As with any technical and powerful software, `git`_ takes time to adapt. Be persistent, it is worth it. « *I wish you a very good programming experience, and good luck for your geeky projects!* » Additional credit ^^^^^^^^^^^^^^^^^ Thanks to `Vincent Cohen-Addad `_ for motivating me to start using `git`_, in Octobre 2012 for `the network programming project for my Computer Science (CS) Master of Science (MPRI, course #1-21) `_ on which we worked together. .. (c) Lilian Besson, 2011-2021, https://bitbucket.org/lbesson/web-sphinx/