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