|
| 1 | +Git Instructions: |
| 2 | +----------------- |
| 3 | + |
| 4 | + For those who think git might be a bit too complicated to deal with, |
| 5 | + here are (I think) the minimal commands. See the "SUDO" section in |
| 6 | + README.sudo for ideas to make updating Xastir even simpler. |
| 7 | + |
| 8 | + |
| 9 | +USERS: |
| 10 | +------ |
| 11 | + |
| 12 | + Initial Copy (Git Clone): |
| 13 | + ------------------------- |
| 14 | + |
| 15 | + 0) Make sure git is installed on your system. |
| 16 | + |
| 17 | + 1) Run |
| 18 | + git config --global user.name "Your Name" user.email " [email protected]" |
| 19 | + |
| 20 | + The above is not strictly necessary, but if you ever try to make changes |
| 21 | + to Xastir and get them integrated with the project it is important. |
| 22 | + |
| 23 | + NOTE: If you already have a different git global config, you can create |
| 24 | + a local config for a particular repo by going into that repo and doing: |
| 25 | + git config --local user.name "Your Name" user.email " [email protected]" |
| 26 | + |
| 27 | + Check the config by: |
| 28 | + git config --local -l |
| 29 | + git config --global -l |
| 30 | + git config -l # Doesn't differentiate between global and local though! |
| 31 | + |
| 32 | + 2) Go to <http://github.com/Xastir/Xastir> to access the project page. |
| 33 | + There you will find the URL of the git repository, just to the |
| 34 | + right of a button that says "HTTPS". Copy this URL to your clipboard. |
| 35 | + |
| 36 | + (At the time of this writing, the URL was |
| 37 | + <https://github.com/Xastir/Xastir.git>) |
| 38 | + |
| 39 | + 3) Open a shell, navigate to a directory where you want to store |
| 40 | + the Xastir source code, and enter this command: |
| 41 | + |
| 42 | + git clone https://github.com/Xastir/Xastir.git |
| 43 | + |
| 44 | + This will create a clone of the Xastir git repository in an |
| 45 | + "Xastir" subdirectory of the current directory. |
| 46 | + |
| 47 | + All done! You now have the latest development sources on your computer. |
| 48 | + Not only that, you have a complete copy of the entire project history |
| 49 | + and access to all prior releases. |
| 50 | + |
| 51 | + |
| 52 | + Updating Your Copy: |
| 53 | + ------------------- |
| 54 | + |
| 55 | + cd Xastir |
| 56 | + git pull # Update your local repo (May be dangerous for developers) |
| 57 | + ./bootstrap.sh |
| 58 | + mkdir -p build # Build in a separate directory |
| 59 | + cd build |
| 60 | + ../configure |
| 61 | + (make clean;make -j3 2>&1) | tee make.log |
| 62 | + sudo make install # "make install-strip" can be used after the first |
| 63 | + # time: It removes debugging info from executable |
| 64 | + sudo chmod 4555 /usr/local/bin/xastir # Only needed if using kernel AX.25 |
| 65 | + xastir & # Start it up! |
| 66 | + |
| 67 | + Note that you'll need autoconf 2.53 or newer and automake 1.6.3 or newer |
| 68 | + in order to run the "./bootstrap.sh" script. |
| 69 | + |
| 70 | + -or- |
| 71 | + |
| 72 | + Bypass all of the commands above and just type: |
| 73 | + cd Xastir |
| 74 | + ./update-xastir |
| 75 | + |
| 76 | + |
| 77 | +DEVELOPERS: |
| 78 | +----------- |
| 79 | + |
| 80 | + Initial Checkout: |
| 81 | + ----------------- |
| 82 | + |
| 83 | + HTTPS Method: |
| 84 | + git clone https://github.com/Xastir/Xastir |
| 85 | + |
| 86 | + -or- |
| 87 | + |
| 88 | + SSH Method. Add keys to GitHub and then: |
| 89 | + |
| 90 | + git clone [email protected]:Xastir/Xastir |
| 91 | + |
| 92 | + Note that using the SSH method means that you won't have to answer the |
| 93 | + popups for user/password each time you do anything with the remote repo, |
| 94 | + although you will have to enter a passphrase if you added a passphrase to |
| 95 | + your SSH key. The SSH method is highly recommended for active developers! |
| 96 | + |
| 97 | + |
| 98 | + Normal Development Flow: |
| 99 | + ------------------------ |
| 100 | + |
| 101 | + A pull before committing can be dangerous, if there are substantial |
| 102 | + conflicts between your work and others (not very likely with Xastir, but |
| 103 | + definitely likely in bigger projects). It is much better to do a fetch |
| 104 | + (which pulls down changes from the remote but DOESN'T merge them into your |
| 105 | + tracking branch), then look at what changed upstream, and then either a |
| 106 | + merge, rebase, stash/pop, or something else depending on the level of |
| 107 | + conflict you see. See README.GIT. |
| 108 | + |
| 109 | + Doing a pull before starting your own work is reasonable, but if someone |
| 110 | + pushes while you're working (again, not very likely with Xastir), you can |
| 111 | + still wind up with really ugly history, with weird merge commits and |
| 112 | + undesired branching. |
| 113 | + |
| 114 | + On the other hand, if you replace "git pull" with "git pull --rebase" in |
| 115 | + that recipe, with the caveat that sometimes you might have to be more |
| 116 | + careful and that you need to understand what you're doing, a lot of the |
| 117 | + danger of the simple git pull can be avoided. |
| 118 | + |
| 119 | + We will often be working on a branch for development, then merging that |
| 120 | + branch with the trunk when that feature or bug-fix is ready for prime-time. |
| 121 | + |
| 122 | + Commit your work to your LOCAL repo: |
| 123 | + |
| 124 | + - First add all desired changes to the staging area: |
| 125 | + git add <file1> <file2> <file3> ... |
| 126 | + |
| 127 | + - Then commit your staged changes to your local repo |
| 128 | + |
| 129 | + git commit |
| 130 | + |
| 131 | + Push your local repo changes up to GitHub when you are ready to |
| 132 | + publish them: |
| 133 | + |
| 134 | + git push |
| 135 | + |
| 136 | + |
| 137 | + Important: Git Commit Message Format |
| 138 | + ------------------------------------ |
| 139 | + |
| 140 | + Git commit messages need to be in a certain format to make the best use |
| 141 | + of the "git log" commands. In particular the first line needs to be 50 |
| 142 | + chars or less, then a BLANK LINE, then a detailed commit message. See |
| 143 | + this link for more info: |
| 144 | + |
| 145 | + http://chris.beams.io/posts/git-commit/ |
| 146 | + |
| 147 | + |
| 148 | + Checking Out A Branch: |
| 149 | + ---------------------- |
| 150 | + |
| 151 | + All branches associated with the Xastir project are contained in the clone |
| 152 | + you made earlier. You can switch your current working directory to |
| 153 | + one of those branches easily: |
| 154 | + |
| 155 | + cd Xastir |
| 156 | + git fetch (this updates your local repo copy from github, but doesn't |
| 157 | + merge changes into your working tree) |
| 158 | + git checkout <branch name> (this switches all the files in your working |
| 159 | + tree to match those in the branch) |
| 160 | + git merge (This makes sure that all the changes that |
| 161 | + may have happened upstream on that branch |
| 162 | + get into your copy) |
| 163 | + |
| 164 | + You do not have to do this in a new directory --- so long as |
| 165 | + you haven't changed any files in the source tree, git checkout |
| 166 | + automatically swaps out all files it knows about with versions from the |
| 167 | + branch. |
| 168 | + |
| 169 | + If you really want to keep more than one branch's code around to work on, |
| 170 | + you can do that if you have git version 2.5 or later with the following |
| 171 | + commands: |
| 172 | + |
| 173 | + cd Xastir |
| 174 | + git worktree add <path> <branchname> |
| 175 | + |
| 176 | + This will create a new directory tree called <path> with the named |
| 177 | + branch checked out into it. |
| 178 | + |
| 179 | + In early 2018, there is only one active branch, the master branch, |
| 180 | + and we will be performing releases by creating release branches. |
| 181 | + |
| 182 | + There are many more git commands and options. Many of them are more of |
| 183 | + use to the developers. Some of those are listed below. The above should |
| 184 | + be enough for most people to keep their copies in sync with the latest git |
| 185 | + development sources. |
| 186 | + |
| 187 | + |
| 188 | + If Using Multiple GitHub Accounts: |
| 189 | + ---------------------------------- |
| 190 | + |
| 191 | + You may have trouble getting your commits attributed to the correct GitHub |
| 192 | + login. GitHub uses the username/email in your git config settings for |
| 193 | + attribution. If it is wrong, you may have to do some of the below in order |
| 194 | + to set a LOCAL username and email for the one repository. |
| 195 | + |
| 196 | + The user.name and user.email are pulled from the global git config, but a |
| 197 | + local git config inside each repo will override those settings. |
| 198 | + |
| 199 | + Go to root of checked-out repo and set local user.name and user.email for |
| 200 | + this repo: |
| 201 | + |
| 202 | + git config user.name <github username> |
| 203 | + git config user.email <email address> |
| 204 | + git config -l # Shows both local and global settings, hard to tell which is which |
| 205 | + git config --global # Shows global settings |
| 206 | + git config --local -l # Shows local repo configs, so should show new settings |
| 207 | + |
| 208 | + Another method (but more error-prone) of editing local/global git config is: |
| 209 | + |
| 210 | + git config edit # Edit local config |
| 211 | + git config --global edit # Edit global config |
| 212 | + |
| 213 | + If new commits still aren't using the right email, make sure you have not |
| 214 | + set GIT_COMMITTER_EMAIL or GIT_AUTHOR_EMAIL environment variables. |
| 215 | + |
| 216 | + |
| 217 | + More Info: |
| 218 | + ---------- |
| 219 | + |
| 220 | + Make sure you know how git works. Read https://git-scm.com/book/en/v2 |
| 221 | + |
| 222 | + If you are very familiar with CVS, get used to working differently, because |
| 223 | + git is different. |
| 224 | + |
| 225 | + Read and understand http://chris.beams.io/posts/git-commit/ |
| 226 | + |
| 227 | + Read http://justinhileman.info/article/changing-history/ |
| 228 | + |
| 229 | + Read http://think-like-a-git.net/ |
| 230 | + |
| 231 | + Read "Visual Git Cheat Sheet" at http://ndpsoftware.com/git-cheatsheet.html |
| 232 | + |
| 233 | + Branching and merging in git is very simple, and is documented very well |
| 234 | + by all those links. We will not repeat it here. |
| 235 | + |
| 236 | + If you use SSH, set up your SSH keys on GitHub and do the "git clone" using |
| 237 | + the SSH path. This will save you having to put in your password each time |
| 238 | + you use the remote repository, although if you added a passphrase to your |
| 239 | + SSH key you'll have to enter that each time. |
| 240 | + |
| 241 | + Useful Git Commands: |
| 242 | + -------------------- |
| 243 | + |
| 244 | + Set up global user/email |
| 245 | + git config --global user.name "Your Name" |
| 246 | + git config --global user.email " [email protected]" |
| 247 | + |
| 248 | + Set up user/email for a local repository |
| 249 | + cd /path/repository |
| 250 | + git config user.name "Your Name" |
| 251 | + git config user.email " [email protected]" |
| 252 | + |
| 253 | + Configure Git's editor: |
| 254 | + git config --global core.editor /path/to/editor |
| 255 | + |
| 256 | + Colorizing Git output (set once and forget): |
| 257 | + git config --global color.ui auto |
| 258 | + |
| 259 | + Clone a repo: |
| 260 | + git clone http://github.com/Xastir/Xastir |
| 261 | + git clone https://github.com/Xastir/Xastir |
| 262 | + git clone [email protected]:Xastir/Xastir |
| 263 | + |
| 264 | + Status of local repo: |
| 265 | + git status |
| 266 | + |
| 267 | + Diff for a file: |
| 268 | + git diff <filename> |
| 269 | + |
| 270 | + See all branches, local and remote: |
| 271 | + git branch -a |
| 272 | + |
| 273 | + Visual Git viewer: |
| 274 | + gitk (tcl/tk and generic X11 viewer, comes with git) |
| 275 | + or |
| 276 | + gitg (gnome git viewer) |
| 277 | + |
| 278 | + Add files to the staging area: |
| 279 | + git add <file1> <file2> |
| 280 | + |
| 281 | + Commit changes to LOCAL repo: |
| 282 | + git commit # If have files in staging area already |
| 283 | + git commit <file1> <file2> # Ignores staging area |
| 284 | + |
| 285 | + Push local changes to remote repository: |
| 286 | + git push |
| 287 | + |
| 288 | + Update local repo from remote repo |
| 289 | + git fetch |
| 290 | + |
| 291 | + Update local repo and merge remote/local changes in local repo (May be |
| 292 | + dangerous for developers with modified code in their working tree): |
| 293 | + git pull |
| 294 | + |
| 295 | + Rebase local changes against latest master branch |
| 296 | + git fetch |
| 297 | + git rebase master |
| 298 | + |
| 299 | + |
| 300 | +------------------------------------------------------------------------ |
| 301 | +Copyright (C) 2000-2018 The Xastir Group |
| 302 | + |
| 303 | + |
0 commit comments