├── samplea.txt ├── sampleb.txt ├── README.md └── stash_git_tutorial.md /samplea.txt: -------------------------------------------------------------------------------- 1 | sample file A 2 | -------------------------------------------------------------------------------- /sampleb.txt: -------------------------------------------------------------------------------- 1 | sample file B 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # stash_git_tutorial 2 | stash git tools tutorial 3 | -------------------------------------------------------------------------------- /stash_git_tutorial.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | [StaSh](https://github.com/ywangd/stash) comes with a few tools for working with git repos. This tutorial will cover a few basic workflows for dealing with git repositories in stash/Pythonista specifically. It helps to be familiar with git commandline tools, although the git in stash is missing a great many features that you might be used to. 3 | 4 | ## Creating a repo from scratch 5 | You have a new idea for a project. Maybe you have some cool code you'd like to share. Fire up stash, and let's begin. 6 | 7 | There are a few basic options when creating a new work. First is to create a local git repo, and work locally. When you are ready to publish, you would create a bare github repo, then push to it. Second is to create the github repo first, clone it back locally, and then start adding files. The first method takes a few extra steps, but is more appropriate when you already have files created. 8 | 9 | Let's start by creating the github repo, using the `gh create` command. First let's review the help: 10 | 11 | ```bash 12 | [~/Documents]$ gh create --help 13 | Usage: gh create [options] 14 | 15 | Options: 16 | -h, --help This message 17 | -s , --description Repo description 18 | -h , --homepage Homepage url 19 | -p, --private private 20 | -i, --has_issues has issues 21 | -w, --has_wiki has wiki 22 | -d, --has_downloads has downloads 23 | -a, --auto_init create readme and first commit 24 | -g , --gitignore_template create gitignore using string 25 | ``` 26 | 27 | To create a bare repo, use `gh create `, otherwise for auto init, use `gh create -a `. Let's create a basic repo with downloads, issue tracker, and autoinit. 28 | 29 | ```bash 30 | [~/Documents]$ gh create -aid -s "stash git tools tutorial" stash_git_tutorial 31 | Created https://github.com/jsbain/stash_git_tutorial 32 | ``` 33 | 34 | Now, magically, a github repo named stash_git_tutorial has been created. Since we used auto init, the repo has a Readme.md file created, and the first commit. 35 | 36 | Let's pull this locally so we can start working. 37 | 38 | ## Cloning a repo 39 | We have a repo, let's clone it. A few gotchas to watch out for: the url should be of the form either an ssh:/git@github.com/owner/repo.git, or https://github.com/owner/repo.git. A later chapter will discuss how to setup ssh (I totally reccommend it, since the http implementation in dulwich seems to not always play well with github.). Don't forget the **.git** extension! 40 | Also, don't forget the second argument to clone, which is the folder to clone to. Leaving it blank will try to clone to the current folder, which is fine if you have alreeady created and cd'd to a folder, but only causes problems if run from ~/Documents. 41 | 42 | ```bash 43 | [~/Documents]$ git clone https://github.com/jsbain/stash_git_tutorial.git git_tutorial 44 | [~/Documents]$ cd git_tutorial/ 45 | [git_tutorial]$ ll 46 | .git (374.0B) 2016-02-25 00:47:43 47 | README.md (46.0B) 2016-02-25 00:47:43 48 | ``` 49 | 50 | So now we have a copy of the repo on our local device. The .git folder is special, do not delete it. A future installment will talk a little about what is in here, since it can sometimes be useful to know a little about the plumbing for times when things go horribly wrong (as long as you don't delete this folder, even if you make a terrible mistake, your committed files are safe and can be recovered. dulwich never really does garbage collection, so objects in the repo will always be there. ) 51 | 52 | ## Adding some files, and our first commit 53 | Let's go ahead and create some files. I will go ahead and save this file to that folder. 54 | 55 | ``` 56 | [git_tutorial]$ ll 57 | .git (374.0B) 2016-02-25 00:47:43 58 | README.md (46.0B) 2016-02-25 00:47:43 59 | stash_git_tutorial.md (3.5K) 2016-02-25 01:00:58 60 | ``` 61 | The `git add` command is used to add a file to the "index". There are some good docs describing how git works, but the basic idea is this: you have a working copy of a folder structure -- basically the files that you see and can edit. Internal to git, there is another "folder" called the index, or staging area, where you can copy files to create a commit. The index is a temporary staging area, starts off containing whatever was in the last commit. When you commit, you create a permanent snapshot of what is in the index at that time. This act of copying to the staging area in git parlance is called `git add`, and `git commit` creates the snapshot which is then permanently stored. `git status` checks the index to see if it is up to date with the working copy. Let us add, then commit, and check status to verify we have added the file. 62 | 63 | ```bash 64 | [git_tutorial]$ git add stash_git_tutorial.md 65 | Adding stash_git_tutorial.md 66 | 67 | # let's check that the file was added 68 | [git_tutorial]$ git status 69 | STAGED 70 | add['stash_git_tutorial.md'] 71 | UNSTAGED LOCAL MODS 72 | [] 73 | 74 | #commit the file 75 | [git_tutorial]$ git commit 76 | Commit Message: Initial commit of tutorial 77 | Author Name: JonB 78 | Save this setting? [y/n]y 79 | Author Email: jsbain@[.....] 80 | Save this setting? [y/n]y 81 | e2a369919bc887bb79690420b5765d0ac525dd4d 82 | ``` 83 | 84 | The first time you commit to a repo in stash, it will prompt you to save author name and email so future commits need only the message. The commit message describes in a few words what the purpose of the commit is. The 20 digits spit out after committing is called the sha, which is basicslly a hash of everything in the staging area and the current time, author, and commit message info. 85 | Usually this gets truncated to 6-7 digits. 86 | 87 | Let's add a few more files to the folder, then add them to the repo. 88 | 89 | 90 | ```bash 91 | [git_tutorial]$ echo 'sample file A' > samplea.txt 92 | [git_tutorial]$ echo 'sample file B' > sampleb.txt 93 | 94 | 95 | [git_tutorial]$ git status 96 | STAGED 97 | UNSTAGED LOCAL MODS 98 | ['stash_git_tutorial.md'] 99 | 100 | [git_tutorial]$ git add * 101 | Adding README.md 102 | Adding samplea.txt 103 | Adding sampleb.txt 104 | Adding stash_git_tutorial.md 105 | 106 | [git_tutorial]$ git status 107 | STAGED 108 | add['sampleb.txt', 'samplea.txt'] 109 | modify['stash_git_tutorial.md'] 110 | UNSTAGED LOCAL MODS 111 | [] 112 | ``` 113 | 114 | Note that since I have been continuing to update this file as I write, the first git status shows me that I have uncommitted changes -- these are not stored anywhere yet, other than your working copy. I used git add with wildcards. After, status shows the new files, as well as the fact that this file is modified in the staging area, compared to the last commit. 115 | 116 | Sometimes it is useful to use `git diff` to remind yourself of the changes you have made. The [gitview](https://github.com/jsbain/gitview) program has a visual diff display which is somewhat easier to look at. 117 | 118 | ``` 119 | [git_tutorial]$ git diff 120 | diff --git /dev/null b/samplea.txt 121 | new mode 100644 122 | index 0000000..e8d2873 100644 123 | --- /dev/null 124 | +++ b/samplea.txt 125 | @@ -1,0 +1,1 @@ 126 | +sample file A 127 | diff --git /dev/null b/sampleb.txt 128 | new mode 100644 129 | index 0000000..80ad0f9 100644 130 | --- /dev/null 131 | +++ b/sampleb.txt 132 | @@ -1,0 +1,1 @@ 133 | +sample file B 134 | diff --git a/stash_git_tutorial.md b/stash_git_tutorial.md 135 | index fc18f02..b982ec5 100644 136 | --- a/stash_git_tutorial.md 137 | +++ b/stash_git_tutorial.md 138 | @@ -58,8 +58,28 @@ 139 | +The `git add` command is used to add a file to the "index" 140 | [...] 141 | ``` 142 | 143 | ``` 144 | [git_tutorial]$ git status 145 | STAGED 146 | add['sampleb.txt', 'samplea.txt'] 147 | modify['stash_git_tutorial.md'] 148 | UNSTAGED LOCAL MODS 149 | [] 150 | [git_tutorial]$ git commit "Added some files and caught up with tutorial" 151 | 8509bbf0116a29076099e3db5c0ba3e57b1d43d9 152 | ``` 153 | 154 | # Pushing back to github 155 | Finally, we want the world to see the great progress we are making. Time to push back to github. If you have cloned using the git clone module, git push will push the changes to origin. A later chapter will discuss remotes, how to add or change. 156 | 157 | ``` 158 | [git_tutorial]$ git push 159 | Attempting to push to: https://github.com/jsbain/stash_git_tutorial.git, branch: refs/heads/master 160 | Push to https://jsbain:********@github.com/jsbain/stash_git_tutorial.git successful. 161 | success! 162 | ``` 163 | 164 | # Setting up ssh keys 165 | In some cases, you may need or want to use ssh instead of https. This is a somewhat more reliable way of pushing, though it can be a little slower. This might also work for private repos. 166 | 167 | With guthub, the process is facilitated by the `gh` command in stash: 168 | ``` 169 | [git_tutorial]$ gh create_key stash 170 | ``` 171 | creates a key, and adds it to your github account. Note this command uses the stored github password, so you will have to create a key in your keychain, or better yet just use git push on an existing repo. 172 | 173 | If you are using a non-github ssh, bitbucket, etc, you can create an ssh key 174 | 175 | ```bash 176 | $ ssh-keygen -trsa -b2048 177 | pbcopy ~/.ssh/id_rsa.pub 178 | ``` 179 | 180 | creates a key, and copies the public key to the clipboard. You can then paste this into whatever you use for setting up the keys on the server. 181 | 182 | 183 | Next, we need to add a remote to an existing repo: 184 | ```bash 185 | [git_tutorial]$ git remote originssh ssh://git@github.com/jsbain/stash_git_tutorial.git 186 | ``` 187 | 188 | Now you can fetch/push,etc from originssh 189 | ```bash 190 | [git_tutorial] git push originssh 191 | ``` 192 | 193 | 194 | #TODO 195 | Future topics: 196 | 1) creating bare repos and pushing to gh 197 | 2) forking someone elses' repo 198 | 3) pull requests 199 | 4) branches 200 | 5) pulling, fetching and merging 201 | 6) multiple remote workflows 202 | 7) what to do when things go horribly wrong 203 | 8) reverting changes (git reset) 204 | --------------------------------------------------------------------------------