Using GIT, GitHub, and GIT GUI Git is a version control system released April 2005. It is one of the most commonly used tools for version control in software development worldwide. As a tool, it is incredibly useful for its ability to not only save your progress, but allow you to share your work, or backtrack to a previous point when you inevitable break everything.
As Git is such a versatile tool, it is thus extremely difficult to use. The cost of such flexibility and freedom, is that the user has the freedom to break things very quickly and easily. I hope this guide may delay that day. Terminology Terminal The ‘terminal’ is the means by which we communicate with our git repository. It allows us to enter the appropriate commands by which we package, store and access our data. Repository The ‘repository’ is the space where we store our data. This is often on the servers of ‘GitHub’ or ‘BitBucket’, however if the need were to arise, you could have a local repository as well. Working Tree The working tree refers to the copy of the data that the user (you) stores on their device. Branch Git separates change history into branches. This allows for multiple stems of development to take place without affecting one another. Every repository, by default, has a ‘master’ branch. This is the branch that you are expected to use to contain the primary copy of your information. Other branches can be created, merged and deleted as needed. It is important to know that branches are located both on your device and in the repository, and do not necessarily have to mimic each other. When I pull the information from the repository, I can set Git to update a certain number of branches with data from different repository branches. E.g. local branch ‘Feature X’ can retrieve data from repository branch ‘Master’, while local branch ‘master’ retrieves data from repository branch ‘Feature X’. This can get quite confusing, and I high recommend for you to … not do that. Merge To ‘merge’ branches together is to combine their change histories into a single timeline. Were both of these branches to have affected different files at different times, this merge would simply just happen, however it is often the case that two branches will have changes to a single file. ‘Feature X’ set a variable to 1, while ‘Feature Y’ set it to 0. This requires the user (you) to go through file by file (sometimes line by line) and choose which version you want. The result is ideally a working final branch (say ‘Feature Z’, or ‘Feature XY’ depending on your naming conventions), however it is far more likely that you accidently delete the best parts of both merging branches. Merges are hell. Push To ‘push’ data to the server means that we are saving our changes to our data, and uploading it. See ‘commit’ for what is actually sent. Pull To ‘pull’ data means to retrieve the latest changes from the server. This represents its own dangers which I will go into momentarily. Commit A ‘commit’ is a packaged set of changes and data. If the user (you) has added data to the repository, it will contain a copy of this to add to the server’s data, and if any files have simply been changed or removed, the commit will contain a detailed record of the ‘diff’ of these files. It is these records which allow for us to recall ourselves to an earlier point. Staged / Not Staged We don’t add files to a commit directly. We mark all the files we want to package as ‘staged’. Git will stop tracking their changes until we do something with them like committing them, or unstaging them. This allows us to snapshot them at the time of staging. Then, we create a single commit out of all of our staged files. Diff A ‘diff’ is a function, or algorithm, that analyses two files and outputs the differences between them. This is most often performed between the server and the working tree. For example: File X on the server contains 3 variables, X = 0; Y = 1; Z = 2; File X in the working tree has the same 3 variables, but they are, X = 0; Y = 1; Z = 512; The ‘diff’ for these files will output //Z = 2; Z = 512 The two slashes (//) mean that this option has been discarded, or overwritten. This would occur in this case when the working tree is given priority (say we were pushing our changes to the server). Cloning This is the process of initially getting the data from the repository to bring it onto your machine for the first time. Used in setup. Processes When we use git, it is best to follow a strict series of procedures to minimise the risks of losing data, or overwriting a team members work. Setting up your repository When setting up a repository, there are certains concepts to take to make your life easier. They may seem trivial, but they can make all the difference in the world; trust me.
The first steps of setting up a repository is to create one. This may be done locally, but for the purposes of this instruction, we will be using GitHub (its far easier). GitHub is a company that allows free storage of all your work. ALL OF IT. Their only condition is that individual files don’t exceed 100MB, and that doesn’t happen very often. If it did, you could use the Git Large File System, (or Git LFS), but that costs money. STEP 1. Go to your web browser. Chrome or Firefox is best. Don’t use Internet Explorer. STEP 2. Navigate to https://github.com/ . STEP 3. If you have an account, sign in. If not, make an account. The ‘Sign In’ and ‘Sign Up’ buttons are in the top right corner STEP 4. Once you have made your account (I’m leaving that part with you), you will be on your dashboard. To the left, there is a panel for all your existing repositories. To the right there is a ‘discovery panel’ to find other peoples cool work. In the bottom middle, we have news about people you can follow (GitHub is a programmers FaceBook.) Where you want to focus is the upper centre, on the “start a project” button. Click it. STEP 5. Name it. Name it WELL. You can’t have spaces, but you can use dashes. Good example: Name-of-my-project Bad example: RanDomSetofWordsandcApitalisation STEP 6. Describe it. You don’t have to. I don’t. Feel free to skip if you want. STEP 7. Public or Private. A ‘public’ repository is one that can be seen by everyone. Like a photo on Instagram. This is useful for opensource projects (projects that a lot of random people collaborate on), and it is the bread and butter of how GitHub was founded. You can download the code from Microsoft Calendar from GitHub, open source is amazing. A ‘private’ repository is one that only you, and people you invite, can see and change. This is good if you are shy, private, under NDA or just shady. I use it a lot for my personal work, and work I do for contracts. Choose one! STEP 8. Add a .gitignore. Projects come with a lot of files. I use Unity3D a lot, and for every file, unity generates a .meta files. That isn’t to mention the thousands of library files which are consistently regenerated and have negligible effect on the project. So, sometimes we just want to ignore a file or two. Or a thousand. Your .gitignore will decide this. There are tons to choose from, depending on what you are working on. I use the Unity gitignore, which ignore library files, and all root files that aren’t /Assets/. Please note, you can just leave this empty! This will still generate a .gitignore file for your repository, and you can always add to it later. STEP 9. Add a license. This harkens back to the whole ‘open source’ side of GitHub. All of the licenses available to choose mean that you are consenting for others to take your work. If you choose not to assign a license, then copyright law comes into play and no-one can use it. GitHub seems to treat this as being nasty, but I very rarely make my work opensource. STEP 10. Click Create. Yay! Cloning Your Repository When it comes to actually getting access to your data there is two levels.
You can probably tell the I favour High level. I used Low for many years, and they are characterised by: “Did it finish? I can't tell. God I hope I didn’t delete that. I suppose I will just keep going and hope for the best?”. This is opposed to High Level, which is characterised by: “Ahh bugger it broke. Oh, I just forgot a comma. God this takes a long time, good thing I actually have a loading bar to see where its at. Cool done, I can now comfortably move onto continuing my work. “ Cloning to Low Level If you just ignored my amazing recommendation, then Low Level it is. To interact with Git without having to use actual commands, or a terminal, we can use a Git GUI, or ‘Graphical User Interface’. In laymans terms; they made a program for it. Its pretty. You have a few to choose from. GitHub Desktop has a lot of useful hookins with the main GitHub servers, but it doesn’t handle large batches of files well. I once had 30,000 changes. I had to use the terminal. You can also use Sourcetree. Sourcetree was developed by Atlassian, who also developed BitBucket; another Git provider. Of the two choices, I prefer Sourcetree as it has a bit more freedom and feedback. It also has quite good support and documentation. For the purposes of this tutorial, we will be using GitHub Desktop as it’s a bit faster initially. You can look up many tutorials for Sourcetree online if that’s your go. STEP 1. Go to your web browser, navigate to https://desktop.github.com/. STEP 2. Download it. It should be available for Windows, Mac AND Linux, so I don’t see where you’re gonna get stuck here. Once the download finishes, install it as you would any other program. STEP 3. Navigate back to your GitHub dashboard (which I hope is still open in another tab). If its not, just log into GitHub online and navigate to it through the left hand repository panel. Once you are at your repository, you will see one of two things: A “quick setup” heading, with a ‘Set up in Desktop’ button. Click it. A repository page with ‘Clone or Download’ in green in the top left. Click it, then select ‘Open in Desktop’ STEP 4. Once the program opens (you may need to give it permissions in browser, don’t worry it’ll ask you), you will see a ‘Clone a Repository’ box. In this we see two input boxes. The first has the path to your repository on the GitHub server. The second has the location on your computer where you want to store your project. I recommend changing this, the default is always awful. Once you have done so, click “Clone”. It is worth noting that if you knew the URL of the repository, you could simply copy and paste it into this box without having to use the browser to open GitHub desktop. STEP 5. Good job! Follow on if you want to see how to interact with the repository from here. Cloning to High Level I feel that I should say that ‘Low level’ and ‘High level’ are not terms widely used through Git. I use them because they are commonly used in game development to refer to Low and High level API (LLAPI and HLAPI). If you are talking to a Git tech and say Low level he will look at you funnily. That being said, I’m going to keep using them. Cloning, and interacting with, a repository in High level means we will be using the terminal almost exclusively. Because we are not using a GUI, this means we don’t actually have git on our computers yet! Lets remedy that. STEP 1. In your web browser, navigate to https://git-scm.com/download/win. Then, download the appropriate installer (it may start an auto download, if so, lucky you!). STEP 2. Once you have that, run the .exe you just downloaded. As you go through the install, you will reach a ‘components’ page. You want to select
Choose your text editor. Vim is the default. Don’t get Vim. What ever you do, DO NOT GET VIM. If you are reading this instructional paper, that means you are somewhat inexperienced. Vim will devour you whole. I know what I’m doing and Vim will devour me whole. I don’t even know how to close it for gods sake. I recommend Notepad++, as it’s a highly intuitive and malleable text editor that can be used for more than 20 different programming languages. STEP 4. Adjusting the PATH environment. The PATH (caps intentional), is a variable in the registry of your computer that is a list of folders. These folders are registered with the terminal, and if the folder is in your PATH, that means that you can run commands from them without having to be in them. For example, it means we can type ‘git’ in command prompt, and instead of saying ‘git doesn’t exist’ , it will try and run a git command. The danger (theres always a danger), is that if you link too many folders to PATH, you may end up with conflicting commands. It hasn’t happened to me yet, so be sure to let me know what happens, that sounds interesting. Coming back, I recommend selection ‘git from the command line’. This will allow you to use git natively on the computer, and wherever you want. STEP 5. Just click next for HTTPS backend, we aren’t using that. As a brief explanation, SSL certificates are files filled with jumbled letters and numbers. Those letters and numbers are then run through an encrypter with a ‘key’ (password), so that they are even more jumbled. This allows us to give our jumbled jumble to the repository. Then, when we want to interact with it, we have to send it our original jumble and the key, so it can see if we’re legit. You can see why we aren’t using it. Lose the key, or lose the jumble, you are permanently locked out. STEP 6. Line-endings matter when you have to transfer files from a mac to a pc, to linux and back. They each format files differently. Select the first option, as it will give you the windows format when you need to access it, but convert it to a basic/universal format when you upload it. STEP 7. Use MinTTY, default console is awful. STEP 8.
Yay for install! STEP 10. We now have git. Now, we need to clone our repository. Click start (on your keyboard or computer), and type in ‘CMD’. Right click on command prompt when it appears and say ‘Run as Administrator’. If you don’t run as admin, everything may go smoothly. However, it is my experience that it will break right as you go to do the most important push of the day. ‘You do not have correct system permissions for this command’. STEP 11. In CMD, type ‘git --version’ (make sure its 2 dashes). If you installed git correctly, you should now get an output of: ‘git version x.xx.x.windows.x’. Mine is ‘git version 2.21.0.windows.1’, but depending on when you do this tutorial that will change. STEP 12. Once we have confirmed we are installed, we need to navigate to the folder we want to store our repository in. So, in your file explorer, create the file, and note the path. E.g, “C:/Users/Peter/Documents/MyRepository/” Then, type this into CMD (replace my path with yours): cd C:/Users/Peter/Documents/MyRepository/” cd is a command to relocate the focus of CMD to the file you entered. This means we wont have to keep typing it in. STEP 13. If you navigate back to your repository page in the web browser, you will see a set of instructions to do so. I will paste here for convenience: echo “# ProjectName” >> README.md git init git add README.md git commit -m “first commit” git remote add origin https://github.com/[YourUserName]/[YourProjectname].git git push -u origin master I am going to explain what we are doing here.
Step 13 was heavy. Take a breather. STEP 15. You have now cloned a repository. Hooray! STEP 16. But what if you already had a repository that was initialised and on the server, and just wanted to download it? Say, you friend was using it, and you wanted to get in on it? Step 1-12 still apply, but instead of step 13, you should instead run: git clone https://github.com/[OwnersUserName] /[Repositoryname] So, you find the server, and git handles the rest. Beware, the repository will be downloaded into whatever folder the CMD is currently focused on. Use ‘cd’ to move to somewhere else if needed. Using Your Repository – Basic (Low Level)Basic mechanics is how I refer to:
STEP 1. Have GitHub Desktop (henceforth referred to as ‘the GUI’) open, focused on your repository. STEP 2. Open file explorer, and navigate to your repositories folder. If there are no files or changes to your repository, there may be a link to this in the GUI. STEP 3. Right click in the root (top level folder) of your repository. Click New -> Text Document. Name it. Im calling mine ‘Fergalicious.txt’. STEP 4. Open your text file, and make a change. Mine reads: ‘definition: make them boys go loco’. STEP 5. Save text file. Congratulations, you did a thing! Of course, were this your actual work, it wouldn’t have to be a text file. GitHub supports literally all files, including pictures (.png, .svg, .jpg), audio (.ogg, .wav, .mp3), videos (.wmv, .mp4) and even custom file formats (I use .dracon files to store player save games). STEP 6. Now we want to upload it. Open the GUI back up. A number have things will have changed. That number is 3.
The left hand panel is a congregation of both stages and unstaged files in the working tree. They have all had changed made to them, but usually you want to cherry pick what changes you are uploading. You do this by ticking the checkbox next to the file to upload. Make sure your file is checked. STEP 8. Down the bottom, next to your little profile pic, put a name for your commit. Mine is called ‘Create Fergie text’. Write a description if you are so inclined. A warning; you will never be so inclined. Not after you have done this 500,000 times. But when you get to a professional level with this, your relationship with the people around you will hinge on how good your descriptions are. Make it quick, sharp and relevant. ‘I added a text file to store lyrics from the greatest song ever made’. Finally, click ‘Commit to master’. STEP 9. Many people make the mistake of thinking that you just uploaded your work to the server. You didn’t. What you just did is get your work ready to make its trip. You packaged it up, got a stamp, put your name on it, and now its waiting on the bench. Up the top, you will see a button called “publish branch”. This is somewhat anomalous as this is the only time that will ever say that. Once you make the first change, your branch is ‘published’ and it will change. Click it. STEP 10. After some steps, feel proud. You have uploaded your work to the server. Fergie will live forever. STEP 11. Some notes. That publish button? It will now say one of 3 things;
Using Your Repository – Basic (High Level)Basic mechanics is how I refer to:
As these are the High level instructions, we will be using the command prompt to do so, and I will assume you have installed git and already initialised your repository (see ‘Cloning to High Level’) STEP 1. First things first, lets upload some work. Open the file explorer, and navigate to your project folder. STEP 2. Right click, and select New -> Text Document. Name it. Im naming mine – “WeAreTheChampions” STEP 3. Open said document, and write something in it. E.g. “My frieeeeendsssss” Save document. STEP 4. Open your CMD back up. Make your it is focused on the project folder cd C:/Users/MyUsername/Documents/MyProjectPath STEP 5. We need to stage it the file to ready it for packaging. We can do this 2 ways;
The difference between these is that the first will stage literally every single file in your project, whilst the second will stage only that file. A noteworthy note is that GIT supports ‘wildcards’. These are expressions within windows for describing paths. They allow us to add a ‘*’, which translates to … anything. So, if you say, git add *.png It will add every single png file to the staged area. If you said, git add /MySubFolder/* It would add every single file in that sub folder. Although, GIT also just supports standalone filename there, so there star becomes unnecessary. Also note, git add is not verbose, so if there are no errors, you did good. If you get antsy, just add a ‘-v’ to your command, and it will tell it to let you know whats going on. E.g git add -A -v STEP 6. Once you have added the file, we need to commit it. We can do this by typing, git commit -a -m “my message” This tells GIT to package all ‘staged’ files into a commit (-a means all). Then, we label the commit with a message (-m for message, whatever is in the parentheses after that is the message). If we wanted a bit more control, we could run this without the message, git commit -a This would open our text editor (notepad++), where we would type our message. Once we save and exit, git would detect the change and use that as the message. STEP 7. Time to upload. git push –progress – all *That’s two dashes before progress and all (curse you MSWord formatting!) General rule is that if its a letter (-m -a -w -r -v), use one dash, if its a word (--verbose, --all, --progress), use two. This tells git to get all our commits, and send them to the server. I am including the –progress as it will create a bar to let you know how long is left. That doesn’t matter much now, but big pushes take big times. STEP 8. You did it! Look at you go, you hacker, you! STEP 9. Let’s say you let your mate have access to the repository, and he uploads a file. To retrieve his changes, you need to do two things. STEP 10. First, check the status. No use trying to download a non-existent file. To see the current state of things in the console, type in git status You can add the –column tag to that (2 dashes), if you want the results to be formatted a bit neater. STEP 11. You can now see your friends file (If you cant, keep pulling, or he mucked up. One or the other). You can grab it by using git pull This will grab all the server stuff and bring it on down to you. You can test this locally by deleting the text file we made before. As long as we don’t push its deletion, the server will see a difference between us and it, and offer us the file back (yep, if God exists, this is his final form right here). So, read the next step to get it back STEP 12. If you make a change to a file, and want to undo it (adding a line, deleting it, renaming it, etc), you can do this by “checking out” the file from the server. This is more like supermarket check out, not creepy old man checking out your mum. Let’s say I did ‘git status’, and I get output of, deleted: WeAreTheChampions.txt Well that’s not good enough. Lets get that back. Type in Git checkout WeAreTheChampions.txt (although you should use your file name, it works better that way). Check your folder, and its there! STEP 13. Profit? Beer? Pride in yourself as a continuously growing individual who has gone out of their way to find and learn a new skill which benefits not only themselves, but potentially everyone in their professional sphere of influence? Beer it is!
0 Comments
Like many things worth doing, writing is an endeavour. It seems that whilst words can flow through the keyboard, concepts and ideas get lost upon their way to the paper. I was reading continually as a child, and as I developed, I focused on my ‘voice’ as a writer. It seems that now I am older, I have a voice, but no meaning.
Narratives often seem vague and unoriginal, essays meander through endless paragraphs saying almost nothing. “Concise” is a term imagined in a dream, where people speak simply and accurately. I ask myself, “Why can I write writhing rings of reckless rambles but not simply state my case?”. In short: I have trouble writing concisely. And yet I enjoy the flourishes of my writing. It is akin to my game development, a tool to create and maintain a world hitherto unthought of. It stream of consciousness that imparts my mind at the time of writing, filled with dreams of grandeur. And I know that when I look at this in a few days, I will find my writing alien, to even myself. It is probably why I find essays to be such obstacles to my progression. I have been taught that there is no place for filigree in an essay. Say the truth, prove the truth, and move on to the next point. There is a place for the simplicity involved there, but I haven’t found it yet. I take my essays, I refine them and grind them. I snip pieces from every branch and cultivate it in the hopes that it will suffice. I often submit the literary equivalent of a gargantuan thorny rosebush. And now I direct my attention toward these very words. A paradox of sorts, an examination of my own writing. So many questions to answer, and each answer sprouts more questions. In writing in this manner, I have chosen to relax, and let my writing flow in the most “me” way that I can. Is this a mistake? Should I have attempted to refine an area that I find difficult? I suppose I will find out. I am not that good at relaxing… Let us answer a question then. “Do you write with an audience in mind?”. I do, but not the actual audience. Whilst I do have the knowledge that this will be read by my peers and lecturer in my mind, I write for an imaginary audience. The perfect audience that no author ever had. They sit, and read, and absorb that which I put forth with little judgement passing that upon my grammar, or a particularly dense phrase. Simultaneously, I write for an empty auditorium. As a reader that visualises scenes more than studying the individual words, I tend towards the same when writing. Thus, I hear my own voice, albeit, a more resonant and timbred sound than ever left my mouth. It echoes within the chambers of my consciousness, and maybe this is why I tend towards grandeur, toward writing patterns that reek of pomposity and conceit. When they are rendered in that tone, they sound even, measured and fair. It is this sound that I strive to impart. Do I write with an audience in mind? Yes. I write for the audience that is my mind. Thus, I write of forests made luscious with life. Of canyons that reek of heat, with dry and dusty wind. I speak of the floating isles, in the sky or in the sea. And I visualise them, and I write for my own audience. Because I know of no way to ever convey this to my reader, save that the reader is myself. Would that I could describe a mans face with a sufficient amount of metaphorical statements, that you could visualise him. Stocky and lean, a soldier worn by years. His stubble peeks through skin made dark by crackling mud. Wild hair made tame by a leather band, like the wild man made tame by a leather will. In is my earnest desire that you see him. His face, his stance. Desperately unyielding, in the way of one that knows that he only has so many years before his defiance is taken from him, before he is made a mockery of health. The tender balance between cherishing your remaining years, and dreading those to come. Yet he stands, proud, made strong by the years that have already passed. What is my writing. My writing is the creation of worlds. My writing is the connection of shared ideals. My writing is the futility of an outstretched hand that does not know how to grasp. Peter Carey This first week is "Writing about Writing". The task instructions are as follows:
Write about how you write. Is writing easy or difficult? Why do you like/ hate it? Do you design a structure first or is it emergent? Do sentences arrive fully formed or do you shape them in subsequent edits? What subjects do you enjoy writing about, what subjects are a guaranteed writer's block? Do you write with an audience in mind? Writing is a kind of enquiry (Armstrong & Wilson, 2014) in which topics can be explored, uncovered, and arguments and ideas developed. As you write and rework your writing to better express your ideas, notice if your ideas about writing change or evolve. Carroll, J. A. & Wilson, E. E. (2014). The critical writer: Inquiry and the writing process. Santa Barbara, California: Libraries Unlimited. Hello again!
We arrive at the beginning of a new trimester, and a new unit. This tri, "Research and Writing". As my reader, I feel that you will enjoy this, or at least benefit. Increased writing skills on my part can only make this process better! In this unit, I will be looking at a variety of writing styles, including descriptive, instructive and referential. I will be doing 5 small "writing assignment" blogs, followed by a big boy mega blog. For this unit, I am changing up my style a bit. This is influenced by a few factors:
I will label them both clearly, so that if you don't really care about the task, or my response, you can navigate quickly to that which you actually mean to view. Week 1 will be posted momentarily, enjoy! Peter Carey
|
AuthorPeter Carey. Game Developer, STEM Education Provider, Dracon Interactive Founder Archives
March 2019
Categories |
RSS Feed
Location |
|