\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename using-git.info @settitle using git @afourpaper @documentencoding UTF-8 @documentlanguage en @finalout @c %**end of header @dircategory Version Control @direntry * using git: (using git). Using the Git source control management @end direntry @copying Copyright @copyright{} 2013 Mattias Andrée @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @end quotation @end copying @ifnottex @node Top @top Using Git @insertcopying @end ifnottex @titlepage @title Using Git @author by Mattias Andrée (maandree) @page @vskip 0pt plus 1filll @insertcopying @end titlepage @contents @menu * Getting started:: * Introduction:: * Branching out:: * Collaborating:: * Basic commands:: * I just don't know what went wrong:: * GNU Free Documentation License:: @end menu @node Getting started @chapter Getting started @menu * Create a repository:: * Create an origin:: * Gratis hosting:: @end menu @node Create a repository @section Create a repository A repository is a directory under source control, normally your project you are working on. Create an empty directory and @command{cd} into it: @example mkdir MY_PROJECT cd MY_PROJECT @end example When you are inside the directory for the repository issus the git command to initialise the repository: @example git init @end example This command creates a directory namend @file{.git} inside the directory with all data git requires to operate on the repository. The next thing you want to do is to create a @file{.gitignore} file, it is used to keep track of with files that should be be included in the repository, unless overruled with a forced staging. A good base @file{.gitignore} content you probably always want to use is: @example _/ # It is a good idea to allow the directory _ to # contain temporary file you do not whant to stage. .* # Generally you probably do not want to include # hidden files. !.git* # But you do generally want to include files starting with .git, such as .gitignore. \#*\# *~ *.bak # And you do not want to include backup files. @end example Git parses @file{.gitignore} with wildcards, @code{#} for comments and @code{!} for inclusion rather than exclusion, latter entires override earlier entries. When you have create you @file{.gitignore} you are ready to stage it and make your first commit: @example git add .gitignore git commit -m 'first commit' @end example @node Create an origin @section Create an origin It is a good idea to create a backup repostory, so you do not lose your work on a disc failure, filesystem corruption accidental removal. You can such repostory for allowing collaboration with a command repository that the collaborators can all submit and fetch commits from. This repository is customarly called `origin'. And it is a bare repository, meaning that it only hold the data in the @file{.git} directory and cannot be used as the working directory. @example mkcd -p /srv/git/MY_REPOSITORY.git cd /srv/git/MY_REPOSITORY.git git init --bare cd - # Go back to your project respository git remote add origin file:///srv/git/MY_REPOSITORY.git git push -u orgin master # master is the bransh you are working in @end example It is standard to append @file{.git} to the end of the repository name when it is bare. To submit your changes to origin you can now use the command @command{git push}. To fetch updates others have made, use the command @command{git pull}. @node Gratis hosting @section Gratis hosting As seen you do not need host, but it is a grate way for making your projects available to the world. Here is a lost of gratis git hosting services that hosts Free Software. @table @asis @item @bullet{} @url{https://savannah.nongnu.org/, Savannah} Hosts Free Software only, and projects are audited for licensing issues upon registration. So it can take a short time before it is accepted, but you your project will not use non-Free Software and no license information will be missing. Savannah runs on only Free Software. @item @bullet{} @url{https://gna.org, Gna!} For Free Software projects only. Gna! runs on only Free Software. @item @bullet{} @url{https://bitbucket.org, BitBucket} Gratis for 5 uses, with unlimied number of private repositories for 5 collaborators. @item @bullet{} @url{https://github.com/, GitHub} 5 private repositories for students, for two yours and reactivatable when expired. Teachers and student organisations can get private repositories, as many as required, for an organisation. @item @bullet{} @url{https://www.assembla.com/catalog/51-free-private-git-repository-package?type=private&ad=git-wiki, Assembla} Hosting limited to 2 GB with one free private repository for three users. @item @bullet{} @url{https://www.cloudforge.com/pricing, CloudForge} Hosting limited to 2 GB. @end table You should note that there are, other, git hosting services that does not allow Free Software. Some of them will allow Open Source, some will allow Free Software, but not gratis. @node Introduction @chapter Introduction @menu * What is Git?:: * It is distributed:: * Integrity:: @end menu @node What is Git? @section What is Git? Git is a version control system know for its lightning speed and being distributed. A version control system is a system for storing changes in a history tree and allow for multiple people to work on the same project without the risk of the code being too new to accept a submitted patch. When you are working it is important to keep track of changes so that you can find when edit step broke the system. But version control also lets you create branches, these are different versions of the same project being developed concurrently which lets your team implement features in parallel and merge them in into the mainline when stable. And other important feature of version control that can be used to tag releases of the code. If you have release a program and is sent a bug report you may want to test it one both the current version and the version the user used. @node It is distributed @section It is distributed Traditionally, version control systems were centralised. Every project has one repository all contributers pushed and pulled from. Git is distributed, this means that contributers clone the respositor and words on that clone instead of ``checking out'' the current tip of the source code. This actually means that there are multiple backups of the respository is recovering a crash or corruption will be a breeze. It is a popular misconception that distributed systems are not suited for projects that requires an official central repository. This is far from true; projects have a central blessed repository, possibly with mirrors. A blessed repository, refered to as the upstream, is the projects official respository. Its maintained by a select few with input from submitted updates. But the upstream can also be a shared repository, this is the classical Subversion-style workflow, where everyone pulls from and pushes to. Git does not allow you to push before you have pulled to latest commit so this workflow works fine. Small projects will usally have one maintainer and contributors clones her blessed repository and sends submissons to her. Larger projects may have multiple maintainers that helps with excepting submissons. A common model like this, that you often se on GitHub, is the integeration manager workflow, where the maintainer is an integeration manager than excepts pull requests from developers that have public repositores, often called forks (which should not be confused with a project fork where the forker is taked the project in another direction is does not requests pulls.) Even larger project will usablly work with a dictator and lieutenants workflow where developers clones the blessed repository and submits patches to the lieutenants who in turn submits the the dictator that finally pushes the changes to the blessed repository. @node Integrity @section Integrity Git cryptographically hashes all data associated with a commit, including the prior commit. This makes it unfeasible to modify a commit without changing the commit ID; change the commit ID brakes the commit history and would therefore get noticed as the develops cannot work against a broken commit history. Additionally commits can be signed with GPG, so you can be sure that the commit is how is says he is. @node Branching out @chapter Branching out @menu * Workflow:: * Creating branches:: * Merging branches:: @end menu @node Workflow @section Workflow Git encourage you to create multiple local branches of you repository. A branch is a fork of your commit history, it allows you to implement features in parallel. The most important part with this is that you can fix bugs meanwhile you are working one big new features. You main branch is by default called `master', from it, it is recommended to have a branch called `develop'. The develop branch is the branch you work on, and when it is stable, you merge it with the master branch. From the develop branch you can branch out an create topic branches, an disposable experiments. @node Creating branches @section Creating branches The quickest way to create a new branch and start working on it is to issue a checkout command that create a new branch: @example git checkout -b BRANCH_NAME @end example After issuing this command you are located in a new branch. The create it in the origin, make a push: @example git push -u origin BRANCH_NAME @end example From this point on you can push without parameters: @example git push @end example The @option{-u origin BRANCH_NAME} is just to initially tell which remote repository a pushes should go to. To switch branch use the checkout command: @example git checkout BRANCH_NAME @end example @node Merging branches @section Merging branches The merge a branch into another, switch to one of them and pull the other: @example git checkout MERGER git pull . MERGEE @end example In the default mode, @command{git pull . MERGEE} is a short and fore a fetch and merge: @example git fetch MERGEE && git merge MERGEE @end example If you two cannot be automatically merged, you will you get a merge conflict. A case where you will get merge conflicts is when one of the branches as made a modification where the other has change the indention, so keep to a coding style from the start; or both has edited the same lines. If you get a merge conflict, git will tell you so, in which files there are conflicts, and exit with the return code 1 to indicated that the merge was not successful and human intervention is required. If the merger branch as a file with the line @code{Hello world} and the mergee branch as the line @code{hello world!}, the file will contain: @example <<<<<<< HEAD Hello world ======= hello world! >>>>>>> xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx @end example Where @code{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} is the lower case hexadecimnal represention of the commit ID at the tip of the mergee branch, which is a SHA-1 hash sum of the commit. After a merge conflict you will need to stage the files and make a new commit. @node Collaborating @chapter Collaborating @menu * Cloning a repository:: * Submitting patches:: * Accepting patches:: * Making pull requests:: @end menu @node Cloning a repository @section Cloning a repository The first thing you need to do in order to begin collaboration is the clone the repository: @example git clone REPOSITORY -o upstream @end example By including @option{-o upstream}, git sets up the cloned repository as a remote repository named `upstream'. If you want to access a branch in the upstream repository, use @code{upstream/BRANCH} as the branch name. @node Submitting patches @section Submitting patches The best way to create a patch is with Git's @command{format-patch} command. Assuming you began from @code{upstream/master}: @example git format-patch upstream/master @end example This command with create a patch whose name will be printed by @command{git format-patch}. Creating a patch this way will keep track of the commit messages, and the individual commits. Another advantage with it is that it can easily be submitted to a mailing list, which the common way for large projects for accepting patches. The created patch file is formated as an e-mail, with `[PATCH]' in the beginning of the subject line. If you update the patch it is customary to use `[PATCH v2]' instread and `[PATCH v3]' on the second update. If the patch, however it not readly for being included, but is rather for discussion, use `PATCH/RFC'@footnote{RFC is an abbreviation for `Request for comments'} instead of `PATCH'. To send the patch, use @command{git send-email}: @example git send-email --to=EMAIL_ADDRESS_TO_SEND_TO PATCH_FILE @end example If you have registered to the mailing list, or for some other reason, want to send under a different e-mail address then you made the commits with, you need to specify an envelop send, by adding an option: @example --envelope-sender=SENDER_EMAIL_ADDRESS @end example You will also need the specify which SMTP server to use, authorisation and configurations: @example --smtp-server=DOMAIN # it usally is prefixed with smtp. --smtp-server-port=PORT --smtp-encryption=ssl # or tls --smtp-user=ACCOUNT # usally just the username without domain --smtp-pass=PASSPHRASE @end example If you are using a forwarding e-mail, such as @@member.fsf.org, you send from using your normal e-mail, but use the forwarding e-mail address as the envelop-sender, most e-mail server should accept this. If you are replying to a message in the mailing list, perhaps with an updated patch, you should specify the message ID of the message to replay to. This done my adding the option: @example --in-reply-to=MESSAGE_ID @end example To get the message ID, open the message in your e-mail client and choose to see all headers --- if not possible: download the it as an mbox file and open it in an text editor --- a look for: @example Message-ID: @end example As indicated here, it is surrended by less than and grater than-signs. You should, if you have subscribed to the mailing list, have gotten it send to your e-mail. If you do not have it, go the the mailing lit and click that you want to reply, it will open your e-mail client in compose mode and the in-reply-to address will have been set to the proper message ID. @node Accepting patches @section Accepting patches To apply a patch, use the @command{git am} @footnote{`am' stands for `apply mailbox', but it words on regular patch files} command: @example git am PATCH_FILE @end example Is good practice to sign off commits to help establish a chain to trace submissions, and some projects will require it. To sign off with @command{git am}, just add @command{--signoff}. @node Making pull requests @section Making pull requests A less feature rich alternative than patches are pull request, but they are easier to just because you do know need to know anything to make a pull request and to accept them you just need to know how to pull from other repositories. Git does however provide a command the produces a clean standard message than can be posted on a mailing list. To do this just type: @example git request pull FORKING_POINT_COMMIT YOUR_URL @end example Additionally you can add a commit that the pull requests stops at, if you have another commit than @code{HEAD} --- the current commit you are working at --- in mind. You can also add @option{-p} if you want to see the changes. @node Basic commands @chapter Basic commands @menu * The trees of Git:: * File operations:: * Go back in time:: @end menu @node The trees of Git @section The trees of Git Git has four trees should know about to better understand how Git works. The first tree you encounter is the working directory. The tree begins in the parent so called git directory; the directory you executed @command{git init} in, and contains the directory @file{.git}. When you are using @command{git add} to stage files you encounter the next tree. This tree is called the index, and is separate from the working directory, when you stage a file, you stage an edit, if you edit the file further those changes does not make it into the index until you restage the file. When you have done some work --- just a small logical step is recommended --- and want to save your changes you commit then with @command{git commit}. This is when you encounter the third tree, the @code{HEAD}. @code{HEAD} is the file tree of the last commit, and it is updated when make a commit. The fourth tree is not a file tree, it is the commit tree. The important thing with Git is that this tree is not linear, it is a directed acyclic graph, so it is not really a tree, but you can think of it as one because you are normally only interested in the leaves, your branches. @node File operations @section File operations Their are four basic options you can do on files: add, update, remove and rename, adding and update is done with the same command: @example git add FILE @end example To remove a file or rename a file, just do as you normally would without git, but prepand @code{git}: @example git rm FILE # Remove FILE git mv FILE NEW_NAME # Rename FILE to NEW_NAME @end example If an directory in becomes empty in the working directory it is automatically removed from working directory. And directories are never tracked by Git, so you cannot have an empty directory in a commit. You can also use @command{git add -u} @footnote{@option{-u} is the short option for @option{--update}.} to stage an edit in an already tracked file or stage the removal of it if it as been removed from the working directory. A caveat with @command{git mv} is that is that is that same thing as typing: @example cp FILE NEW_NAME git rm FILE git add NEW_NAME @end example In other words, the history for the file is reset and if you do this at the same time someone edits the file you will get a merge conflict. This is not a problem with GNU Arch because it keeps track of which file is which by giving it an unique identifier, and you may think that would have been a good think. But if the content of the file depends on the file's name, or the other way around, and a line with such dependency is added, the file's content would become bad. Well it is debatable since the case could be that another file depends on the renamed files name, and someone could make a change in that file. But fixing a merge conflict when you have only renamed the file is not too hard and it eliminates a potatial maintenance miss. If you want do know the file staging difference between the index and working directory type @command{git status}. @node Go back in time @section Go back in time Because git keeps track of what has changed it has a log you access, which has commit messages, so you know when something has happend or what has happen lately. To read the log type: @example git log @end example If you want to know which files have changes, you can use @command{git whatchanged} instead. If you want to take a closer look a commit an see the state of the project at the commit type: @example git stash # Only if you have uncommited changes, this # saves you changes outside the tree in a stack. git checkout COMMIT_ID # Take a look around! git checkout - # Checking out - means that you checkout the # commit you were on before the last checkout. # Kind of like `cd -'. git stash pop # Only if you have uncommited changes, this # reapplies the changes you saved with `git stash' # and removes it from that stack. @end example If you instead what to see all changes from that point of time type: @example git diff COMMIT_ID @end example Or for a specific file: @example git diff COMMIT_ID FILE @end example If you decide that you want to go back permanently to this state you type: @example git revert THE_COMMIT_ID_OF_THE_COMMIT_AFTER_THAT_COMMIT..HEAD @end example If you have not push the commits you want to revert you can do a reset instead, thay way the are irreverable removed instead of a new commit being made: @example git reset --hard COMMIT_ID @end example But you should think of that as running as root: @cartouche @noindent Chris: root is the number zero user, it is main user in your system, it can do everything, it can literally delete the filesystem while your operating system is running. @noindent Bryan: Yeah, it is a grate user in that regard. @noindent Chris: Yeah. Yeah. @noindent Bryan: Here is the thing, so people always say `do not run as root.' @emph{I always} run as root. @noindent Chris: Do you really always run as root? @noindent Bryan: Hell yes. Do you know why I always run as root? @noindent Chris: Why? @noindent Bryan: Awesome. @noindent Chris: Here, I... @noindent Bryan: I live on the edge. I'm like Mad Max. @noindent Chris: Do you really always run as root for real? @noindent Bryan: No, I do not run as root. Are you kidding me, that is asinine! I would love to think that I am so hardcore that I just always ran as root. I just, caution to the wind, screw it, lets just thunderdome this bitch and... you know, see what happens. But no, never run as root, never ever do that. The only time you run as root is when you run as root temporarly, you sudo. @noindent Chris: You need to do something. @end cartouche Only use @command{reset} if you are absolutely sure and know exactly what you are doing. @node I just don't know what went wrong @chapter I just don't know what went wrong @menu * Naïve reset:: * Using the stash:: * Commit amendment:: * Bisection:: @end menu @node Naïve reset @section Naïve reset If something went horribly, horribly, horribly, horribly wrong and you do not know how to get back to a clean state, you can always doing this naïvely by clone the repository: @example git clone REPOSITORY REPOSITORY.new cp REPOSITORY/.git/config REPOSITORY.new/.git/config yes | rm -r REPOSITORY mv REPOSITORY.new REPOSITORY @end example @node Using the stash @section Using the stash The stash is a grate utility for storing changes. If you have made changes in the working directory or the index, you can store them in the stash and both the working directory and the index will be restored to the @code{HEAD}. Keep in mind the the naïve reset will discard the stash because the stash is local. Changes stored to the stash can be applied to any branch and any later state of the @code{HEAD}, that is what the stash is made for. The basic stash operations include: @table @command @item git stash Store the changes made to the index and working directory. @item git stash drop Discard the object at the top of the stash stack. @item git stash apply Apply changes stored as the object at the top of the stash stack. @item git stash pop Synonym for @command{git stash apply && git stash drop}. @item git stash clear Discard all stored stash objects. @end table @node Commit amendment @section Commit amendment If you have not yet pushed your latest commit you can amend it. If you have pushed it, you cannot amend it cause the commit ID changes because it is SHA-1 hashsum of all imformation. To amend your commit run @command{git commit --amend}. It will launch your text editor so you can edit the commit message, additionally all staged changes are included in the amendment. @node Bisection @section Bisection Bisection is the process of identifying when a bug was introduced. To start a bisection you first need to tell git to start bisection and specify the commit range. If the current commit is bad you type: @example git bisect start git bisect bad git bisect good LAST_KNOWN_GOOD_COMMIT @end example After this you either of, depending if the commit Git checks out is good or bad: @example git bisect good git bisect bad @end example Git will tell you when it has found the the first bad or possible first bad commit. To then checkout the commit that was checked out before the bisection started type: @example git bisect reset @end example If you in the process of the bisection landed on a commit you need to skip because it has some other problem, you can use @example git reset --hard HEAD~N @end example Where @code{N} is the number of revisions before the checked out, you want to jump to. You can also use @command{git bisect skip} to Git which revision that cannot be tested so they are excluded from the bisection process. Instead of manually telling Git if a commit is good or bad, you can use: @example git bisect TEST_SCRIPT [ARGUMENTS...] @end example The test script should exit with 0, if and only if the commit is good, 125 to skip the commit, and anything else between 1 and 127, inclusively, if the commmit is bad. Other values (128–255) are will abort the bisection. @node GNU Free Documentation License @appendix GNU Free Documentation License @include fdl.texinfo @bye